Skill Shaper

A guide for creating effective skills that extend Claude's capabilities.

Your job is to figure out where the user is in this process and jump in. Maybe they have a workflow they want to capture ("turn this into a skill"). Maybe they want to create something from scratch. Maybe they have an existing skill that needs work. Be flexible — if the user doesn't want evals, skip them. Adapt your language to their technical level.

Communication

Pay attention to cues about the user's familiarity with technical terms:

"Evaluation" and "benchmark" are borderline OK for most users
"JSON" and "assertion" need signals that the user knows what they mean
When in doubt, briefly explain terms with a short definition

Step 1: Capture Intent

Start by understanding what the user wants. The conversation may already contain a workflow to capture — check history for tools used, steps taken, corrections made.

Key questions (don't ask all at once — start with the most important):

What should this skill enable Claude to do?
When should it trigger? Collect 5+ trigger queries and 3+ negative queries (things that should NOT trigger it)
What's the expected output format?

Check available MCPs — if useful for research (searching docs, finding similar skills), research in parallel via subagents if available.

Define success criteria before moving on: trigger queries, minimum acceptable output quality.

Step 2: Plan Reusable Contents

Identify the skill's category — this affects directory structure, testing approach, and templates:

Document/Asset Creation — produces files (PDFs, images, documents)
Workflow Automation — orchestrates multi-step processes
MCP Enhancement — wraps external tools with specialized knowledge

See references/skill-categories.md for detailed guidance.

Analyze each concrete example to identify what to bundle:

Pattern	Signal	Bundle As
Same code rewritten each time	PDF rotation logic	`scripts/rotate_pdf.py`
Same boilerplate needed	Frontend starter code	`assets/hello-world/`
Complex domain knowledge	API schemas, policies	`references/api_docs.md`
Template with variable parts	Report structure	`references/template.md`

Step 3: Initialize

For new skills, always run the init script:

python3 scripts/init_skill.py <skill-name> --path <directory> [--category <type>]

Categories: document-creation, workflow, mcp-enhancement (default: generic).

Each category generates a tailored SKILL.md template with relevant patterns, plus a .skill-eval/ directory with starter eval files.

Skip this step if updating an existing skill.

Step 4: Write the Skill

This is where the skill comes to life. Read references/authoring-best-practices.md before writing — it covers the principles below in depth with examples.

Description (Most Important)

The description is the primary triggering mechanism. Make it pushy — assertive and territory-claiming:

Weak: "A tool for creating PDF documents from markdown."

Strong: "Generate production-quality PDF documents from markdown content with professional typography and brand-consistent styling. Use this skill whenever the user wants to create a PDF, render markdown to PDF, generate a report, produce a document, or needs any kind of formatted output from text content."

Guidelines:

Use imperative form ("Generate...", "Process...", "Create...")
Focus on user intent, not implementation
List specific trigger contexts and keywords
Include both what it does AND when to use it
Aim for 100-200 words, max 1024 characters
Generalize: cover the category, not just specific examples

Body

Explain the why. Today's LLMs are smart. They have good theory of mind and when given a good harness can go beyond rote instructions. If you find yourself writing MUST or NEVER in all caps, reframe as reasoning:

Before: "ALWAYS validate output before returning."

After: "Validation catches formatting errors that are invisible in the editor but break the final PDF — run validate.py after every render."

Keep prompts lean. Challenge every paragraph: "Does this justify its token cost?" Prefer concise examples over verbose explanations. The context window is a shared resource.

Progressive disclosure. Keep SKILL.md body under 500 lines. Split content into reference files when approaching this limit. Each reference file should be clearly linked from SKILL.md with guidance on when to read it.

Bundled resources:

scripts/ — Deterministic code that's rewritten repeatedly. Execute without loading into context.
references/ — Documentation loaded as needed. Include grep patterns for large files (>10k words).
assets/ — Files used in output (templates, fonts, images). Not loaded into context.

See references/output-patterns.md for template and visual output patterns. See references/workflows.md for sequential, conditional, iterative, and multi-MCP patterns.

Specification Compliance

See references/skill-specification.md for:

Frontmatter constraints (name: max 64 chars, hyphen-case; description: max 1024 chars)
Supported frontmatter fields (name, description, allowed-tools, license, compatibility, context, agent, hooks, model, user-invocable, argument-hint, disable-model-invocation)
String substitutions ($ARGUMENTS, $N, ${CLAUDE_SESSION_ID})
Dynamic context injection (!command`` preprocessing)
Validation rules

Step 5: Validate and Package

Validation

Primary: skills-ref validate <path/to/skill-folder>

If not installed: uv pip install -e deps/agentskills/skills-ref/

Fallback: python3 scripts/quick_validate.py <path/to/skill-folder>

Packaging

python3 scripts/package_skill.py <path/to/skill-folder> [output-dir]

Validates automatically, then creates a .skill ZIP file.

Step 6: Test, Eval, Ship

Quick Manual Testing

Before automated evals, do a quick sanity check:

Try 5+ paraphrased trigger queries — does the skill activate?
Try 3+ unrelated queries — does it stay quiet?
Run the primary workflow end-to-end with realistic inputs
Test at least one edge case

Automated Evaluation

For thorough testing, use the skill-eval skill. It provides:

Automated eval scaffolding from trigger queries
Two-tier grading (programmatic + agent)
Token budget analysis
Regression testing with pinned baselines
Description optimization loop with train/test split
Interactive HTML review viewer

Ship Pipeline

When the skill is ready: validate → eval (all checks pass, 80%+ assertions) → quality gate (under 500 lines, no TODOs, refs exist, token budget OK) → package.

See references/distribution-guide.md for distribution channels and positioning.

Reference Materials

Consult these based on your needs during skill creation:

references/skill-specification.md — Frontmatter constraints, naming rules, validation rules, supported fields, string substitutions, dynamic context injection
references/authoring-best-practices.md — Pushy descriptions (5+ examples), explain the why, writing patterns, keep prompts lean, extract repeated work, pre-distribution checklist
references/workflows.md — Sequential, conditional, iterative, plan-validate-execute, multi-MCP, subagent delegation, visual output patterns
references/output-patterns.md — Template, example, visual output, and structured data patterns
references/testing-and-debugging.md — Pointer to skill-eval, two-tier testing, description testing, regression testing, debugging triggers and context
references/skill-categories.md — Document/asset creation, workflow automation, MCP enhancement, subagent-based skills, knowledge/reference skills, category-to-template mapping
references/distribution-guide.md — Channels, packaging formats, plugin distribution, managed settings, ship-skill pipeline, quality gate checklist

skill-shaper