/skill-creator

name: skill-creator
description: Guide users through creating, reviewing, and fixing custom skills for Claude — both command skills (invoked via /slash) and context skills (auto-loaded by tech stack). Use when the user asks to create a skill, build a skill, make a new slash command skill, add a coding standards skill, review an existing skill, update a skill, or fix a skill that doesn't trigger.
type: command
source: https://github.com/AJBcoding/claude-skill-eval
metadata:
  reference: "The Complete Guide to Building Skills for Claude (Anthropic, Jan 2026)"

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.

| # | Pattern | When | |---|---------|------| | 1 | Sequential workflow orchestration | Multi-step process, steps in a specific order | | 2 | Multi-MCP coordination | Workflow spans multiple MCP servers | | 3 | Iterative refinement | Output quality improves through repeat passes | | 4 | Context-aware tool selection | Same outcome, different tools depending on context | | 5 | Domain-specific intelligence | Specialized expertise beyond tool access |

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/