Create-Skill - Scaffolding Claude Code Skills

Skills are reusable prompt modules that extend Claude Code’s capabilities. They live as SKILL.md files inside a project and get loaded automatically when a user’s prompt matches their trigger description. Think of them as specialized instructions that teach Claude how to handle specific workflows.

Skill Structure

A skill is a folder with a SKILL.md file at minimum:

skills/
└── skill-name/           # kebab-case
    ├── SKILL.md          # Required - main skill definition
    ├── Workflows/        # Optional - sub-workflows
    │   └── workflow.md
    └── tools/            # Optional - scripts invoked by the skill
        └── tool.ts       # TypeScript (run with bun), Python, etc.

The SKILL.md file uses YAML frontmatter for metadata and markdown for instructions:

---
name: skill-name
description: What it does. USE WHEN [trigger phrases]. Key capabilities.
allowed-tools: # Optional - restrict tool access
  - Read(path/**)
  - Bash
---

The description field is critical because Claude uses it for routing. The USE WHEN clause tells Claude when to activate the skill.

After the frontmatter, the body contains the actual instructions: workflow steps, examples, notes, and optionally a workflow routing table if the skill has sub-workflows.

My create-skill Skill

I built a create-skill skill that helps scaffold and validate new skills. It enforces the canonical structure and catches common mistakes.

The skill defines the expected SKILL.md format:

---
name: skill-name
description: What it does. USE WHEN [trigger phrases]. Key capabilities.
allowed-tools:            # Optional - restrict tool access
  - Read(path/**)
  - Bash
---

# Skill Title

Brief description of what this skill does.

## Workflow Routing       # ONLY if Workflows/ directory exists

| Trigger | Workflow |
|---------|----------|
| "do X"  |x.md |

## Examples

**Example 1: Description**
User: "example prompt"
→ Expected action/output

## Notes

Additional context, prerequisites, tips.

It also includes a validation checklist that gets run against any skill:

• Folder name is kebab-case
• SKILL.md has valid YAML frontmatter
• description includes a USE WHEN clause
• Examples section with 2-3 trigger patterns
• Workflow Routing section only present if Workflows/ directory exists
• No orphan workflow files (every workflow must be referenced in the routing table)

You can use it in three ways:

1. Create a new skill: “create a skill for managing git worktrees” and it scaffolds the full folder structure
2. Validate an existing skill: “check if my summarize skill is structured correctly” and it reports issues against the checklist
3. Canonicalize a skill: “my skill works but might not follow best practices” and it reviews and fixes the structure

Anthropic’s Official Skill Creator

Anthropic published their own skill-creator skill that takes a more structured, iterative approach to building skills. Key differences from my simpler version:

• Iterative development loop: define intent, write draft, create test cases, evaluate with user, refine, repeat
• Progressive disclosure: skills load metadata first (~100 words), then full instructions (<500 lines), then bundled resources
• Theory of mind over rigid rules: they recommend explaining why things matter instead of heavy MUST/NEVER directives
• Generalization over overfitting: since skills can run across many different prompts, they suggest iterating on broad patterns rather than tweaking for specific test cases
• Built-in eval workflow: spawns parallel “with-skill” and baseline runs, then uses a review tool to compare results

Worth looking at if you want a more rigorous approach to skill development, especially for skills intended to be shared publicly.