Skill Creator

<!-- Adapted from skill-creator implementations by Anthropic and OpenAI: https://github.com/anthropics/claude-plugins-official https://github.com/openai/codex-plugins-official -->

Create a New Skill

Guide the user through creating a new agent skill following the Agent Skills specification. Follow each step in order.

Step 1: Understand the Skill

Gather requirements before writing anything.

Ask the user: 1. What should this skill do? (one sentence) 2. When should an agent use it? (trigger phrases) 3. What tools does the skill need? (Read, Grep, Glob, Bash, Task, WebFetch, etc.) 4. Where should the skill live? (which plugin or directory)

Determine the skill name:

• Lowercase alphanumeric with hyphens, 1-64 characters
• Descriptive and unique among existing skills
• Check the target skills directory to avoid name collisions

Choose a complexity tier:

Read ${CLAUDE_SKILL_ROOT}/references/design-principles.md for guidance on keeping skills focused and concise.

Step 2: Study Existing Skills

Before writing, study 1-2 existing skills that match the chosen tier. Look for skills in the target repository or plugin to understand local conventions.

Read ${CLAUDE_SKILL_ROOT}/references/skill-patterns.md for concrete examples of each tier.

Also read CLAUDE.md (or AGENTS.md) at the repository root for repo-specific conventions that the skill should follow.

Step 3: Write the SKILL.md

Create <skill-directory>/<name>/SKILL.md.

Frontmatter

The YAML frontmatter must be the first thing in the file. No comments or blank lines before ---.

---
name: <skill-name>
description: <what it does>. Use when <trigger phrases>. <key capabilities>.
---

Required fields:

• name — must match the directory name exactly
• description — up to 1024 chars; include trigger keywords that help agents match user intent

Optional fields:

• model — override model (sonnet, opus, haiku); omit to use the user's default
• allowed-tools — space-delimited list (e.g., Read Grep Glob Bash Task); omit to allow all tools
• license — license name or path (add when vendoring external content)

Body Guidelines

Write the body in imperative voice — these are instructions, not documentation.

Structure: 1. Start with a one-line summary of what the skill does 2. Organize steps with ## Step N: Title headings 3. Use tables for decision logic and mappings 4. Include concrete examples of expected output 5. End with validation criteria or exit conditions

Size limits:

• Keep SKILL.md under 500 lines
• If approaching the limit, move reference material to references/ files
• Load reference files conditionally based on context (not all at once)

Attribution

If the skill is based on or adapted from external sources, add an HTML comment after the frontmatter closing ---:

---
name: example
description: ...
---

<!--
Based on [Original Name] by [Author/Org]:
https://github.com/example/original-source
-->

Step 4: Create Supporting Files

References (references/)

Use for domain knowledge the agent loads conditionally.

<name>/
├── SKILL.md
└── references/
    ├── topic-a.md
    └── topic-b.md

Reference from SKILL.md with:

Read `${CLAUDE_SKILL_ROOT}/references/topic-a.md` for details on [topic].

Keep each reference file focused on one topic. Use markdown with tables and code blocks.

Scripts (scripts/)

Use for workflow automation that benefits from structured Python.

<name>/
├── SKILL.md
└── scripts/
    └── do_thing.py

Script requirements:

• Always use uv run to execute: uv run ${CLAUDE_SKILL_ROOT}/scripts/do_thing.py
• Add PEP 723 inline metadata for dependencies:

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///

• Output structured JSON for agent consumption
• Run from the repository root, not the skill directory
• Document the script's interface in SKILL.md (arguments, output format)

Assets (assets/)

Use for static files the skill references (templates, configs, etc.).

LICENSE

Include a LICENSE file in the skill directory when vendoring content with specific licensing requirements.

Step 5: Register the Skill

Registration steps vary by repository. Check the repository's CLAUDE.md or README.md for specific instructions.

