Skill Creator

Skill Creator

Interactive guide for building effective skills — from planning through distribution.

What is a Skill

A skill is a folder containing:

• SKILL.md (required): Instructions in Markdown with YAML frontmatter
• scripts/ (optional): Executable code (Python, Bash, etc.)
• references/ (optional): Documentation loaded as needed
• assets/ (optional): Templates, fonts, icons used in output

Skills work identically across Claude.ai, Claude Code, and API. Multiple skills can be loaded simultaneously — design skills to work alongside others.

Core Design Principles

Progressive Disclosure — three-level loading system:

1. YAML frontmatter — always in Claude's system prompt (~100 words). Claude decides when to trigger.
2. SKILL.md body — loaded when skill triggers (<5k words). Core instructions.
3. Linked files — bundled resources Claude navigates only as needed (unlimited).

Concise is Key — the context window is a public good. Claude is already very smart — only add context it doesn't have. Challenge each piece: "Does this paragraph justify its token cost?" Prefer concise examples over verbose explanations.

Degrees of Freedom — match specificity to task fragility:

• High (text instructions): multiple approaches valid, context-dependent decisions
• Medium (pseudocode/scripts with params): preferred pattern exists, some variation ok
• Low (specific scripts, few params): fragile operations, consistency critical

File Structure

skill-name/
├── SKILL.md          # Required - instructions with YAML frontmatter
├── scripts/          # Optional - executable code (Python/Bash)
├── references/       # Optional - documentation loaded as needed
└── assets/           # Optional - templates, images, fonts for output

Critical rules:

• SKILL.md must be exactly SKILL.md (case-sensitive)
• Folder name: kebab-case only (notion-project-setup not Notion Project Setup)
• No README.md inside skill folder — all docs go in SKILL.md or references/
• No extraneous files (CHANGELOG.md, INSTALLATION_GUIDE.md, etc.)

Bundled Resources

scripts/ — executable code for deterministic, repeatable operations. Token efficient; may be executed without loading into context.

references/ — documentation loaded as needed. Keep SKILL.md lean; move detailed schemas, API docs, policies here. If files >10k words, include grep patterns in SKILL.md. Avoid duplication between SKILL.md and references.

assets/ — files used in output, not loaded into context. Templates, images, fonts, boilerplate.

Progressive Disclosure Patterns

Keep SKILL.md under 500 lines. Reference detailed content from separate files.

Pattern 1: High-level guide with references

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md)

Pattern 2: Domain-specific organization — organize by domain/variant:

bigquery-skill/
├── SKILL.md (overview + navigation)
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

Pattern 3: Conditional details — basic content inline, link advanced content.

Guidelines: keep references one level deep from SKILL.md. For files >100 lines, include a table of contents.

Common Skill Use Case Categories

Category 1: Document & Asset Creation — creating consistent, high-quality output (documents, presentations, apps, designs, code). Key techniques: embedded style guides, template structures, quality checklists.

Category 2: Workflow Automation — multi-step processes with consistent methodology. Key techniques: step-by-step workflow with validation gates, templates, iterative refinement loops.

Category 3: MCP Enhancement — workflow guidance on top of MCP tool access. Key techniques: coordinate multiple MCP calls, embed domain expertise, error handling for common MCP issues. See references/mcp-guide.md for MCP + Skills integration details.

Skill Creation Process

1. Understand the skill with concrete examples
2. Plan reusable skill contents (scripts, references, assets)
3. Initialize the skill (run init_skill.py)
4. Edit the skill (implement resources and write SKILL.md)
5. Test the skill
6. Package the skill (run package_skill.py)
7. Iterate based on real usage

Follow these steps in order, skipping only if there is a clear reason why they are not applicable.

Step 1: Understand the Skill with Concrete Examples

Identify 2-3 concrete use cases. For each, define:

• What does a user want to accomplish?
• What multi-step workflows does this require?
• Which tools are needed (built-in or MCP)?
• What domain knowledge or best practices should be embedded?
• What would a user say that should trigger this skill?

Ask the user focused questions. Avoid overwhelming — start with the most important and follow up as needed.

Step 2: Plan Reusable Skill Contents

For each use case, analyze what would be helpful when executing the workflow repeatedly:

• scripts/: code that gets rewritten each time (e.g., rotate_pdf.py)
• assets/: boilerplate files copied each time (e.g., hello-world/ template)
• references/: knowledge re-discovered each time (e.g., schema.md for BigQuery tables)

