v1.1.0 to git:20260331.7c00a2d

85 added, 234 removed. Audit A to A.

---

name: agent-skill-builder

- description: Creates new Claude skills or translates ChatGPT projects into Claude skills. Use when the user wants to create a skill, convert a ChatGPT project, migrate prompts to Claude, or set up a new slash command.

- version: "1.1.0"

+ description: "Quickly creates new Claude Code skills or translates ChatGPT projects into Claude Code skills. Handles skill scaffolding, frontmatter, directory structure, and ChatGPT-to-Claude migration. Use when the user wants to 'create a skill,' 'make a new slash command,' 'convert a ChatGPT project,' 'translate a GPT to Claude,' or 'migrate prompts to Claude Code.' For full eval/testing/benchmarking workflows, use skill-creator instead."

argument-hint: "[new|translate] [skill-name or ChatGPT-project-name]"

---

# Agent Skill Builder

- Creates new Claude skills from scratch or translates ChatGPT projects into the Claude skill format.

- ## Trigger Conditions

- Invoke this skill when the user:

- - Wants to "create a skill" or "make a new skill"

- - Wants to "translate a ChatGPT project" or "convert a ChatGPT Project to Claude"

- - Mentions "migrate prompts" or "convert ChatGPT project"

- - Asks about "slash commands" or "custom commands"

- - Says "create a /command" or similar

+ Quickly scaffolds new Claude Code skills or translates ChatGPT projects into Claude Code format. This skill focuses on fast creation and correct structure. For iterative testing, benchmarking, and description optimization, use `/skill-creator`.

## Two Modes

- ### Mode 1: Create New Skill (`/skill-builder new [name]`)

- Creates a fresh Claude skill with proper structure and best practices.

- ### Mode 2: Translate ChatGPT Project (`/skill-builder translate [name]`)

- Converts an existing ChatGPT project into a Claude skill.

- ---

- ## Core Principles (from Anthropic)

- ### Concise is Key

- The context window is a public good. Skills share it with system prompts, conversation history, other skills' metadata, and user requests.

- **Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"

- Prefer concise examples over verbose explanations.

- ### Set Appropriate Degrees of Freedom

- Match specificity to task fragility:

- | Freedom Level | When to Use | Format |

- |---------------|-------------|--------|

- | **High** | Multiple valid approaches, context-dependent decisions | Text instructions |

- | **Medium** | Preferred pattern exists, some variation OK | Pseudocode, parameterized scripts |

- | **Low** | Fragile operations, consistency critical | Specific scripts, few parameters |

- Think of Claude exploring a path: a narrow bridge with cliffs needs guardrails (low freedom), while an open field allows many routes (high freedom).

- ### Progressive Disclosure

+ ### Mode 1: Create New Skill (`/agent-skill-builder new [name]`)

- Skills use a three-level loading system:

+ Scaffolds a fresh Claude Code skill with proper structure and best practices.

- 1. **Metadata (name + description)** - Always in context (~100 words)

- 2. **SKILL.md body** - When skill triggers (<5k words ideal, <500 lines)

- 3. **Bundled resources** - As needed (unlimited, scripts execute without loading)

+ ### Mode 2: Translate ChatGPT Project (`/agent-skill-builder translate [name]`)

- **Key principle:** Keep SKILL.md lean. Move variant-specific details to reference files.

+ Converts an existing ChatGPT project into a Claude Code skill.

---

- ## Workflow: Create New Skill

+ ## Create New Skill

- ### Step 1: Understand with Concrete Examples

+ ### Step 1: Gather Intent

- Ask the user:

