Skill Creator

Overview

A skill is a folder that teaches Claude how to handle a specific task or workflow. Skills are an open standard — the same skill folder works across Claude.ai, Claude Code, and the Messages API (via container.skills).

Two types (claude-code-setup harness convention):

• Command skills — invoked explicitly via /skill-name (e.g. /deploy-staging)
• Context skills — auto-loaded when the project's Tech Stack matches (e.g. standards-python loads for Python projects)

The type/applies_to/file_extensions fields are harness extensions specific to claude-code-setup. For pure Anthropic-spec skills (Claude.ai or API upload), see references/02-frontmatter.md → "Harness-specific fields".

This skill walks the user through an 8-step interactive flow for creating a new skill. It is also useful for reviewing an existing skill (see references/07-troubleshooting.md → "Escalation path") or fixing one that doesn't trigger properly.

By default, created skills save to ~/.claude/custom/skills/<name>/, survive claude-code-setup upgrades, and are discovered by the harness. For Claude.ai or API distribution, see references/09-distribution.md.

Critical rules (always)

• SKILL.md — exact filename, case-sensitive. skill.md, SKILL.MD, etc. all fail.
• Name — kebab-case only. No claude or anthropic prefix (both reserved).
• Description — under 1024 chars, must include both what the skill does and when to use it. No XML angle brackets (< or >) — security restriction.
• No README.md inside the skill folder. Repo-level READMEs (for GitHub visitors) are fine.
• SKILL.md — keep under ~5000 words. Move depth into references/.
• Composability. Claude loads many skills simultaneously. Your skill should work alongside others — do not assume it's the only capability available.

Full rules and frontmatter schema: references/02-frontmatter.md.

Creation Flow (8 steps, interactive)

Use conversational interaction — ask one question at a time, wait for the answer before moving on.

Step 1 — Concrete use cases

Ask:

Give me 2–3 specific, concrete scenarios where you want this skill to kick in. Format: "I say X" → "Claude does Y".

The quality of the skill is capped by the quality of the use cases. Vague cases ("help with projects") produce unusable skills. Specific cases ("onboard a new PayFlow customer: create account → setup payment → activate subscription") produce skills that trigger reliably and behave consistently.

If the user gives only one scenario, push for at least two more — paraphrased versions of the same task, or related edge cases.

Step 2 — Skill type

Map the use cases to a type:

• If the trigger is explicit ("deploy X", "generate report", "scaffold Y") → command skill
• If the skill should apply automatically when touching certain files, file extensions, or tech stacks → context skill

If ambiguous, present both options and let the user pick:

Command skill — invoked as /skill-name
   Example: /deploy-staging, /generate-report
   Pro: deterministic invocation
   Con: user must remember the command

Context skill — auto-loaded by tech stack or file extension
   Example: standards-python, api-conventions
   Pro: always applied, no user effort
   Con: consumes context tokens on every matching project

Minimal frontmatter for each type (harness-specific fields — see references/02-frontmatter.md):

# Command skill
type: command

# Context skill
type: context
applies_to: [python, fastapi]

Step 3 — Name + description

Propose a kebab-case name based on the use cases. The folder name, frontmatter name, and directory must all match.

Write the description in this structure:

[What it does] + [When to use it, with trigger phrases] + (optional) [Key capabilities]

Good and bad examples, plus the full test ("would Claude know to pick this skill when the user says X?"): references/03-writing-descriptions.md.

Step 4 — Frame the skill (problem-first vs. tool-first)

Before picking a pattern, decide which framing fits:

• Problem-first — user describes an outcome ("set up a project workspace") and the skill orchestrates tools. Most command skills.
• Tool-first — user has a tool (MCP server, library) and the skill teaches best practices for using it. Most context skills and MCP-wrapping skills.

This framing points directly at the right pattern.

Step 4b — Pick a pattern

Most skills fit one of 5 patterns. Identify which fits before writing instructions.

Full descriptions with ready-to-copy structures — plus the "Skills + MCP" story for skills that wrap an MCP server: references/05-patterns.md.

Step 5 — Decide the folder structure

Most skills need only SKILL.md. Add folders only when justified.

<skill-name>/
├── SKILL.md              required
├── references/           optional — detailed docs loaded on demand
├── assets/               optional — templates the skill produces
└── scripts/              optional — executable code (Python, Bash, etc.)

• references/ — use when SKILL.md would otherwise exceed 5000 words
• assets/ — use when the skill produces outputs from templates (letters, reports, decks)
• scripts/ — use when a step needs determinism (code is reliable; language interpretation isn't). Common: validation, parsing, file manipulation.

See references/01-progressive-disclosure.md for the full three-level model.

Step 6 — Generate the content

Write SKILL.md using the pattern from Step 4. Apply the rules in references/04-writing-instructions.md:

• Lead with the decision flow, not prose
• Be specific and actionable — concrete commands/queries, not abstractions
• Structure with headers and bullets, not paragraphs
• Include error handling and worked examples
• Move depth to references/ the moment SKILL.md threatens to bloat

If the user asked to provide instructions themselves, review their draft against these rules and suggest concrete edits.

Step 7 — Test

Three checks before calling the skill done:

1. Triggering — does Claude load the skill when asked the expected questions? Paraphrase the question; also check that unrelated topics do NOT trigger.
2. Functional — does the skill produce correct outputs for the use cases from Step 1?
3. Performance — does the skill save tokens + tool calls vs. a no-skill baseline?

To measure a baseline, temporarily disable the skill. Simplest: rename the folder to <name>.disabled before running the same prompts, then rename back.

Full method and example test matrix: references/06-testing.md.

Step 8 — Save, activate, verify

1. Write the files to ~/.claude/custom/skills/<name>/.
2. Activate the skill in the harness so the loader picks it up:

   ./install.sh --refresh-custom
   

   or equivalently: run /claude-code-setup and pick "Upgrade custom".
3. Run through references/08-checklist.md pre-upload.
4. Show the user the invocation:
   • Command skill: /<name>
   • Context skill: "auto-loads when Tech Stack includes <applies-to value>"

For sharing outside claude-code-setup (Claude.ai upload, API via container.skills, GitHub distribution), see references/09-distribution.md.

Troubleshooting (quick reference)

Full diagnosis: references/07-troubleshooting.md.