Step 3: Initialize the Skill

Skip if updating an existing skill. For new skills, run:

scripts/init_skill.py <skill-name> --path <output-directory>

Creates skill directory with SKILL.md template and example resource directories.

Step 4: Edit the Skill

The skill is being created for another Claude instance. Include information that would be beneficial and non-obvious. Consider what procedural knowledge, domain-specific details, or reusable assets would help.

Implement Resources

Start with scripts/, references/, assets/ identified in Step 2. Test added scripts by running them. Delete unneeded example files from initialization.

Design Patterns

Consult these based on your skill's needs:

• Workflow patterns: See references/patterns.md — sequential, multi-MCP, iterative refinement, context-aware, domain-specific
• Output patterns: See references/output-patterns.md — template and example patterns

Write YAML Frontmatter

Required fields:

name — kebab-case, lowercase, max 64 characters. Must match folder name.

description — the primary triggering mechanism. Structure: [What it does] + [When to use it] + [Key capabilities]. Max 1024 characters. No XML angle brackets (< >).

Good description examples:

# Good - specific and actionable
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

# Good - includes trigger phrases
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

# Good - clear value proposition
description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".

Bad description examples:

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers
description: Implements the Project entity model with hierarchical relationships.

Include all "when to use" info in description — NOT in the body. The body is only loaded after triggering.

Optional fields:

• license: e.g., MIT, Apache-2.0
• allowed-tools: restrict tool access, e.g., "Bash(python:*) Bash(npm:*) WebFetch"
• metadata: custom key-value pairs (author, version, mcp-server, category, tags)
• compatibility: environment requirements, max 500 characters

Security restrictions:

• No XML angle brackets (< >) in frontmatter
• No "claude" or "anthropic" in skill name (reserved)

Write SKILL.md Body

Use imperative/infinitive form. Recommended structure:

# Your Skill Name

## Instructions
### Step 1: [First Major Step]
Clear explanation of what happens.
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]

Step 2: [Next Step]

...

Examples

Example 1: [common scenario] User says: "Set up a new marketing campaign" Actions:

1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters Result: Campaign created with confirmation link

Troubleshooting

Error: [Common error message] Cause: [Why it happens] Solution: [How to fix]

Best practices for instructions:
- Be specific and actionable (not "Validate the data" but "Run `python scripts/validate.py --input {filename}`")
- Reference bundled resources clearly
- Include error handling for common issues
- For critical validations, bundle a script rather than relying on language instructions — code is deterministic
- Keep SKILL.md focused on core instructions, move detailed docs to references/

#### Define Success Criteria

Aspirational targets for the skill:
- **Triggers on 90% of relevant queries** — test 10-20 queries that should trigger
- **Completes workflow in X tool calls** — compare with/without skill
- **0 failed API calls per workflow** — monitor during test runs
- **Users don't need to prompt about next steps**
- **Consistent results across sessions**

### Step 5: Test the Skill

See [references/testing.md](references/testing.md) for detailed testing guidance.

Three areas to test:
1. **Triggering** — triggers on obvious tasks and paraphrases; doesn't trigger on unrelated topics
2. **Functional** — valid outputs, API calls succeed, error handling works, edge cases covered
3. **Performance** — compare with/without skill (token usage, tool calls, user corrections)

Pro tip: iterate on a single challenging task until Claude succeeds, then extract the winning approach into the skill.

### Step 6: Package the Skill

```bash
scripts/package_skill.py <path/to/skill-folder> [output-directory]

Validates automatically (frontmatter, naming, description quality), then creates a .skill file (zip format).

Step 7: Iterate

See references/troubleshooting.md for common issues.

Undertriggering signals: skill doesn't load when it should, users manually enabling it → add more trigger phrases and keywords to description.

Overtriggering signals: skill loads for irrelevant queries → add negative triggers, be more specific, clarify scope.

Execution issues: inconsistent results, API failures → improve instructions, add error handling.

Quick Checklist

Before you start: 2-3 concrete use cases identified, tools identified, folder structure planned.

During development: folder kebab-case, SKILL.md exists, frontmatter has --- delimiters, name kebab-case, description includes WHAT and WHEN, no XML tags, instructions actionable, error handling included, examples provided, references linked.

Before upload: tested triggering (obvious + paraphrased), functional tests pass, compressed as .zip/.skill.

After upload: test in real conversations, monitor under/over-triggering, collect feedback, iterate.