Creating Skills

Create portable, reusable expertise that extends Claude's capabilities across contexts.

When to Create Skills

Skills are appropriate when:

Capability needed across multiple projects/conversations
Procedural knowledge that applies broadly (not project-specific)
Instructions should activate automatically on trigger patterns
Want portable expertise that loads progressively on-demand

Not appropriate when:

Context is project-specific (use Project instructions instead)
One-off task (use standalone prompt instead)
See main crafting-instructions guidance for detailed decision framework

Skill Structure

Every skill is a directory containing:

SKILL.md (required): Frontmatter + imperative instructions
scripts/ (optional): Executable code for deterministic operations
references/ (optional): Detailed docs loaded on-demand
assets/ (optional): Templates/files used in output

Create this structure directly:

mkdir -p skill-name/{scripts,references,assets}

Delete unused directories before packaging.

Naming Convention

Use gerund form (verb + -ing):

✅ processing-pdfs, analyzing-data, creating-reports
❌ pdf-helper, data-tool, report-maker

Requirements:

Lowercase letters, numbers, hyphens only
Max 64 characters
No reserved words (anthropic, claude)

Frontmatter Requirements

---
name: skill-name
description: [Action verbs] [what]. Use when [trigger patterns].
---

name: Follow naming convention above

description: (max 1024 chars)

Lead with action verbs: "Create", "Generate", "Analyze", "Extract" (imperative, not descriptive)
State capabilities concisely: What the skill does in active voice
Explicit trigger section: "Use when" followed by trigger conditions
Trigger specificity: File types (.docx, .pptx), keywords (chart, visualize), task verbs (debug, optimize), user phrases
No XML tags, no procedural steps

Strong examples:

"Create and edit PowerPoint presentations (.pptx) with layouts and formatting. Use when users request slide creation, mention presentations, reference .pptx files, or need pitch deck generation."
"Analyze and optimize SQL query performance. Use when users report slow queries, share EXPLAIN output, request optimization, or need database performance tuning."
"Generate interactive data visualizations using Vega-Lite. Use when users request charts, want to plot data, mention visualizations, or upload CSV/JSON with charting intent."

Weak examples:

"I can help create presentations" (first person, passive, no triggers)
"Presentation creator" (descriptive noun, no actions, no triggers)
"Creates PowerPoint presentations. Use when users mention slides." (descriptive "Creates", vague trigger, incomplete conditions)
"Advanced presentation tool with animations and transitions" (implementation details, no actions or triggers)

Pattern: [Verb] [Verb] [Verb] [object/domain]. Use when [trigger condition 1], [trigger condition 2], or [trigger condition 3].

The description determines skill activation—imperative verbs and explicit triggers are critical.

Writing Effective SKILL.md

Apply crafting-instructions core principles when writing skill instructions:

Imperative Construction: Direct commands, not suggestions
Strategic Over Procedural: Goals and decision frameworks, not step-by-step
Trust Base Behavior: Claude knows basics, specify only skill-specific needs
Positive Directive Framing: State what to do, not what to avoid
Provide Context: Explain WHY for non-obvious requirements

Model-aware skill writing: Skills may be executed by any Claude model. Write for robustness:

Lead with goals (Opus) but include decision frameworks (Sonnet)
Provide WHY context (both benefit, Opus leverages more)
Include 1-2 examples (Sonnet benefits; Opus uses if helpful)
State explicit edge case handling rather than assuming inference

If skill is known to run on a specific model, calibrate:

Sonnet: More procedural detail, explicit conditions, concrete examples
Opus: More strategic, principle-based, trust judgment for unstated cases

See main crafting-instructions guidance (§ Core Optimization Principles) for details.

Bundled Resources Patterns

scripts/

Add when Claude would repeatedly write similar code:

Validation logic (schema checking, format verification)
Complex transformations (data normalization, format conversion)
Deterministic operations requiring exact consistency

Scripts should have explicit error handling and clear variable names.

references/

Add when:

SKILL.md approaching 500 lines
Detailed domain knowledge (API docs, schemas, specifications)
Content applies to specific use cases only, not core workflow

Keep references one level deep (avoid file1 → file2 → file3 chains).

assets/

Add for:

Templates users will receive in output
Files copied/referenced but not loaded into context
Images, fonts, static resources

Assets save tokens—they're used but not read into context.

Decision framework: Will Claude repeatedly generate similar code? → scripts/. Is there extensive domain knowledge? → references/. Are there output templates? → assets/. Otherwise SKILL.md only.

Progressive Disclosure

Skills load in three tiers:

Metadata (name + description): Always loaded for all skills
SKILL.md body: Loaded when skill activates
Bundled resources: Loaded as Claude reads them

Keep SKILL.md focused on core workflows (~500 lines max). Move detailed content to references/ for on-demand loading. This enables context-efficient skill ecosystems.

Token Efficiency

Challenge each line: Does Claude really need this explanation? Can I assume Claude knows this? Does this justify its token cost?

Prefer concise patterns:

Code examples over verbose explanations
Decision frameworks over exhaustive lists
Strategic goals over procedural steps

Packaging & Delivery

Create ZIP archive:

cd /home/claude
zip -r /mnt/user-data/outputs/skill-name.zip skill-name/

Verify contents:

unzip -l /mnt/user-data/outputs/skill-name.zip

Show user the packaged structure:

tree skill-name/
# or
ls -lhR skill-name/

Provide download link:

[Download skill-name.zip](computer:///mnt/user-data/outputs/skill-name.zip)

Version Control (Optional)

For skills under active development, track changes:

cd /home/claude/skill-name
git init && git add . && git commit -m "Initial: skill structure"

After modifications:

git add . && git commit -m "Update: description of change"

See versioning-skills for advanced patterns (rollback, branching, comparison).

Best Practices

Structure:

Lead with clear overview of what skill enables
Group related instructions together
Use headings that describe goals, not procedures
Reference other skills/resources when appropriate

Instructions:

Write TO Claude (imperative commands) not ABOUT Claude (documentation)
Assume Claude's intelligence—avoid over-explaining basics
Show code examples for complex patterns
Specify success criteria, let Claude determine approach
Use fully qualified names for MCP tools: ServerName:tool_name (prevents collisions)

Content:

Keep frequently-used guidance in SKILL.md
Move detailed/specialized content to references/
Include WHY context for non-obvious requirements
Use consistent terminology throughout

Resources:

Only add bundled resources that solve real problems
Scripts should have error handling and clear outputs
References should be focused and topic-specific
Delete unused directories before packaging

Testing:

Test with 3+ real scenarios (simple, complex, edge case)
Verify skill activates on expected trigger patterns
Confirm bundled resources are accessible and functional
Iterate based on actual usage, not assumptions

Quality Checklist

Before providing skill to user:

Metadata:

Name: lowercase, hyphens, gerund form, max 64 chars
Description: third person, includes WHAT + WHEN triggers, max 1024 chars, no XML