---

name: skills-development version: 1.3.0 description: This skill should be used when creating skills, writing SKILL.md files, or when "create skill", "new skill", "validate skill", or "SKILL.md" are mentioned. metadata: related-skills: - claude-agent-development - claude-plugin-development - claude-command-authoring - codex-configuration - claude-code-configuration user-invocable: true allowed-tools: Read Write Edit Grep Glob Bash TodoWrite AskUserQuestion

Skills Development

Create skills that follow the Agent Skills specification—an open format supported by Claude Code, Cursor, VS Code, GitHub, and other agent products.

Workflow

1. Discovery — Understand what the skill should do
2. Archetype Selection — Choose the best pattern
3. Initialization — Create skill structure from template
4. Customization — Tailor to specific needs
5. Validation — Verify quality before committing

Phase 1: Discovery

Ask about the skill:

• What problem does this skill solve?
• What are the main capabilities?
• What triggers should invoke it? (phrases users would say)
• Where should it live? (personal ~/.claude/skills/, project .claude/skills/, or plugin)

Phase 2: Archetype Selection

Templates in templates/skill-archetypes/.

Phase 3: Initialization

Run the init script:

Copybun run ${CLAUDE_PLUGIN_ROOT}/skills/skills-development/scripts/init-skill.ts <skill-name> <output-dir> --template <archetype>

Output directories:

• Personal: ~/.claude/skills/<skill-name>/
• Project: .claude/skills/<skill-name>/
• Plugin: <plugin-dir>/skills/<skill-name>/

Phase 4: Customization

Directory Structure

Copyskill-name/
├── SKILL.md           # Required: instructions + metadata
├── scripts/           # Optional: executable code
├── references/        # Optional: documentation
└── assets/            # Optional: templates, resources

Frontmatter

Copy---
name: skill-name
description: What it does and when to use it. Include trigger keywords.
license: Apache-2.0                    # optional
compatibility: Requires git and jq     # optional
metadata:                              # optional
  author: your-org
  version: "1.0"
allowed-tools: Read Grep Glob          # optional, experimental
user-invocable: true                   # optional, makes skill a /command
---

user-invocable

When user-invocable: true, the skill becomes callable as a slash command:

Copy---
name: code-review
description: Reviews code for bugs and best practices...
user-invocable: true
---

Users can then invoke with /code-review instead of waiting for auto-activation. The skill content becomes the command prompt.

Custom Frontmatter

Custom fields must be nested under metadata:

Copy---
name: my-skill
description: ...
metadata:
  author: your-org
  version: "1.0"
  category: development
  tags: [typescript, testing]
---

Top-level custom fields are not allowed and may cause parsing errors.

Description Formula

[WHAT] + [WHEN] + [TRIGGERS]

Copydescription: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Checklist:

• Explains WHAT (capabilities)
• States WHEN (trigger conditions)
• Includes 3-5 trigger KEYWORDS
• Uses third-person voice
• Under 200 words

Per-Archetype Customization

api-wrapper:

• Update scripts/client.ts with API endpoints
• Add auth instructions
• Create references/endpoints.md if API is large

document-processor:

• Update scripts/process.ts with format logic
• Add library dependencies
• Document supported operations

dev-workflow:

• Update scripts/run.ts with commands
• Add safety checks for destructive operations
• Document available commands

research-synthesizer:

• Define source priority order
• Specify output format
• Set citation style

Phase 5: Validation

Validate before committing. Use the CLI or run checks manually:

Copyskills-ref validate ./my-skill

Validation Checklist

A. YAML Frontmatter

• Opens with --- on line 1, closes with ---
• name and description present (required)
• Uses spaces, not tabs
• Special characters quoted

B. Naming

• Lowercase, numbers, hyphens only (1-64 chars)
• Matches parent directory name
• No --, leading/trailing hyphens
• No anthropic or claude in name

C. Description Quality

• WHAT: Explains capabilities
• WHEN: States "Use when..." conditions
• TRIGGERS: 3-5 keywords users would say
• Third-person voice (not "I can" or "you can")