1. Verify directory-name match — confirm the directory name matches the name field in SKILL.md frontmatter exactly 2. Update documentation — add the skill to any skills index or table in README.md 3. Update permissions — if the repo has .claude/settings.json, add Skill(<plugin>:<name>) to the permissions.allow array 4. Check CLAUDE.md — read the repository's CLAUDE.md for any additional registration steps specific to that project

Step 6: Verify

Run through this checklist before finishing:

Frontmatter

• [ ] name matches directory name
• [ ] description is under 1024 characters
• [ ] description includes trigger keywords
• [ ] No content before the opening ---

Content

• [ ] SKILL.md is under 500 lines
• [ ] Written in imperative voice
• [ ] Steps are numbered and clear
• [ ] Examples of expected output included
• [ ] Reference files loaded conditionally (not unconditionally)

Registration

• [ ] Directory name matches frontmatter name
• [ ] Skill added to repo documentation (README or equivalent)
• [ ] Permissions updated (if applicable)
• [ ] Any repo-specific registration steps completed (check CLAUDE.md)

Scripts (if applicable)

• [ ] Uses uv run ${CLAUDE_SKILL_ROOT}/scripts/...
• [ ] Has PEP 723 inline metadata
• [ ] Outputs structured JSON
• [ ] Documented in SKILL.md

Report any issues found and fix them before completing.

Skill Design Principles

Principles for writing effective agent skills. A skill is a set of instructions injected into an agent's context window — every line competes for space with the user's actual task.

Conciseness

The context window is shared between the skill instructions and the agent's working memory. Only include what the agent doesn't already know.

Include:

• Domain knowledge specific to this task
• Decision logic the agent can't infer
• Output format requirements
• Concrete examples of correct behavior

Omit:

• General programming knowledge
• How to use standard tools (Read, Grep, Bash)
• Obvious instructions ("be thorough", "check for errors")
• Lengthy explanations when a table or example suffices

Rule of thumb: If a senior engineer would skip reading it, the agent doesn't need it either.

Degrees of Freedom

Match the specificity of your instructions to the fragility of the task.

Over-constraining low-fragility tasks wastes context and limits the agent. Under-constraining high-fragility tasks leads to inconsistent results.

Progressive Disclosure

Structure skills so agents load only what they need, when they need it.

Three-tier loading:

1. Metadata (always loaded) — frontmatter name and description determine whether the skill activates 2. Instructions (loaded on activation) — the SKILL.md body with the core workflow 3. Resources (loaded on demand) — reference files, loaded conditionally based on the task context

## Step 3: Load Language Guide

| File Extension | Read This Reference |
|---------------|-------------------|
| `.py`         | `${CLAUDE_SKILL_ROOT}/references/python.md` |
| `.js`, `.ts`  | `${CLAUDE_SKILL_ROOT}/references/javascript.md` |

This keeps the base context small while making deep knowledge available when needed.

Description as Trigger

The description field determines when agents activate the skill. It must contain the phrases users actually say.

Effective descriptions:

# Good — includes natural trigger phrases
description: Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history.

# Good — includes action verbs and domain terms
description: Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for security issues", "audit security", "OWASP review".

Ineffective descriptions:

# Bad — too vague, no trigger phrases
description: A helpful skill for code quality.

# Bad — describes internals, not when to use it
description: Runs a Python script that parses AST and generates reports.

# Bad — too short, won't match varied user phrasing
description: Code review.

Pattern: <What it does>. Use when <trigger phrases>. <Key capabilities>.

Imperative Voice

Skills are instructions to an agent, not documentation for humans. Write in imperative voice throughout.

The agent interprets imperative instructions as direct commands. Descriptive language introduces ambiguity about whether an action is required or optional.

Skill Patterns

Concrete examples of skill structures at each complexity tier.

Simple: SKILL.md Only

Use when the entire skill fits in under ~200 lines with no external resources needed.

Examples: brand-guidelines, commit, create-pr

Structure:

brand-guidelines/
└── SKILL.md

Pattern highlights:

• Frontmatter with name and description only (no model override, no allowed-tools)
• Body organized with ## sections for different aspects of the domain
• Heavy use of tables for decision logic and examples
• No references to external files

