Meta-Skill Creator

Create and validate skills for AI agents following Anthropic's official skill specification.

Output Language: All generated skill content (SKILL.md, comments, documentation) in English.

Core Principle: Concise is Key

The context window is a public good. Skills share it with system prompt, conversation history, other skills, and the user request.

Default assumption: Claude is already very smart. Only add context Claude doesn't already have. For each piece of content, ask: "Does Claude really need this? Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations. See references/official-examples.md for how Anthropic's own skills demonstrate this — ranging from 33-line reference skills to 400-line generative skills, each sized appropriately for their domain.

Workflow Routing

Quick Start

Create a New Skill

bun scripts/init-skill.ts <skill-name> --path <output-directory>
# Example:
bun scripts/init-skill.ts my-awesome-skill --path .claude/skills

Validate and Package

bun scripts/validate-skill.ts <skill-folder>
bun scripts/package-skill.ts <skill-folder> [output-dir]

Skill Creation Workflow (7 Phases)

Follow these phases in order. Each phase has specific deliverables and exit criteria.

Phase 1: UNDERSTAND

Goal: Define concrete use cases and trigger conditions.

Questions to Ask:

1. •"What specific scenarios trigger this skill?"
2. •"Can you provide 2-3 concrete use cases?" (with trigger, steps, result format)
3. •"What keywords should activate this skill?"
4. •"What inputs does it receive? What outputs does it produce?"
5. •"What tools are needed (built-in or MCP)?"

Use Case Format (from Anthropic guide):

Use Case: [Name]
Trigger: User says "[phrase]" or "[phrase]"
Steps:
  1. [Step with tool/MCP call if applicable]
  2. [Step]
Result: [Concrete outcome]

Deliverables:

• •2-3 concrete use cases in the format above
• •Trigger condition list
• •Expected input/output format

Exit Criteria: Clear understanding of skill purpose, trigger conditions, and use cases.

Phase 2: PLAN

Goal: Design structure and identify reusable content.

Content Type Decision:

Freedom Level Decision:

Skill Pattern Selection (choose one):

Deliverables:

• •Directory structure design
• •Progressive Disclosure strategy
• •Selected skill pattern

Phase 3: INITIALIZE

Goal: Create skill directory and template files.

bun scripts/init-skill.ts <skill-name> --path <output-directory>

Creates:

skill-name/
├── SKILL.md              # Template with placeholders
├── scripts/
│   └── example.ts
├── references/
│   └── guide.md
└── assets/
    └── .gitkeep

Post-init: Delete unnecessary directories. Not all skills need all three resource types.

Phase 4: IMPLEMENT

4.1 Write Frontmatter

---
name: skill-name                    # Required: kebab-case, max 64 chars, match dir name
description: [What it does] in natural prose. Use when [specific triggers/contexts].
  Supports [key capabilities]. Include trigger phrases naturally in the sentence
  flow — do NOT use structured labels like "USE WHEN:" or bullet lists.
# --- Optional fields ---
# license: MIT
# compatibility: Requires Node.js 18+
# allowed-tools: "Bash(python:*) WebFetch"   # Restrict tool access for security
---

Description field rules (see references/frontmatter-spec.md):

• •Natural prose — write 1-3 sentences, not structured labels or bullet lists
• •Weave trigger phrases into natural sentences (e.g., "Use when users want to..." not USE WHEN:\n- "keyword")
• •Under 1024 characters
• •No XML angle brackets (< or >)
• •Add "Do NOT use for..." only if realistic confusion exists with similar skills
• •See references/official-examples.md for real Anthropic skill descriptions

Security considerations:

• •No XML angle brackets in frontmatter (appears in system prompt — injection risk)
• •No "claude" or "anthropic" in skill name (reserved by Anthropic)
• •YAML uses safe parsing (no code execution)
• •Use allowed-tools to restrict tool access when the skill should only use specific tools

See references/frontmatter-spec.md for complete spec.

4.2 Write SKILL.md Body

Design the body structure around your skill's domain — there is no one-size-fits-all template. Study references/official-examples.md for how Anthropic's own skills structure their bodies.

Observed patterns from official skills:

Key principle: Let the domain dictate the structure. A 33-line reference skill and a 400-line generative art skill should look nothing alike.

