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

• Discovery — Understand what the skill should do

• Archetype Selection — Choose the best pattern

• Initialization — Create skill structure from template

• Customization — Tailor to specific needs

• 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

Archetype Use When Example

simple Basic skill without scripts Quick reference, style guide

api-wrapper Wrapping external APIs GitHub API, Stripe API

document-processor Working with file formats PDF extractor, Excel analyzer

dev-workflow Automating development tasks Git workflow, project scaffolder

research-synthesizer Gathering and synthesizing information Competitive analysis, literature review

Templates in templates/skill-archetypes/ .

Phase 3: Initialization

Run the init script:

bun 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

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

Frontmatter

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

Field Required Constraints

name

Yes 1-64 chars, lowercase/numbers/hyphens, must match directory

description

Yes 1-1024 chars, describes what + when

user-invocable

No Boolean, enables /skill-name command (Claude Code)

license

No License name or reference

compatibility

No 1-500 chars, environment requirements

allowed-tools

No Space-delimited tool list (experimental)

metadata

No Object for custom fields (see below)

user-invocable

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

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 :

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]

description: 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:

skills-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:

Aspect Check

Discoverability Would Claude know when to activate?

Conciseness Does each paragraph justify its token cost?

Clarity Are instructions step-by-step and actionable?

Report Format

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:

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:

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:

• Metadata (~100 tokens): name + description at startup

• Instructions (<5000 tokens): SKILL.md body when activated

• 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):

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

• Validate: Run Phase 5 checklist or skills-ref validate

• Test: Ask a question that should trigger it

• Iterate: Fix issues until passing

• Share: Commit to git or distribute via plugin

Troubleshooting

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