D. Structure

• SKILL.md under 500 lines
• All referenced files exist
• No TODO/placeholder markers
• Progressive disclosure (details in references/)

Review Checks

After validation passes, review for quality:

Report Format

Copy# Skill Check: {skill-name}

**Status**: PASS | WARNINGS | FAIL
**Issues**: {critical} critical, {warnings} warnings

## Critical (must fix)
1. {issue with fix}

## Warnings (should fix)
1. {issue with fix}

## Strengths
- {what's done well}

Common Fixes

Vague description:

Copy# Before
description: Helps with PDF files

# After
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDFs, forms, or document extraction.

Wrong voice:

Copy# Before
description: I can help you process data files

# After
description: Processes data files and converts between formats (CSV, JSON, XML). Use when working with data files or format conversion.

Priority Levels

• Critical: Invalid YAML, missing required fields, broken references
• Important: Vague descriptions, wrong voice, missing triggers
• Nice-to-have: Additional examples, better organization

Core Principles

Concise is key

Context window is shared. Only include what the agent doesn't already know. Challenge each paragraph—does it justify its token cost?

Third-person descriptions

Descriptions inject into system prompt:

• ✓ "Extracts text from PDFs"
• ✗ "I can help you extract text from PDFs"

Progressive disclosure

Keep SKILL.md under 500 lines. Move details to:

• references/ - Detailed docs, API references
• scripts/ - Executable utilities (code never enters context)
• assets/ - Templates, data files

Token loading:

1. Metadata (~100 tokens): name + description at startup
2. Instructions (<5000 tokens): SKILL.md body when activated
3. Resources (as needed): files loaded only when referenced

Degrees of freedom

Match instruction specificity to task requirements:

• High freedom (text): Multiple valid approaches, use judgment
• Medium freedom (pseudocode): Preferred pattern with variation allowed
• Low freedom (scripts): Exact sequence required, no deviation

See patterns.md for detailed examples.

Naming Requirements

• Lowercase letters, numbers, hyphens only
• Cannot start/end with hyphen or contain --
• Must match parent directory name
• Cannot contain anthropic or claude

Recommended: Gerund form (processing-pdfs, reviewing-code)

Tool Restrictions

Use allowed-tools to limit capabilities (experimental):

Copy# Read-only
allowed-tools: Read Grep Glob

# With shell access
allowed-tools: Bash(git:*) Bash(jq:*) Read

# Full access (default)
# Omit field entirely

After Creation

1. Validate: Run Phase 5 checklist or skills-ref validate
2. Test: Ask a question that should trigger it
3. Iterate: Fix issues until passing
4. Share: Commit to git or distribute via plugin

Troubleshooting

Copy# Find all skills
find ~/.claude/skills .claude/skills -name "SKILL.md" 2>/dev/null

# Check for tab characters (YAML requires spaces)
grep -P "\t" SKILL.md

# Find broken markdown links
grep -oE '\[[^]]+\]\([^)]+\)' SKILL.md | while read link; do
  file=$(echo "$link" | sed 's/.*(\(.*\))/\1/')
  [ ! -f "$file" ] && echo "Missing: $file"
done

References

• patterns.md - Degrees of freedom, script design, variant organization, writing patterns
• best-practices.md - Community patterns, testing strategies, advanced techniques
• quick-reference.md - Fast checklist and one-liners
• implementations.md - Per-tool storage paths
• invocations.md - How tools activate skills
• compatibility.md - Path compatibility matrix

Platform-Specific Implementation

Each tool has specific implementation details beyond the common spec:

• Claude Code: claude.md - Tool restrictions syntax, --debug testing, troubleshooting, command/hook integration
• Codex CLI: codex.md - Discovery paths, $skill-name invocation, AGENTS.md relationship, feature flags, built-in skills

See implementations.md for storage paths and platform-specific notes.

External Resources

• Agent Skills Specification
• Best Practices Guide
• skills-ref Validation Library