Optional elements (include only when they add value):

• •Workflow Routing table — only if the skill has multiple distinct workflows (e.g., "create" vs "validate")
• •Examples section — helpful for user-facing skills with trigger phrases
• •Troubleshooting section — helpful for skills involving scripts or MCP integrations
• •Reference Files section — when bundled resources exist in references/, scripts/, or assets/

Writing best practices (see references/writing-guide.md):

• •Be specific and actionable (not "validate the data" but run scripts/validate.py --input {file})
• •Reference bundled resources clearly (Before writing queries, consult references/api-patterns.md)
• •Put critical instructions at the top
• •Match Degrees of Freedom to task fragility (see writing-guide.md)

Output format guidance (see references/output-patterns.md):

• •Strict template: API contracts, data exports — use exact template with ALWAYS prefix
• •Flexible template: Analysis, docs — template with "adjust as needed"
• •Examples pattern: Style-sensitive output — provide 2-3 input/output pairs

4.3 Implement Scripts (TypeScript/JavaScript)

• •Test ALL scripts by actually running them
• •Include helpful error messages
• •Handle edge cases gracefully

4.4 Write References

• •Keep SKILL.md under 500 lines (under 5,000 words)
• •Move detailed content to references/
• •Always link references from SKILL.md

4.5 Critical Rules

• •SKILL.md must be exactly SKILL.md (case-sensitive)
• •Folder naming: kebab-case only (my-skill not My_Skill)
• •No README.md inside skill folder (documentation goes in SKILL.md or references/)
• •No deeply nested references — keep 1 level deep

Phase 5: VALIDATE

bun scripts/validate-skill.ts <skill-folder>

Validation Checklist:

See workflows/validate-skill.md for full validation workflow.

Phase 6: TEST

Goal: Verify skill triggers correctly and produces expected output.

6.1 Triggering Tests:

Should trigger:
- "[obvious trigger phrase 1]"
- "[paraphrased request]"
- "[alternative wording]"

Should NOT trigger:
- "[unrelated query 1]"
- "[similar but out-of-scope query]"

6.2 Functional Tests:

Test: [Scenario name]
Given: [Input conditions]
When: Skill executes workflow
Then:
  - [Expected outcome 1]
  - [Expected outcome 2]
  - No errors

6.3 Performance Comparison (optional — for distribution/sharing):

• •Compare same task WITH and WITHOUT skill
• •Measure: tool calls, total tokens, user corrections needed
• •Most useful when proving value to external users; skip for internal-only skills

See references/testing-guide.md for iteration signals and complete testing methodology.

Phase 7: PACKAGE

bun scripts/package-skill.ts <skill-folder> [output-dir]

Output: <skill-name>.skill file (ZIP format with .skill extension)

Post-Package:

1. •Test the packaged skill in target environment
2. •Collect usage feedback
3. •Iterate based on real usage (go back to Phase 6)

Progressive Disclosure Patterns

Pattern 1: High-level Guide with References

# Main Skill

## Quick Start

[Essential instructions]

## Advanced Features

- **Feature A**: See [references/feature_a.md](references/feature_a.md)

Pattern 2: Conditional Details

## Basic Usage

[Simple instructions]

## Advanced (when needed)

**For complex scenarios**: See [references/advanced.md](references/advanced.md)

What NOT to Include

A skill should only contain files that directly support its functionality. Do NOT create:

• •README.md — documentation goes in SKILL.md or references/
• •INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md
• •User-facing documentation, setup guides, or process notes
• •Any auxiliary context about the creation process itself

Rule: If it's not needed by an AI agent to do the job, it doesn't belong in the skill.

Anti-Patterns

References

• •Official Examples: references/official-examples.md — real Anthropic skill frontmatter and body patterns
• •Frontmatter Spec: references/frontmatter-spec.md
• •Writing Guide: references/writing-guide.md — description field, body structure, degrees of freedom
• •Output Patterns: references/output-patterns.md — template, examples, and validation patterns
• •Skill Patterns: references/skill-patterns.md — 5 architecture patterns
• •Testing Guide: references/testing-guide.md
• •Workflow Patterns: references/workflows.md
• •Skill Template: assets/templates/skill-template.md