+ Ask the user (skip what's already clear from context):

1. **Skill name**: What should the `/slash-command` be called?

2. **Purpose**: What does this skill do?

- 3. **Examples**: "Can you give examples of how this skill would be used?"

- 4. **Triggers**: "What would a user say that should trigger this skill?"

+ 3. **Examples**: How would this skill be used in practice?

+ 4. **Triggers**: What would a user say that should invoke this skill?

- Avoid overwhelming with questions. Start with the most important ones.

+ ### Step 2: Plan Resources

- ### Step 2: Plan Reusable Contents

+ Analyze each example to identify what should be bundled:

- Analyze each example to identify:

- - **Scripts** (`scripts/`): Code rewritten repeatedly or needing deterministic reliability

- - **References** (`references/`): Documentation Claude should consult while working

- - **Assets** (`assets/`): Files used in output (templates, images, fonts)

+ - **Scripts** (`scripts/`): Code rewritten repeatedly or needing deterministic reliability. Execute without loading into context.

+ - **References** (`references/`): Documentation Claude should consult while working. Loaded on demand.

+ - **Assets** (`assets/`): Files used in output (templates, images, fonts). Not loaded into context.

- ### Step 3: Create Directory Structure

+ ### Step 3: Create Directory and SKILL.md

```bash

mkdir -p ~/.claude/skills/[skill-name]

```

- ### Step 4: Write SKILL.md

- Choose a structure pattern:

- **Workflow-Based** (sequential processes)

- ```

- ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...

- ```

- **Task-Based** (tool collections)

- ```

- ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...

- ```

- **Reference/Guidelines** (standards/specifications)

- ```

- ## Overview → ## Guidelines → ## Specifications → ## Usage...

- ```

- **Capabilities-Based** (integrated systems)

- ```

- ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...

- ```

- Use this template:

+ Write SKILL.md following this template:

```markdown

---

- name: [skill-name]

- description: [What it does AND when to use it. Include specific triggers/contexts. Max 200 chars. This is the PRIMARY triggering mechanism.]

- version: "1.0.0"

+ name: skill-name

+ description: "Describes what the skill does and specific triggers for when to use it. Write in third person. Include keywords users would say. Max 1024 characters. This is the PRIMARY triggering mechanism."

---

- # [Skill Name]

+ # Skill Name

- [Brief description - 1-2 sentences]

+ [1-2 sentence description]

## Instructions

- [Step-by-step guidance for Claude]

+ [Step-by-step guidance — use imperative form]

## Output Format

[Expected output structure]

- ## Examples

- [Concrete input/output pairs]

## Constraints

[Limitations and rules]

```

- ### Step 5: Reference Files (if needed)

+ ### Step 4: Add Reference Files (if needed)

- For skills with multiple domains or variants:

+ For skills with multiple domains or variants, keep SKILL.md lean and split into references:

```

skill-name/

- ├── SKILL.md (overview + navigation)

+ ├── SKILL.md (overview + navigation, under 500 lines)

└── references/

├── variant-a.md

- ├── variant-b.md

- └── variant-c.md

+ └── variant-b.md

```

- Reference from SKILL.md:

- ```markdown

- ## Advanced Features

- - **Form filling**: See [forms.md](references/forms.md)

- - **API reference**: See [api.md](references/api.md)

- ```

+ Reference from SKILL.md with clear guidance on when to read each file. Keep references one level deep.

- ### Step 6: Test the Skill

+ ### Step 5: Test

1. Invoke directly: `/skill-name`

2. Let Claude auto-invoke by matching description keywords

- 3. Check `/context` to verify skill is loaded

+ 3. Check that the skill triggers when expected and stays silent when not relevant

---

- ## Workflow: Translate ChatGPT Project to Claude Skill

+ ## Translate ChatGPT Project to Claude Skill

### Step 1: Extract ChatGPT Components

Request from user:

- - ChatGPT system prompt/instructions

- - Knowledge files (PDFs, docs, etc.)

+ - System prompt/instructions

+ - Knowledge files (PDFs, docs)

- Conversation starters (optional)

- Actions/API configurations (if any)

- ### Step 2: Map ChatGPT Project → Claude

+ ### Step 2: Map Components

- | ChatGPT Component | Claude Equivalent | Location |

- |---------------|-------------------|----------|

+ | ChatGPT Component | Claude Code Equivalent | Location |

+ |---|---|---|

| Name | `name` in frontmatter | SKILL.md |

| Description | `description` in frontmatter | SKILL.md |

- | Instructions | Main markdown content | SKILL.md |

- | Knowledge files | `references/` folder (as .md) | Subdirectory |

- | Conversation starters | Document in skill or omit | SKILL.md |

- | Actions (APIs) | MCP servers | Separate config |

- | Custom behavior | Detailed instructions | SKILL.md |

+ | Instructions | Main markdown body | SKILL.md |

+ | Knowledge files | `references/` folder (convert to .md) | Subdirectory |

+ | Conversation starters | Document in Examples section or omit | SKILL.md |

+ | Actions (APIs) | MCP servers | `~/.claude/mcp.json` |

+ | Code Interpreter | Native tools: `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep` | Built-in |

+ | Memory | No direct equivalent. Use context files or skill background sections | Various |

### Step 3: Convert Instructions

| ChatGPT Pattern | Claude Equivalent |

- |-------------|-------------------|

- | "You are a [role]..." | "## Role" section |

- | "Your task is to..." | "## Instructions" section |

- | "Always/Never..." | "## Constraints" section |

- | "Output format..." | "## Output Format" section |

- | "Examples:" | "## Examples" section |

+ |---|---|

+ | "You are a [role]..." | Role section or integrate into instructions |

+ | "Your task is to..." | Instructions section |

+ | "Always/Never..." | Constraints section |

+ | "Output format..." | Output Format section |

| Input placeholders `[text]` | Keep as-is or use `$ARGUMENTS` |

### Step 4: Convert Knowledge Files

- 1. **PDFs/Docs**: Convert to Markdown

- 2. **Large references**: Put in `references/` subfolder

- 3. **Templates**: Put in `assets/` subfolder

- 4. **Examples**: Include in SKILL.md or `references/examples.md`

- If files are large (>10k words), include grep search patterns in SKILL.md.

- ### Step 5: Set Frontmatter

- ```yaml

- ---

- name: skill-name # lowercase, hyphens only

- description: What AND when # PRIMARY triggering mechanism

- version: "1.0.0" # optional

- disable-model-invocation: true # if user-only

- user-invocable: false # if Claude-only

- context: fork # if needs isolation

- agent: Explore # if using subagent

- allowed-tools: Read, Grep, Glob # if restricting tools

- ---

- ```

- ### Step 6: Update CLAUDE.md

- Add entry to the skills table:

- ```markdown

- | `skill-name` | User wants to [action]; mentions "[keyword1]," "[keyword2]" |

- ```

- ---

- ## ChatGPT-Specific Translation Notes

- ### ChatGPT "Memory" → Claude

- ChatGPT memory has no direct equivalent. Options:

- - Store in `~/.claude/memory.json`

- - Use project-specific context files

- - Include as "background" section in skill

- ### ChatGPT "Actions" → MCP Servers

- ChatGPT Actions (API calls) require MCP server setup in `~/.claude/mcp.json`.

- ### ChatGPT "Code Interpreter" → Claude Tools

- Claude has native access to: `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`

+ 1. Convert PDFs/docs to Markdown and place in `references/`

+ 2. For large files (>10k words), include grep search patterns in SKILL.md

+ 3. For files >100 lines, add a table of contents at the top

+ 4. Templates and assets go in `assets/`

- ### ChatGPT Conversation Starters

+ ### Step 5: Write Frontmatter

- Document in skill's "## Examples" section or CLAUDE.md usage hints.

+ The `description` field is the primary triggering mechanism. Write in third person and include both what the skill does and when to use it. Be slightly "pushy" with triggers to combat undertriggering.

---

- ## What NOT to Include

- Do NOT create extraneous documentation:

- - README.md

- - INSTALLATION_GUIDE.md

- - QUICK_REFERENCE.md

- - CHANGELOG.md

- Skills should only contain information needed for an AI agent to do the job. No auxiliary context about creation process, setup procedures, or user-facing documentation.

- ---

+ ## Frontmatter Reference

- ## Frontmatter Fields Reference

+ Only `name` and `description` are required. Additional fields are Claude Code-specific extensions:

| Field | Required | Description |

- |-------|----------|-------------|

- | `name` | No | Slash command name. Uses directory name if omitted. |

- | `description` | **Critical** | What + When. PRIMARY triggering mechanism for auto-invocation. |

- | `version` | No | Version string (e.g., "1.0.0") |

- | `argument-hint` | No | Hint shown in autocomplete (e.g., "[issue-number]") |

- | `disable-model-invocation` | No | `true` = user-only invocation |

- | `user-invocable` | No | `false` = Claude-only (hidden from menu) |

+ |---|---|---|

+ | `name` | Yes | Max 64 chars, lowercase letters/numbers/hyphens only |

+ | `description` | Yes | Max 1024 chars. What + When. Third person. Primary trigger mechanism |

+ | `argument-hint` | No | Hint shown in autocomplete (e.g., `"[issue-number]"`) |

+ | `disable-model-invocation` | No | `true` = user-only invocation (no auto-trigger) |

+ | `user-invocable` | No | `false` = Claude-only (hidden from slash command menu) |

| `context` | No | `fork` = run in isolated subagent |

- | `agent` | No | Subagent type: Explore, Plan, general-purpose |

- | `allowed-tools` | No | Restrict tools: `Read, Grep, Glob` |

+ | `agent` | No | Subagent type: `Explore`, `Plan`, `general-purpose` |

+ | `allowed-tools` | No | Restrict available tools: `Read, Grep, Glob` |

| `model` | No | Override model for this skill |

- ---

- ## Writing Good Descriptions

- The description is the PRIMARY triggering mechanism. Claude reads it to decide when to use the skill.

- **Bad:**

- ```

- description: Helps with code

- ```

- **Good:**

- ```

- description: Reviews code for security, performance, and best practices. Use when user asks to "review code," "check this code," "security audit," or wants feedback on code quality.

- ```

- Include:

- - What the skill does

- - When to use it (keywords, triggers, scenarios)

- - Max 200 characters

- ---

## String Substitutions

| Variable | Description |

- |----------|-------------|

+ |---|---|

| `$ARGUMENTS` | Everything after `/skill-name` |

| `${CLAUDE_SESSION_ID}` | Current session ID |

| `` !`command` `` | Dynamic injection (runs before skill loads) |

- ---

## Skill Locations

| Location | Path | Scope |

- |----------|------|-------|

- | Personal | `~/.claude/skills/[name]/` | All your projects |

+ |---|---|---|

+ | Personal | `~/.claude/skills/[name]/` | All projects |

| Project | `.claude/skills/[name]/` | This project only |

- ---

+ ## Writing Best Practices

+ These come from Anthropic's official skill authoring guide:

+ - **Concise is key.** Claude is already smart. Only add context Claude doesn't already have. Prefer concise examples over verbose explanations.

+ - **Description is everything.** Claude reads descriptions to decide which skill to use from potentially 100+ available skills. Be specific, include trigger keywords, write in third person.

+ - **Progressive disclosure.** Keep SKILL.md under 500 lines. Move detailed references to separate files. Claude loads them only when needed.

+ - **Match freedom to fragility.** High freedom (text instructions) for flexible tasks, low freedom (specific scripts) for fragile operations.

+ - **Explain the why.** Explain reasoning behind instructions rather than using heavy-handed MUSTs. Claude responds better to understanding motivation than rigid rules.

+ - **Consistent terminology.** Pick one term and use it throughout. Don't mix "API endpoint" / "URL" / "API route" / "path".

+ - **No extraneous files.** No README.md, CHANGELOG.md, INSTALLATION_GUIDE.md. Skills contain only what an AI agent needs to do the job.

+ - **Forward slashes only.** Use `scripts/helper.py`, never `scripts\helper.py`.

## After Creation Checklist

- - [ ] SKILL.md created with proper frontmatter

- - [ ] Description includes what AND when (triggers)

+ - [ ] SKILL.md created with `name` and `description` in frontmatter

+ - [ ] Description includes what AND when (triggers), written in third person

+ - [ ] SKILL.md under 500 lines

- [ ] Knowledge files converted to Markdown in `references/`

- - [ ] SKILL.md under 500 lines (split if larger)

- - [ ] CLAUDE.md updated with skill entry

- - [ ] Skill tested with `/skill-name`

- - [ ] Auto-invocation tested with matching keywords

- - [ ] No extraneous documentation files created

+ - [ ] References are one level deep from SKILL.md

+ - [ ] Large reference files (>100 lines) have table of contents

+ - [ ] Skill tested with `/skill-name` and auto-invocation

+ - [ ] No extraneous documentation files