How to Install the GPT-Image2 Agent Skill for Claude Code and Codex

Run npm run install:skill from the repository root to copy the skill into ~/.claude/skills and ~/.codex/skills, or specify claude-code or codex as arguments to target a single agent.

The freestylefly/awesome-gpt-image-2 repository provides a fully-defined GPT-Image2 agent skill that enables Claude Code and Codex to generate production-ready image prompts using a curated style library. This skill, located in agents/skills/gpt-image-2-style-library, includes a comprehensive SKILL.md definition and a JSON-backed template catalog. Installing the skill requires running a single Node.js script that copies the necessary files into your agent's skill directory.

What Is the GPT-Image2 Agent Skill?

The GPT-Image2 agent skill is a structured capability package that allows AI agents to interpret creative requests and output optimized prompts for OpenAI's GPT-Image2 model. According to the source code in freestylefly/awesome-gpt-image-2, the skill consists of three core components:

• Skill Definition: The SKILL.md file in agents/skills/gpt-image-2-style-library/ contains the human-readable workflow, language detection logic, and output format instructions.
• Data Catalog: The data/style-library.json file provides a JSON database of 500+ prompt templates, categories, style tags, and scene tags that powers the skill's template matching.
• Install Script: The scripts/install-style-skill.mjs Node script handles the deployment of the skill directory to one or more agent home directories.

Prerequisites

Before installing the GPT-Image2 agent skill, ensure you have:

1. Node.js installed (required to run the install script).
2. Git to clone the repository.
3. Claude Code or Codex installed, with their respective home directories already initialized (the script will create skills subdirectories if missing).

Installation Steps

Clone and Install Dependencies

First, clone the repository and install the Node dependencies:

git clone https://github.com/freestylefly/awesome-gpt-image-2.git
cd awesome-gpt-image-2
npm install

This installs the required runtime dependencies including Vite, React, and Supabase packages defined in package.json.

Run the Install Command

The repository exposes an npm shortcut that invokes the install script. To install the skill for both Claude Code and Codex simultaneously, run:

npm run install:skill

As implemented in scripts/install-style-skill.mjs, this command detects your home directory, creates the appropriate skill folders, removes any previous versions of the skill, and copies agents/skills/gpt-image-2-style-library to both ~/.codex/skills/ and ~/.claude/skills/.

Target Specific Agents

To install for only one environment, pass the target alias as an argument:

# Install only for Claude Code

npm run install:skill claude-code

# Install only for Codex

npm run install:skill codex

Omitting the argument defaults to "all", which installs the skill for every supported environment including the shared ~/.agents/skills directory.

How the Installation Works

Environment Variables and Paths

The install script determines destination roots using the following priority, as defined in install-style-skill.mjs:

• Codex: $CODEX_HOME environment variable, or falls back to $HOME/.codex/skills
• Claude Code: $CLAUDE_HOME environment variable, or falls back to $HOME/.claude/skills
• Shared Agents: $AGENTS_HOME environment variable, or falls back to $HOME/.agents/skills

The install-style-skill.mjs Implementation

The script scripts/install-style-skill.mjs performs four critical operations:

1. Path Resolution: It constructs the source path from agents/skills/gpt-image-2-style-library and resolves the target path based on the environment variable or default home directory.
2. Directory Creation: It ensures the destination directory exists, creating missing parent folders recursively.
3. Cleanup: It removes any existing gpt-image-2-style-library directory in the target to prevent file conflicts.
4. Copy Operation: It recursively copies the entire skill folder, preserving the SKILL.md definition and any assets/ subdirectories.

After copying, the script emits a confirmation message indicating the absolute path where the skill was installed.

Verifying the Installation

After running the install command, verify the skill exists in your agent's skill directory:

ls ~/.claude/skills/gpt-image-2-style-library/
ls ~/.codex/skills/gpt-image-2-style-library/

Each directory should contain:

• SKILL.md — The skill definition and workflow
• assets/ — Supporting files and templates
• Any helper configuration files

Using the Skill in Prompts

Once installed, Claude Code and Codex automatically discover the skill. Invoke it using natural language in your prompts:

Use the gpt-image-2-style-library skill to generate a city-life system map.

The agent will execute the workflow defined in SKILL.md:

1. Detect the input language (Chinese or English).
2. Identify the target output type (e.g., poster, illustration).
3. Match the request against categories and tags in data/style-library.json.
4. Return a production-ready GPT-Image2 prompt with relevant template IDs.

Summary

• The GPT-Image2 agent skill resides in agents/skills/gpt-image-2-style-library and includes a SKILL.md definition plus JSON template data.
• Run npm run install:skill to deploy the skill to ~/.claude/skills and ~/.codex/skills simultaneously.
• Pass claude-code or codex as arguments to target specific agents, or set CLAUDE_HOME / CODEX_HOME environment variables for custom installation paths.
• The install script at scripts/install-style-skill.mjs handles directory creation, cleanup, and recursive copying of the skill files.
• Once installed, agents automatically load the skill and can generate optimized GPT-Image2 prompts using the curated style library.

Frequently Asked Questions

Can I install the skill for only Claude Code or only Codex?

Yes. Pass the target name as an argument to the npm script. Use npm run install:skill claude-code to install only for Claude Code, or npm run install:skill codex for Codex only. Omitting the argument installs for all supported environments by default.

What if I use a custom home directory for my AI agents?

Set the appropriate environment variable before running the install command. Define CODEX_HOME for Codex, CLAUDE_HOME for Claude Code, or AGENTS_HOME for shared agent directories. The script checks these variables before falling back to the default $HOME/.codex/skills or $HOME/.claude/skills paths.

How does the skill work once installed?

The skill provides a structured workflow defined in SKILL.md. When you reference the skill in a prompt, the agent reads this definition to detect language, identify output types, and match your request against the data/style-library.json catalog. It then composes a production-ready prompt optimized for GPT-Image2, including relevant template IDs and style tags.

Where is the skill definition stored?

The canonical skill definition lives in agents/skills/gpt-image-2-style-library/SKILL.md within the repository. During installation, this entire directory is copied to your agent's skills folder (e.g., ~/.claude/skills/gpt-image-2-style-library/SKILL.md), allowing the agent to load and execute the workflow locally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}