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

> Install the GPT-Image2 agent skill for Claude Code and Codex easily. Follow simple commands to integrate this powerful tool into your coding environment.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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:

```bash
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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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:

```bash
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:

```bash

# 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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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:

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

```

Each directory should contain:

- [`SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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:

```text
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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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.