When to use: The skill provides a single coherent set of rules or a short procedural workflow. All the information an agent needs fits comfortably in one file.

Workflow: SKILL.md + Scripts

Use when the skill automates a multi-step workflow with structured data processing.

Examples: iterate-pr

Structure:

iterate-pr/
├── SKILL.md
└── scripts/
    ├── fetch_pr_checks.py
    └── fetch_pr_feedback.py

Pattern highlights:

• SKILL.md documents each script's interface (arguments, output JSON schema)
• Scripts use PEP 723 inline metadata for dependencies:

  # /// script
  # requires-python = ">=3.12"
  # dependencies = ["requests"]
  # ///

• Invoked with uv run ${CLAUDE_SKILL_ROOT}/scripts/script_name.py
• Scripts run from the repository root, not the skill directory
• Scripts output structured JSON for agent consumption
• SKILL.md includes a fallback section for when scripts fail

When to use: The workflow benefits from structured data extraction, API calls, or processing that would be fragile as inline bash commands.

Domain Expert: SKILL.md + References

Use when the skill covers a broad domain with conditional knowledge loading.

Examples: security-review

Structure:

security-review/
├── SKILL.md
├── LICENSE
├── references/
│   ├── injection.md
│   ├── xss.md
│   ├── authentication.md
│   └── ... (17 reference files)
├── languages/
│   ├── python.md
│   └── javascript.md
└── infrastructure/
    ├── docker.md
    └── kubernetes.md

Pattern highlights:

• SKILL.md contains the core workflow and quick-reference tables
• Reference files are loaded conditionally based on detected context:

  | Code Type | Load These References |
  |-----------|----------------------|
  | API endpoints | `authorization.md`, `injection.md` |
  | Frontend | `xss.md`, `csrf.md` |

• Each reference file is self-contained and focused on one topic
• SKILL.md includes a file index so the agent knows what's available
• LICENSE included because content is adapted from external sources

When to use: The domain is too large for one file, but the agent only needs a subset for any given task. Progressive disclosure keeps context small.

Anti-Patterns

Over-long SKILL.md

Problem: SKILL.md exceeds 500 lines, consuming excessive context window.

Fix: Extract reference material into references/ files. Keep SKILL.md focused on the procedural workflow and load references conditionally.

Missing Trigger Keywords

Problem: Description says "A skill for helping with code" — agents can't match this to user requests like "review my PR" or "check for bugs".

Fix: Include the actual phrases users say: Use when asked to "review code", "find bugs", "check for issues".

Duplicating CLAUDE.md

Problem: SKILL.md repeats repo conventions already in CLAUDE.md (commit format, PR process, etc.).

Fix: Reference CLAUDE.md where needed. Skills should add domain knowledge, not repeat general conventions. Example: "Follow the commit conventions in CLAUDE.md" instead of copying the entire commit format spec.

Unconditional Reference Loading

Problem: SKILL.md says "Read all reference files before starting" — loads 20+ files into context regardless of the task.

Fix: Use a decision table to load only relevant references:

| Detected Language | Read |
|------------------|------|
| Python           | `references/python.md` |
| JavaScript       | `references/javascript.md` |

Scripts Without Documentation

Problem: SKILL.md says uv run ${CLAUDE_SKILL_ROOT}/scripts/tool.py but doesn't document what arguments it takes or what it outputs.

Fix: Document every script's interface in SKILL.md:

### `scripts/tool.py`
Fetches X and returns structured data.

uv run ${CLAUDE_SKILL_ROOT}/scripts/tool.py --flag VALUE

Returns JSON:

{"key": "value", "items": [...]}

Hardcoded Paths

Problem: SKILL.md references a hardcoded path like plugins/my-plugin/skills/my-skill/scripts/tool.py.

Fix: Always use ${CLAUDE_SKILL_ROOT}/scripts/tool.py. The variable resolves to the skill's directory regardless of where the agent runs from.