Skill Creator

Skill Creator

Create effective Claude Skills using progressive disclosure.

When to Create a Skill

Create a skill when you notice:

• Repeating context across conversations
• Domain expertise needed repeatedly
• Project-specific knowledge Claude should know automatically

Progressive Disclosure

Skills load in 3 levels:

1. Metadata (~27 tokens optimal, ~100 max) - YAML frontmatter for triggering 2. Instructions (<50 lines recommended, 500 max) - SKILL.md body with core patterns 3. Resources (unlimited) - references/ scripts/ assets/ loaded on demand

Key: Keep Levels 1 & 2 lean. Move details to Level 3. Use npx claude-skills-cli validate to check budgets.

Structure

my-skill/
├── SKILL.md       # Core instructions + metadata
├── references/    # Detailed docs (loaded as needed)
├── scripts/       # Executable operations
└── assets/        # Templates, images, files

References

• quick-start.md - Creating your first skill
• writing-guide.md - Writing effective skills
• development-process.md - Step-by-step workflow
• skill-examples.md - Patterns and examples
• cli-reference.md - CLI tool usage
• anthropic-resources.md - Official best practices
• mcp-integration.md - MCP server integration patterns
• testing-guide.md - Testing methodology and checklists
• distribution.md - Sharing and distributing skills
• troubleshooting.md - Common issues and fixes

Anthropic Resources - Official Guidance

Key insights from Anthropic's official Agent Skills documentation.

Sources:

• Agent Skills Overview
• Engineering Blog
• Product Announcement

---

The Progressive Disclosure System

Core Design Principle: Skills load information in stages as needed, rather than consuming context upfront.

The 3-Level Loading System

\*No practical limit - files only load when accessed

Why This Matters

"Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix, skills let Claude load information only as needed."

>

— Anthropic Engineering Blog

Benefits:

• Install many skills without context penalty
• Claude only knows each skill exists and when to use it (Level 1)
• Detailed content doesn't consume tokens until needed
• Effectively unbounded context per skill (via Level 3)

---

How Skills Work

Skill Discovery and Loading

1. Startup: Claude pre-loads name and description of every installed skill into system prompt 2. User request: User makes a request that might need a skill 3. Skill matching: Claude scans available skills to find relevant matches 4. Skill loading: If relevant, Claude reads SKILL.md from filesystem via bash 5. On-demand access: Claude reads additional files (references/, scripts/) as needed

The Filesystem Architecture

Skills run in a code execution environment where Claude has:

• Filesystem access: Skills exist as directories on a virtual machine
• Bash commands: Claude uses bash to read files and execute scripts
• Code execution: Scripts run without loading code into context

Key insight: Script code never enters the context window. Only the output does. This makes scripts far more token-efficient than generating equivalent code on the fly.

---

Official Best Practices

1. Start with Evaluation

"Identify specific gaps in your agents' capabilities by running them on representative tasks and observing where they struggle or require additional context. Then build skills incrementally to address these shortcomings."

Process:

• Use Claude on real tasks
• Notice where it struggles
• Create skills to fill gaps
• Test and iterate

2. Structure for Scale

"When the SKILL.md file becomes unwieldy, split its content into separate files and reference them."

Guidelines:

• Keep SKILL.md under ~5k words
• Split mutually exclusive contexts into separate files
• Use code for both execution and documentation
• Make it clear whether Claude should run or read scripts

3. Think from Claude's Perspective

"Monitor how Claude uses your skill in real scenarios and iterate based on observations: watch for unexpected trajectories or overreliance on certain contexts."

Key areas:

• name and description drive skill triggering
• Claude decides whether to use the skill based on metadata
• Observe actual usage patterns, not assumed ones

4. Iterate with Claude

"As you work on a task with Claude, ask Claude to capture its successful approaches and common mistakes into reusable context and code within a skill."

Workflow (Claude A creates, Claude B tests):

1. Complete a task with Claude A using normal prompting 2. Identify reusable patterns from the conversation 3. Ask Claude A to create a skill capturing those patterns 4. Review for conciseness — remove what Claude already knows 5. Test with Claude B (fresh instance with skill loaded) on similar tasks 6. If Claude B struggles, return to Claude A with specifics to refine

"Claude models understand the Skill format and structure natively. You don't need special system prompts or a 'writing skills' skill to get Claude to help create Skills."

5. Set Appropriate Degrees of Freedom

Match the level of specificity to the task's fragility and variability.

• High freedom (text instructions): Output varies by context, Claude's judgment adds value
• Medium freedom (pseudocode/scripts with params): Process is consistent but details vary
• Low freedom (exact scripts): Exact execution matters — migrations, compliance, deployments

6. Test with All Models

"Skills act as additions to models, so effectiveness depends on the underlying model."

What works for Opus may need more detail for Haiku. If using across models, aim for instructions that work with all of them.

---

Writing for Claude

Skills as "Onboarding Guides"

"Building a skill for an agent is like putting together an onboarding guide for a new hire."

>

— Anthropic Engineering Blog

What this means:

• Focus on procedural knowledge ("how to do X")
• Include workflows, not just facts
• Provide examples of actual usage
• Capture organizational context

Skills Transform General → Specialized Agents

"Skills extend Claude's capabilities by packaging your expertise into composable resources for Claude, transforming general-purpose agents into specialized agents that fit your needs."

Examples:

• General Claude + Database skill = Database specialist
• General Claude + Auth skill = Security specialist
• General Claude + UI skill = Frontend specialist

---

The Skill Anatomy

Required Structure

Every skill must have:

skill-name/
└── SKILL.md          # Required

SKILL.md must have:

---
name: skill-name
description: What it does and when to use it
---

# Skill content...

Frontmatter Limits

Only name and description are required and universally supported. No other YAML fields are recognized in Claude Code.

Name restrictions:

• Lowercase letters, numbers, and hyphens only
• Cannot contain "anthropic" or "claude" (reserved words)
• Cannot contain XML tags (< or >)
• Prefer gerund form: processing-pdfs, analyzing-spreadsheets

Description restrictions:

• Cannot contain XML tags
• Write in third person (injected into system prompt)

Known discrepancy: Some Anthropic documentation references allowed-tools, license, compatibility, and metadata frontmatter fields. These fields are not supported in Claude Code and will be ignored. The Complete Guide PDF mentions them for API/claude.ai contexts only.

Optional Bundled Content

skill-name/
├── SKILL.md                    # Level 2: Instructions
├── references/                 # Level 3: Documentation
│   ├── detailed-guide.md
│   └── api-reference.md
├── scripts/                    # Level 3: Executable code
│   ├── validate.js
│   └── generate.sh
└── assets/                     # Level 3: Resources
    ├── template.json
    └── diagram.png

---

Code Execution in Skills

Why Include Scripts

"Large language models excel at many tasks, but certain operations are better suited for traditional code execution. For example, sorting a list via token generation is far more expensive than simply running a sorting algorithm."

>

— Anthropic Engineering Blog

When to use scripts:

• Efficiency: Operations that are cheaper to execute than generate
• Determinism: Tasks requiring consistent, repeatable results
• Complexity: Algorithms better suited to code than token generation

Script Execution Model

# Claude runs script
bash: node scripts/validate_form.js form.pdf

# Output (only this enters context)
✅ All form fields valid
Found 12 fillable fields

Context consumed: ~20 tokens (just the output) Alternative (Claude generates validation code): ~500 tokens

50x more efficient

---

Security Considerations

Trusted Sources Only

"We strongly recommend using Skills only from trusted sources: those you created yourself or obtained from Anthropic."

Risk: Malicious skills can:

• Direct Claude to invoke tools in harmful ways
• Execute code with unintended effects
• Exfiltrate data to external systems
• Compromise system security

Auditing Third-Party Skills

If you must use untrusted skills:

1. Review all files: SKILL.md, scripts, images, bundled resources 2. Check for unusual patterns:

• Unexpected network calls
• File access beyond skill scope
• Operations not matching stated purpose

3. Examine external sources: Skills fetching from URLs are risky 4. Verify dependencies: Check code dependencies and imports

Runtime Constraints

Runtime constraints vary by platform:

• Claude API: No network access, no runtime package installation, sandboxed execution
• Claude.ai: Varying network access depending on user/admin settings
• Claude Code: Full network access (same as any program on the user's machine), but global package installation is discouraged

---

Skills are Composable

"Skills stack together. Claude automatically identifies which skills are needed and coordinates their use."

>

— Anthropic Product Announcement

Example: Multi-Skill Task

User request: "Create a GitHub contact card with database-backed favorites"

Skills activated:

1. github-integration - Fetch profile data 2. database-patterns - Query favorites table 3. ui-components - Build card component 4. styling-patterns - Apply CSS/styles

Result: Skills work together naturally, each handling its domain.

---

Where Skills Work

Claude.ai

• Pre-built Skills: PowerPoint, Excel, Word, PDF (automatic)
• Custom Skills: Upload as zip (Settings > Capabilities > Skills)
• Sharing: Individual user only (not org-wide, no central admin management)

Claude API

• Pre-built Skills: Reference by skill_id (e.g., pptx, xlsx)
• Custom Skills: Upload via /v1/skills endpoints
• Sharing: Workspace-wide
• Requires beta headers: code-execution-2025-08-25, skills-2025-10-02, files-api-2025-04-14

Claude Code

• Custom Skills only: Filesystem-based (.claude/skills/ or ~/.claude/skills/)
• Sharing: Via git/version control or Claude Code Plugins

Claude Agent SDK

• Custom Skills: Filesystem-based in .claude/skills/
• Enable by including "Skill" in allowed_tools configuration

Important: Custom Skills do not sync across surfaces. Upload separately for each platform.

---

Key Quotes

On Progressive Disclosure

"Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable."

On Simplicity

"Skills are a simple concept with a correspondingly simple format. This simplicity makes it easier for organizations, developers, and end users to build customized agents and give them new capabilities."

On Filesystem Architecture

"Agents with a filesystem and code execution tools don't need to read the entirety of a skill into their context window when working on a particular task. This means that the amount of context that can be bundled into a skill is effectively unbounded."

On Purpose

"Think of Skills as custom onboarding materials that let you package expertise, making Claude a specialist on what matters most to you."

---

Official Resources

Documentation

• Agent Skills Overview
• Quickstart Tutorial
• Best Practices
• API Skills Guide
• Skills in Claude Code
• Skills in Agent SDK
• Agent Skills Standard

Guides

• The Complete Guide to Building Skills for Claude (PDF)
• Skills Cookbook

Examples

• Skills Repository

Articles

• Product Announcement
• Engineering Blog

---

Skill Categories

Skills generally fall into these categories:

Domain Knowledge Skills

Encode expertise about a specific domain, technology, or codebase:

• Project context and conventions
• API documentation and patterns
• Database schema and query patterns

Workflow Skills

Guide Claude through multi-step processes:

• Code review checklists
• Deployment procedures
• Testing workflows
• Data migration steps

Tool Integration Skills

Bridge Claude to external tools and systems:

• MCP server usage patterns (see mcp-integration.md)
• CLI tool documentation
• Service-specific workflows

Generator Skills

Create or transform content:

• Code scaffolding with scripts
• Document generation from templates
• Data transformation pipelines

---

Workflow Patterns

Linear Workflow

Skill guides Claude through ordered steps:

## Deployment Process
1. Run validation: `node scripts/validate.js`
2. Build the project
3. Run tests
4. Deploy to staging
5. Verify staging
6. Deploy to production

Decision Tree Workflow

Skill provides branching logic based on conditions:

## Error Handling
- If HTTP 401 → Re-authenticate, retry once
- If HTTP 429 → Wait and retry with backoff
- If HTTP 5xx → Log error, alert, do not retry

Iterative Workflow

Skill defines a loop for refinement:

## Review Cycle
1. Run linter
2. Fix reported issues
3. Run tests
4. If failures remain, return to step 2
5. Submit for review

---

Anti-Patterns (Official)

Avoid Deeply Nested References

Keep references one level deep from SKILL.md. Claude may partially read files when they're referenced from other referenced files.

Avoid Too Many Options

Provide a default with an escape hatch, not a menu of choices.

Avoid Time-Sensitive Information

Use "Old patterns" sections with <details> instead of date-conditional instructions.

Avoid Windows-Style Paths

Always use forward slashes. Unix paths work everywhere; Windows paths fail on Unix.

No README.md in Skill Folder

All documentation goes in SKILL.md or references/. Repository-level README is separate.

---

Official Workflow Patterns

Checklist Pattern

Provide a checklist Claude copies and tracks through multi-step tasks.

Feedback Loop Pattern

Run validator → fix errors → repeat until passing. Greatly improves output quality.

Plan-Validate-Execute Pattern

For complex tasks: create structured plan file → validate with script → execute. Catches errors before they propagate.

Template Pattern

Provide output templates. Match strictness to requirements — "ALWAYS use this exact structure" vs "sensible default, use judgment."

Examples Pattern

Input/output pairs for output-quality-dependent skills. Examples communicate style and detail better than descriptions.

Conditional Workflow Pattern

Guide Claude through decision points with branching logic.

---

Summary: The Anthropic Philosophy

Skills are:

• Composable (stack together)
• Portable (same format everywhere)
• Efficient (only load what's needed)
• Powerful (include executable code)

Build like:

• Onboarding guides (procedural knowledge)
• Specialized tools (domain expertise)
• Reference manuals (progressive detail)

Optimize for:

• Token efficiency (3-level loading)
• Claude's perspective (discovery via metadata)
• Real usage (iterate based on observation)
• Scalability (split when too large)

claude-skills-cli Reference

Complete command-line reference for the claude-skills-cli tool.

Installation

Global Installation

npm install -g claude-skills-cli
claude-skills-cli --version

Using npx (No Installation)

npx claude-skills-cli <command>

Using pnpm

pnpx claude-skills-cli <command>

Using bun

bunx claude-skills-cli <command>

As Dev Dependency

npm install --save-dev claude-skills-cli

# Use via package.json scripts
{
  "scripts": {
    "skill:init": "claude-skills-cli init",
    "skill:validate": "claude-skills-cli validate",
    "skill:package": "claude-skills-cli package"
  }
}

---

Commands

init - Create New Skill

Create a new skill directory with standard structure.

Syntax

claude-skills-cli init [options]

Options

\*Either --name or --path must be provided

Examples

# Create skill with default location (.claude/skills/)
npx claude-skills-cli init --name my-skill

# With description
npx claude-skills-cli init --name my-skill \
  --description "SQLite queries. Use when writing database operations"

# Custom path
npx claude-skills-cli init --path /custom/path/my-skill

Created Structure

.claude/skills/my-skill/
├── SKILL.md        # Main skill instructions
└── references/     # Level 3 detailed documentation

Name Validation

• Must be lowercase
• Must be kebab-case (alphanumeric with hyphens)
• No spaces or special characters
• Example valid names: database-queries, auth-patterns, ui-components

---

validate - Validate Skill Structure

Validate skill structure and progressive disclosure compliance.

Syntax

claude-skills-cli validate <skill-path> [options]

Options

Validation Modes

Examples

# Validate skill (default strict limits)
npx claude-skills-cli validate .claude/skills/my-skill

# Strict mode (warnings = errors)
npx claude-skills-cli validate .claude/skills/my-skill --strict

# Use Anthropic official limits
npx claude-skills-cli validate .claude/skills/my-skill --loose

# JSON output for CI
npx claude-skills-cli validate .claude/skills/my-skill --format json

Validation Checks

Level 1 (Metadata):

• Description length: <200 chars (optimal), <300 chars (warning), <1024 chars (max)
• Description includes trigger keywords ("Use when...", "Use for...", "Use to...")
• Name format (lowercase, kebab-case)
• Name length (<64 chars)
• Name matches directory name

Level 2 (SKILL.md Body):

• Line count: <50 (default), <150 (lenient), <500 (loose)
• Word count: <1000 (optimal), <5000 (max)
• Code blocks: 1-2 (optimal), ≤3 (good), >3 (warning)
• Sections: 3-5 (optimal), ≤8 (good), >8 (warning)
• "Quick Start" section present
• Links to references/ when body is long (>60 lines)
• No TODO placeholders

Level 3 (References):

• Referenced files exist (errors on broken links)
• No empty directories (warnings)
• Scripts are executable (warnings)
• Scripts have shebang (#!)

Exit Codes

---

doctor - Fix Common Issues

Automatically fix common skill issues.

Syntax

claude-skills-cli doctor <skill-path>

What It Fixes

Multi-line Descriptions: When formatters like Prettier wrap descriptions across multiple lines, Claude Code cannot recognize the skill. The doctor command:

1. Detects multi-line descriptions in YAML frontmatter 2. Adds # prettier-ignore comment before the description field 3. Reflows the description to a single line

Examples

# Fix multi-line description
npx claude-skills-cli doctor .claude/skills/my-skill

# Common workflow after formatting
npx prettier --write .claude/skills/my-skill/SKILL.md
npx claude-skills-cli doctor .claude/skills/my-skill
npx claude-skills-cli validate .claude/skills/my-skill

---

package - Create Distribution Zip

Package skill into a zip file for distribution.

Syntax

claude-skills-cli package <skill-path> [options]

Options

Examples

# Package skill (validates first)
npx claude-skills-cli package .claude/skills/my-skill

# Custom output directory
npx claude-skills-cli package .claude/skills/my-skill --output builds/

Distribution

The created zip can be:

1. Uploaded to Claude.ai (Settings > Capabilities > Skills) 2. Uploaded via API (/v1/skills endpoint) 3. Shared with team members

---

install - Install Bundled Skill

Install a skill from a bundled collection.

Syntax

claude-skills-cli install

---

stats - Skill Overview

Show overview of all skills in a directory.

Syntax

claude-skills-cli stats [directory]

Arguments

Example

npx claude-skills-cli stats .claude/skills

---

add-hook - Add Activation Hook

Add a skill activation hook to .claude/settings.json.

Syntax

claude-skills-cli add-hook

Adds a UserPromptSubmit hook that automatically evaluates and activates skills.

---

Common Workflows

Create and Validate New Skill

# 1. Create skill
npx claude-skills-cli init --name database-queries \
  --description "SQLite queries. Use when writing SELECT, INSERT, UPDATE"

# 2. Edit SKILL.md
vim .claude/skills/database-queries/SKILL.md

# 3. Add references
vim .claude/skills/database-queries/references/schema.md

# 4. Validate
npx claude-skills-cli validate .claude/skills/database-queries

# 5. Package for distribution
npx claude-skills-cli package .claude/skills/database-queries

Strict Validation in CI

# package.json
{
  "scripts": {
    "test:skills": "claude-skills-cli validate .claude/skills/* --strict"
  }
}

# Run in CI
npm run test:skills

Batch Validate All Skills

# Bash script to validate all skills
for skill in .claude/skills/*/; do
  echo "Validating $skill"
  npx claude-skills-cli validate "$skill" || exit 1
done

---

Resources

• GitHub Repository
• Anthropic Skills Documentation
• Anthropic Skills Repository

Development Process

Step-by-step workflow for creating effective Claude Skills.

The Eight Steps

0. Evaluate First

"Create evaluations BEFORE writing extensive documentation."

Define 2-3 concrete use cases and success criteria before writing anything:

• What specific tasks should the skill enable?
• What does success look like? (triggers correctly, completes workflow, 0 errors)
• What does failure look like? (doesn't trigger, wrong output, user corrections needed)

This ensures the skill solves real problems rather than documenting imagined ones.

1. Recognize

Notice when you're repeatedly providing the same context or domain knowledge:

• Explaining the same database schema multiple times
• Providing API integration details in every conversation
• Sharing framework-specific conventions repeatedly
• Teaching the same domain concepts

Signal: "I've explained this 3+ times in different conversations"

2. Gather

Collect 3-5 concrete examples of how you've used this knowledge:

• Save conversation snippets showing the repeated context
• Document the specific questions or tasks that triggered the need
• Note the exact information you provided each time
• Identify common patterns across usage

Output: A collection of real usage examples

3. Plan

Decide information hierarchy:

SKILL.md (Level 2) - Core patterns only:

• What the skill does
• When to use it
• Essential structure/commands
• Links to references

references/ (Level 3) - Detailed docs:

• Complete API documentation
• Detailed examples and tutorials
• Background and theory
• Edge cases and troubleshooting

scripts/ (Level 3) - Deterministic operations:

• Validation logic
• Code generation
• File transformations
• Data processing

assets/ (Level 3) - Static resources:

• Templates
• Configuration files
• Images and diagrams

4. Structure

Create the directory structure:

mkdir -p .claude/skills/my-skill/{references,scripts,assets}
touch .claude/skills/my-skill/SKILL.md

5. Write

Write Description First

The description is critical for skill discovery. Format:

[Domain/Context] [operations/capabilities]. Use when [trigger scenarios].

Examples:

• "PostgreSQL schema and query patterns. Use when designing databases, writing queries, or optimizing performance."
• "Next.js 14 App Router conventions. Use when building Next.js apps, configuring routes, or implementing server components."
• "A skill for databases" (too vague)
• "This skill helps you work with PostgreSQL databases" (second person)

Target: 100-300 chars, max 1024 chars.

Naming: Use gerund form (processing-pdfs, managing-databases). Kebab-case only. Cannot contain "anthropic" or "claude".

Write SKILL.md Body

Structure:

1. Brief intro (1-2 lines) - What this skill provides 2. When to use (3-5 bullets) - Triggering scenarios 3. Core patterns (3-5 sections) - Essential knowledge 4. Links to references - Point to detailed docs

Guidelines:

• Use imperative voice ("Use X for Y", not "You should use X")
• Write descriptions in third person
• Provide concrete examples, not abstract concepts
• Keep it scannable with clear headings
• Target <50 lines (strict) or <500 lines (Anthropic max)
• Link liberally to references/

Write References

No size limits - be as detailed as needed:

• Use descriptive filenames (api-endpoints.md, not reference.md)
• Structure with clear headings
• Include code examples
• Cover edge cases
• Provide context and rationale
• For files over 100 lines, include a table of contents at top
• Keep references one level deep from SKILL.md (avoid nesting)
• Do NOT include README.md in the skill folder

6. Enhance

Add progressive enhancements:

Scripts - When operations are:

• Deterministic (same input = same output)
• Complex (would require Claude to generate code)
• Reusable (used frequently)

Examples: validators, code generators, formatters

Assets - When you need:

• Templates (boilerplate code, config files)
• Static files (images, data files)
• Resources that shouldn't be loaded into context

7. Iterate

Test and refine:

Testing:

• Start a new conversation
• Trigger the skill naturally (don't force it)
• Observe if Claude loads it appropriately
• Check if the content is helpful and sufficient

Refining:

• If skill loads too often → Make description more specific
• If skill never loads → Add trigger keywords to description
• If Claude asks for info that's in references → Add links in SKILL.md
• If SKILL.md feels bloated → Move content to references
• If you're repeating the same complex operation → Create a script

Iteration Cycle:

1. Use skill in real conversations 2. Note friction points and gaps 3. Refactor structure and content 4. Test again

Common Pitfalls

Starting Too Big

• Writing 500 lines before testing
• Start with 30-line SKILL.md, iterate

Generic Descriptions

• "Helps with coding tasks"
• "React hooks patterns and performance optimization. Use when building React components or debugging re-renders."

Bloated SKILL.md

• Including complete API docs in SKILL.md
• Core patterns in SKILL.md, full docs in references/

Missing Triggers

• Description with no "Use when..." clause
• Clear triggering scenarios in description

Second Person Voice

• "You should use this pattern when you need..."
• "Use this pattern when..."

Success Criteria

A well-designed skill:

• Loads automatically when relevant (no manual triggering)
• Provides exactly the context needed (not too much, not too little)
• Improves with each conversation (you notice missing pieces)
• Saves you time (no more re-explaining the same concepts)

Testing Checklist

Before considering a skill complete, run through these checks:

Structural

• [ ] npx claude-skills-cli validate --strict passes
• [ ] All reference links resolve to existing files
• [ ] Scripts have correct permissions and shebang lines
• [ ] No TODO placeholders remain

Behavioral

• [ ] Skill triggers from natural language (don't name the skill directly)
• [ ] Skill does NOT trigger for unrelated requests
• [ ] Claude follows instructions from SKILL.md
• [ ] Claude reads reference files when needed
• [ ] Scripts produce expected output

Content Quality

• [ ] Description in third person with keywords and "Use when..." trigger
• [ ] Name is kebab-case, no reserved words, no XML tags
• [ ] Imperative voice throughout
• [ ] Real examples, not generic placeholders
• [ ] SKILL.md body under 50 lines (strict) or 500 lines (loose)
• [ ] No README.md in skill folder
• [ ] References one level deep, long refs have TOC

For a more detailed testing methodology, see testing-guide.md. For common issues during development, see troubleshooting.md.

Tips

• Start minimal: Better to add than to remove
• Test early: Don't perfect in isolation
• Use real examples: Concrete beats abstract
• Trust progressive disclosure: Claude will ask for references when needed
• Iterate based on usage: Let real conversations drive refinement

Distribution

Sharing and distributing Claude Skills across platforms and teams.

Packaging

Using claude-skills-cli

Package a skill into a distributable zip:

# Validate and package
npx claude-skills-cli package .claude/skills/my-skill

# Custom output directory
npx claude-skills-cli package .claude/skills/my-skill --output builds/

# Skip validation (not recommended)
npx claude-skills-cli package .claude/skills/my-skill --skip-validation

The output is a zip file ready for upload or sharing.

See cli-reference.md for full packaging options.

Manual Packaging

cd .claude/skills/my-skill
zip -r ../../../my-skill.zip .

Ensure the zip root contains SKILL.md directly (not nested in a subdirectory).

Distribution Channels

Claude Code (Filesystem)

Skills live as directories. Share via:

Git repository (recommended):

• Commit skills to .claude/skills/ in the project repo
• Team members get skills automatically on clone/pull
• Version controlled with the rest of the project

Plugin distribution:

• Package skills as part of a Claude Code plugin
• Install via the plugin system or npx mcpick plugins install <plugin>
• Manage with npx mcpick plugins list|enable|disable|update
• Skills go in plugins/<plugin>/skills/<skill-name>/

Manual copy:

• Copy the skill directory to ~/.claude/skills/ (user-level) or .claude/skills/ (project-level)

Claude.ai (Web)

Upload packaged zip files:

1. Go to Settings > Features > Skills 2. Upload the zip file 3. Skill is available for your account only (not org-wide)

Claude API

Upload via the skills API:

1. Package the skill as a zip 2. Upload via POST /v1/skills endpoint 3. Skill is available workspace-wide

Important: Skills do not sync across platforms. Upload separately for each target.

Plugin Packaging

To distribute skills as part of a Claude Code plugin:

Directory Structure

my-plugin/
├── plugin.json          # Plugin manifest
├── skills/
│   ├── skill-one/
│   │   ├── SKILL.md
│   │   └── references/
│   └── skill-two/
│       ├── SKILL.md
│       ├── references/
│       └── scripts/
└── README.md

Plugin Manifest

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin with custom skills"
}

Skills inside a plugin are automatically discovered by Claude Code when the plugin is installed.

Versioning

Semantic Versioning for Skills

Follow semver principles:

• Patch (1.0.x): Fix typos, clarify instructions, fix broken links
• Minor (1.x.0): Add new reference files, new patterns, new scripts
• Major (x.0.0): Change core instructions, rename skill, restructure fundamentally

Version Tracking

Track versions in git commits or a changelog. Skills don't have a built-in version field, so use external version tracking:

# Tag releases
git tag -a skill-myskill-v1.0.0 -m "Initial release of my-skill"

Backwards Compatibility

When updating a shared skill:

• Do not remove patterns that others depend on without notice
• Add new patterns alongside existing ones
• Use reference files for new content to minimize SKILL.md changes
• Test after updates to verify trigger behavior is preserved

Plugin Management with mcpick

mcpick provides CLI management for MCP servers and plugins:

# Install and manage plugins
npx mcpick plugins install <plugin>
npx mcpick plugins update <plugin>
npx mcpick plugins list

# Cache management (fix stale plugins after version bumps)
npx mcpick cache status
npx mcpick cache clear
npx mcpick cache clean-orphaned

# Save/load MCP server + plugin profiles
npx mcpick profile save my-setup
npx mcpick profile load my-setup

Pre-Distribution Checklist

• [ ] npx claude-skills-cli validate --strict passes
• [ ] Tested in a fresh conversation
• [ ] All reference links resolve
• [ ] Scripts have correct permissions and shebangs
• [ ] No absolute paths or machine-specific references
• [ ] No secrets, tokens, or credentials in any file
• [ ] Description is clear for someone unfamiliar with the skill
• [ ] README or documentation explains the skill's purpose (for plugin distribution)

MCP Server Integration

Patterns for integrating MCP (Model Context Protocol) servers with skills.

When to Use MCP vs Direct Tools

Use Direct Tools When

• Reading/writing files on the local filesystem
• Running shell commands
• Searching code with grep/glob
• Standard development operations

Use MCP When

• Accessing external services (databases, APIs, SaaS platforms)
• The operation requires a specialized protocol or authentication
• You need structured resource access beyond filesystem reads
• Bridging Claude to tools that don't have native support

MCP in Skills Context

Skills and MCP servers are complementary:

• Skills provide context, instructions, and domain knowledge
• MCP servers provide tool access to external systems
• A skill can instruct Claude on when and how to use MCP tools

Example: Database Skill + MCP

A skill provides query patterns and schema knowledge. An MCP server provides the actual database connection tool.

# In SKILL.md
## Database Queries

Use the `mcp__db__query` tool for all read operations.
Use the `mcp__db__execute` tool for write operations.

Always use parameterized queries:
- Read: `mcp__db__query` with `sql` and `params` parameters
- Write: `mcp__db__execute` with `sql` and `params` parameters

Example: External API Skill + MCP

# In SKILL.md
## Fetching Data

Use `mcp__api__request` for all external API calls.
Include the authorization header from the environment config.

MCP Tool Naming

Always use fully qualified tool names to avoid "tool not found" errors, especially when multiple MCP servers are available.

Cross-platform format: ServerName:tool_name

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

Claude Code format: mcp__server__tool_name

Use `mcp__db__query` for read operations.

Both formats work in Claude Code. Use the format that matches your target platform.

Patterns

Pattern 1: Skill as MCP Tool Guide

The skill documents which MCP tools to use, when, and with what parameters. The skill content acts as a usage manual for available MCP tools.

## Available Tools

- `mcp__service__list_items` - Fetch items with optional filters
- `mcp__service__create_item` - Create new item (requires `name`, `type`)
- `mcp__service__delete_item` - Delete by ID (irreversible)

## Workflows

### Adding a new item
1. Check for duplicates with `mcp__service__list_items`
2. Create with `mcp__service__create_item`
3. Verify with `mcp__service__list_items`

Pattern 2: Skill Scripts That Call MCP Indirectly

Scripts in a skill cannot call MCP tools directly. Instead, scripts handle data preparation, and the skill instructs Claude to pass script output to MCP tools.

## Data Import Workflow

1. Run `node scripts/transform-csv.js input.csv` to normalize data
2. Pass each row from the output to `mcp__db__execute` for insertion

Pattern 3: Resource-Aware Skills

If an MCP server exposes resources (read-only data), a skill can reference them:

## Configuration

Read the current config from `mcp__config__read_resource` before making changes.
Compare against the schema in [references/config-schema.md](references/config-schema.md).

Limitations

• Skills cannot directly invoke MCP tools — only Claude can
• MCP servers must be configured separately from skills (in Claude settings or project config)
• Skills should document MCP tool names but cannot guarantee they are available
• Add a fallback note: "If mcp__X__Y is not available, use [alternative approach]"

Checklist

• [ ] Skill documents which MCP tools to use and when
• [ ] Parameter requirements are specified for each MCP tool reference
• [ ] Fallback approaches documented for when MCP tools are unavailable
• [ ] Scripts handle data prep, Claude handles MCP tool invocation
• [ ] MCP tool names match the actual configured server naming

Quick Start Guide

Creating Your First Skill

1. Create the skill directory

   mkdir -p .claude/skills/my-skill

2. Create SKILL.md with frontmatter

   ---
   name: my-skill
   description: Brief description of what this skill does
   ---

   # My Skill

   Core instructions go here...

3. Test in conversation

• Invoke the skill using the Skill tool
• Verify it loads and provides correct guidance

4. Iterate and expand

• Add references/ directory for detailed documentation
• Add scripts/ for executable operations
• Add assets/ for templates and files

Skill Structure Details

Directory Layout

my-skill/
├── SKILL.md          # Core instructions + YAML frontmatter
├── references/       # Detailed documentation (loaded as needed)
│   ├── guide.md
│   └── examples.md
├── scripts/          # Executable shell scripts or programs
│   └── setup.sh
└── assets/           # Templates, images, configuration files
    └── template.yaml

SKILL.md Anatomy

---
name: skill-name # Unique identifier (kebab-case, max 64 chars)
description: What it does and when to use it. Use when [triggers].
---

# Skill Title

Brief overview of what this skill does.

## Section 1

Core patterns and instructions...

## Section 2

More essential guidance...

Frontmatter Requirements

name field

• Max 64 characters
• Lowercase letters, numbers, and hyphens only
• Cannot contain "anthropic" or "claude" (reserved words)
• Cannot contain XML tags (< or >)
• Prefer gerund form: processing-pdfs, analyzing-data, managing-databases
• Acceptable alternatives: pdf-processing, process-pdfs
• Avoid generic names: helper, utils, tools, data

description field

• Max 1024 characters, min ~50 characters
• Cannot contain XML tags
• Write in third person (description is injected into system prompt)
• Include both what the skill does AND when to use it
• Include searchable keywords and trigger phrases

No README.md

Do not include a README.md inside the skill folder. All documentation goes in SKILL.md or references/.

Progressive Disclosure Strategy

Level 1: Metadata (Always Loaded)

• YAML frontmatter only
• CLI recommended: <200 chars, ~27 tokens (optimal for many skills)
• Anthropic max: 1024 chars, ~100 tokens
• Used for: Skill discovery and triggering

Level 2: Instructions (Loaded When Triggered)

• SKILL.md body content
• CLI recommended: <50 lines, <1000 words (optimal for context efficiency)
• Anthropic max: 500 lines, ~5k tokens
• Use npx claude-skills-cli validate to check (default strict, --loose for official limits)
• Contains: Core patterns, essential rules, reference links

Level 3: Resources (Loaded On Demand)

• references/ scripts/ assets/ directories
• Size: Unlimited
• Contains: Detailed docs, code, templates
• Keep references one level deep from SKILL.md (avoid nesting references that link to other references)
• For reference files over 100 lines, include a table of contents at the top

Tips for Effective Skills

• Start minimal: Begin with just SKILL.md
• Iterate: Add references/ as complexity grows
• Link clearly: Use relative links to reference files
• Test often: Validate with pnpx claude-skills-cli validate
• Stay focused: One skill = one clear purpose
• Evaluate first: Create evaluations BEFORE writing extensive documentation

Skill Examples

Real examples showing effective skill patterns.

Example 1: API Client Skill

Use Case

Repeatedly making authenticated API requests with TypeScript types and error handling.

Structure

api-client/
├── SKILL.md                    # Core request patterns
├── references/
│   ├── endpoints.md            # Complete API endpoint reference
│   ├── authentication.md       # Auth patterns and token management
│   └── error-handling.md       # Error codes and retry strategies
└── scripts/
    ├── validate-token.js       # Check token validity
    └── test-endpoints.js       # Verify endpoint availability

SKILL.md Excerpt

````markdown --- name: api-client description: REST API client with TypeScript types for user and data endpoints. Use when making HTTP requests, handling authentication, managing API errors, or working with async operations. ---

API Client

Quick Start

import { apiClient } from "./lib/api";

// GET single resource with type safety
const user = await apiClient.get(`/users/${id}`);

````

For complete endpoint docs: references/endpoints.md

Why It Works

• Description includes operation keywords for matching
• Quick Start shows most common pattern with types
• Complete API docs in references (not inline)
• Scripts validate connectivity and tokens
• Keyword-rich: "HTTP requests", "authentication", "async operations"

---

Example 2: Database Patterns

Use Case

Type-safe database queries with consistent patterns.

Structure

database-patterns/
├── SKILL.md                    # Core patterns and conventions
├── references/
│   ├── schema.md               # Complete database schema
│   ├── query-patterns.md       # Common query examples
│   └── migrations.md           # Migration conventions
└── scripts/
    └── validate-schema.js      # Check schema consistency

SKILL.md Excerpt

````markdown --- name: database-patterns description: SQLite database operations with better-sqlite3 for contacts, companies, and interactions. Use when writing SELECT, INSERT, UPDATE, DELETE, or designing database schema. ---

Database Patterns

Quick Start

import { db } from "./lib/db";

// Query with type safety
const users = db.prepare("SELECT * FROM users WHERE active = ?").all(1);

````

Why It Works

• Mentions specific technology (SQLite, better-sqlite3)
• Lists specific operations (SELECT, INSERT, UPDATE, DELETE)
• Schema details in references, not SKILL.md
• Script validates consistency

---

Example 3: Component Library

Use Case

Consistent component styling with project conventions.

Structure

component-library/
├── SKILL.md                    # Core components and patterns
├── references/
│   ├── component-catalog.md    # All available components
│   └── theme-tokens.md         # Color system and usage
└── assets/
    └── templates/
        ├── basic-component.svelte
        └── form-component.svelte

SKILL.md Excerpt

````markdown --- name: component-library description: UI component patterns with DaisyUI v5 for cards, forms, buttons, and layouts. Use when styling components, implementing forms, or applying consistent visual design. ---

Component Library

Card Pattern

<div class="card bg-base-100 shadow-xl">
  <div class="card-body">
    <h2 class="card-title">Title</h2>
    <p>Content</p>
  </div>
</div>

````

Why It Works

• Shows actual classes used in project
• Theme tokens documented
• Templates in assets/ for copying
• Keywords: "cards, forms, buttons, layouts"

---

Example 4: Project Context

Use Case

Ensure Claude follows YOUR project's specific patterns, conventions, and architecture decisions consistently across all conversations.

Why You Need This

Without a project-context skill, Claude:

• Mixes patterns (uses writable when you use $state)
• Creates files in wrong locations
• Uses wrong libraries (Prisma when you use Drizzle)
• Ignores your naming conventions

With a project-context skill, Claude automatically follows your rules.

Structure

project-context/
├── SKILL.md                    # Stack + critical rules
└── references/
    ├── architecture.md         # System design details
    ├── conventions.md          # Naming, file structure
    └── patterns.md             # Code patterns with examples

SKILL.md Example (SvelteKit + Drizzle + Better-auth)

---
name: project-context
description: Project patterns for [your-app]. Use before any development work to ensure consistent implementation.
---

# Project Context

## Stack

- **Framework**: SvelteKit 2 with Svelte 5
- **Database**: SQLite + Drizzle ORM
- **Auth**: Better-auth
- **UI**: Tailwind + shadcn-svelte
- **Forms**: Superforms + Zod

## Critical Rules

1. **State**: Use `$state`, `$derived`, `$effect` - never `writable`/`$:`
2. **Routes**: App routes in `src/routes/(app)/` - requires auth
3. **DB queries**: Always through `src/lib/server/db/queries/` - never import drizzle directly in routes
4. **Forms**: Superforms with Zod schemas from `src/lib/schemas/`
5. **Auth**: Use `auth.api` helpers - never modify `src/lib/server/auth.ts` directly

## File Patterns

| Type         | Location                      | Naming               |
| ------------ | ----------------------------- | -------------------- |
| Routes       | `src/routes/(app)/[feature]/` | `+page.svelte`       |
| Components   | `src/lib/components/`         | `PascalCase.svelte`  |
| Server utils | `src/lib/server/`             | `kebab-case.ts`      |
| Schemas      | `src/lib/schemas/`            | `[entity].schema.ts` |

## References

- [architecture.md](references/architecture.md) - System design
- [conventions.md](references/conventions.md) - All naming rules
- [patterns.md](references/patterns.md) - Code examples

Why It Works

• Specific stack - Names exact versions and libraries
• Critical rules first - Most important patterns immediately visible
• Actionable - "never do X" is clearer than "prefer Y"
• File locations - Claude knows where to create things
• Details in references - Keeps SKILL.md scannable

Creating Your Own

1. List your stack (framework, db, auth, ui) 2. Identify top 5 mistakes Claude makes in your project 3. Write rules that prevent those mistakes 4. Add file location patterns 5. Move detailed docs to references/

Key Insight

A project-context skill is NOT a template you distribute - it's unique to YOUR project. Create one in your repo's .claude/skills/ or as a local plugin.

---

Pattern: Description Keywords

Good descriptions include:

• Technology names: "TypeScript", "REST API", "React", "Node.js"
• Operations: "HTTP requests", "OAuth flow", "async/await"
• Data types: "users, posts, comments", "API responses"
• Triggers: "Use when...", "Use for...", "Use to..."

Before (Vague)

description: Helps with API stuff

After (Specific)

description: REST API client with TypeScript types for user and data endpoints. Use when making HTTP requests, handling authentication, managing API errors, or working with async operations.

---

Pattern: Progressive Disclosure

Level 1: Metadata (Always)

name: api-client
description: [keyword-rich, third person, includes "Use when..." triggers]

Token cost: ~100 tokens per skill

Level 2: SKILL.md Body (When Triggered)

• Quick Start example
• 3-5 core patterns
• Links to references (one level deep)
• Script descriptions

Token cost: Under 5k tokens / 500 lines

Level 3: Resources (As Needed)

• references/endpoints.md (complete API docs)
• references/examples.md (20+ examples)
• scripts/validate-token.js (runs without loading)

Token cost: Only what's accessed

---

Pattern: Scripts for Efficiency

Without Script

Claude generates validation code every time:
"Check that all timestamps are valid..."
[Claude writes 50 lines of JavaScript]

Cost: ~500 tokens each time

With Script

node scripts/validate_timestamps.js

Cost: ~50 tokens (just output)

Script Types

• Validation: Check data consistency
• Generation: Create boilerplate
• Analysis: Parse and report
• Testing: Verify configuration

---

Pattern: Assets for Templates

Without Assets

"Create a basic component..."
[Claude writes boilerplate each time]

With Assets

cp assets/templates/basic-component.svelte \
  src/lib/components/new-component.svelte
# Modify as needed

Asset Types

• Component templates (.svelte, .tsx)
• SQL schemas (.sql)
• Configuration files (.json)
• Images and logos (.png, .svg)

---

Anti-Patterns to Avoid

Generic Description

description: Database helper tool

Fix: Include table names, operations, when to use

Everything Inline

# Database Skill

## Complete Schema (1000 lines)

## All Queries (500 lines)

Fix: Move to references/schema.md

Second Person

You should use prepared statements...

Fix: "Use prepared statements for all queries"

Missing Keywords

description: Helps with frontend stuff

Fix: "React components with hooks, TypeScript, forms"

---

Example 5: MCP-Aware Skill

Use Case

Skill that guides Claude on using MCP tools for database operations.

Structure

db-operations/
├── SKILL.md                    # Core patterns + MCP tool usage
├── references/
│   ├── schema.md               # Database schema documentation
│   └── query-patterns.md       # Common query templates
└── scripts/
    └── validate-schema.js      # Schema consistency checker

SKILL.md Excerpt

````markdown --- name: db-operations description: Database operations via MCP tools for users, orders, and products tables. Use when querying databases, writing migrations, or managing schema changes. ---

Database Operations

Quick Start

Execute read queries with the MCP database tool:

Use mcp__db__query with sql: "SELECT * FROM users WHERE active = 1"

For write operations:

Use mcp__db__execute with sql and params for parameterized queries

````

Why It Works

• Documents specific MCP tool names for the domain
• Provides parameter patterns for each tool
• Schema details in references, not inline
• See mcp-integration.md for MCP patterns

---

Quick Checklist

Before considering a skill "done":

• [ ] Description includes keywords and "when to use"
• [ ] Quick Start shows most common pattern
• [ ] Core patterns (3-5) in SKILL.md
• [ ] Detailed docs in references/
• [ ] Scripts for repeated code
• [ ] Assets for templates
• [ ] Validated with npx claude-skills-cli validate
• [ ] Tested in real conversations
• [ ] No TODO placeholders
• [ ] Imperative voice throughout

If something isn't working, see troubleshooting.md for common issues and fixes.

Testing Guide

Structured testing methodology for Claude Skills.

Manual Testing Workflow

Step 1: Structural Validation

Run the CLI validator first to catch structural issues:

npx claude-skills-cli validate .claude/skills/my-skill
npx claude-skills-cli validate .claude/skills/my-skill --strict

Fix all errors before proceeding. See cli-reference.md for validation details.

Step 2: Trigger Testing

Test that the skill activates when expected:

1. Start a fresh conversation (no prior context) 2. Make a request that should trigger the skill — use natural language, do not name the skill directly 3. Verify Claude loads the skill (check if the skill's instructions are being followed) 4. Make a request that should NOT trigger the skill — verify it stays inactive

Common trigger issues:

• Skill triggers too broadly → Make description more specific
• Skill never triggers → Add keyword-rich trigger phrases ("Use when...")
• Skill triggers for wrong tasks → Narrow the domain terms in description

Step 3: Instruction Following

Once triggered, verify Claude follows the skill's instructions:

1. Ask Claude to perform a core task the skill covers 2. Check the output against skill instructions — are patterns followed? 3. Ask for a task that requires reference files — does Claude read them? 4. Run any scripts the skill includes — do outputs match expectations?

Step 4: Edge Case Testing

Test boundary conditions:

• What happens with minimal input?
• What happens with conflicting instructions (skill says X, user says Y)?
• Does the skill handle missing context gracefully?
• Do reference links resolve correctly?

Validation Checklist

Metadata (Level 1)

• [ ] name is lowercase kebab-case, under 64 characters
• [ ] name matches the directory name
• [ ] description is under 1024 characters
• [ ] description includes "Use when..." trigger phrase
• [ ] description contains domain-specific keywords
• [ ] No unsupported frontmatter fields (only name and description are valid)

Instructions (Level 2)

• [ ] SKILL.md body under 5k words
• [ ] Imperative voice throughout (no "you should")
• [ ] Quick Start section with a working example
• [ ] 3-5 core patterns documented
• [ ] Links to references/ for detailed content
• [ ] No TODO placeholders
• [ ] No stale or incorrect examples

Resources (Level 3)

• [ ] All referenced files exist (no broken links)
• [ ] Scripts are executable (chmod +x)
• [ ] Scripts have shebang lines (#!/bin/bash or #!/usr/bin/env node)
• [ ] No empty directories
• [ ] Reference files have clear headings and structure

Integration

• [ ] Skill triggers from natural language requests
• [ ] Skill does NOT trigger for unrelated requests
• [ ] Claude follows skill instructions correctly
• [ ] Scripts produce expected output
• [ ] Reference files are accessed when needed

Testing Script Template

Create a simple test script to validate skill structure programmatically:

#!/bin/bash
# scripts/test-skill.sh
SKILL_DIR="${1:-.claude/skills/my-skill}"

echo "Testing skill at: $SKILL_DIR"

# Check SKILL.md exists
if [ ! -f "$SKILL_DIR/SKILL.md" ]; then
  echo "FAIL: SKILL.md not found"
  exit 1
fi

# Check frontmatter
if ! head -1 "$SKILL_DIR/SKILL.md" | grep -q "^---"; then
  echo "FAIL: Missing YAML frontmatter"
  exit 1
fi

# Check for broken reference links
grep -oP '\[.*?\]\((references/[^)]+)\)' "$SKILL_DIR/SKILL.md" | \
  grep -oP 'references/[^)]+' | while read -r ref; do
    if [ ! -f "$SKILL_DIR/$ref" ]; then
      echo "FAIL: Broken link to $ref"
      exit 1
    fi
  done

echo "PASS: Basic structure checks passed"

Iteration After Testing

When tests reveal issues, apply these fixes:

See development-process.md for the full iteration workflow. See troubleshooting.md for common issues and fixes.

Troubleshooting

Common skill development issues and fixes.

Skill Not Triggering

Symptom: Claude does not activate the skill when expected.

Causes and fixes:

Test: Start a fresh conversation and make a natural request related to the skill domain.

Skill Triggers Too Often

Symptom: Skill activates for unrelated tasks.

Causes and fixes:

Test: Make requests outside the skill's domain and verify the skill stays inactive.

Claude Ignores Skill Instructions

Symptom: Skill loads but Claude doesn't follow the documented patterns.

Causes and fixes:

Claude Doesn't Read References

Symptom: Claude answers from general knowledge instead of reading reference files.

Causes and fixes:

Frontmatter Issues

Invalid Frontmatter

Symptom: CLI validation fails on frontmatter.

Fixes:

• Ensure SKILL.md starts with --- on line 1
• Only use name and description fields — no other fields are supported
• name must be lowercase kebab-case, under 64 characters
• description must be under 1024 characters

Known discrepancy: Some Anthropic documentation references an allowed-tools frontmatter field. This field is not supported in Claude Code. Do not use it.

Multi-Line Description

Symptom: Skill not recognized after running Prettier or other formatters.

Fix:

npx claude-skills-cli doctor .claude/skills/my-skill

This adds # prettier-ignore and reflows the description to a single line.

Script Issues

Script Won't Execute

Causes and fixes:

Script Output Too Large

Symptom: Script runs but floods the context window.

Fix: Modify script to output a summary instead of raw data. Filter or truncate output within the script.

Validation Errors

"Description missing trigger keywords"

Add a "Use when..." phrase to the description:

# Before
description: Database query patterns

# After
description: Database query patterns for SQLite. Use when writing queries, designing schema, or optimizing database operations.

"SKILL.md body too long"

Move content to reference files:

1. Identify sections that are detailed documentation (not core patterns) 2. Move them to references/<topic>.md 3. Replace with a link: See [references/<topic>.md](references/<topic>.md)

"Broken reference link"

A link in SKILL.md points to a file that doesn't exist:

1. Check the path is correct (relative to SKILL.md location) 2. Create the missing file, or remove/update the link

"Name doesn't match directory"

The name field in frontmatter must match the skill's directory name:

# Directory: .claude/skills/my-skill/
# Frontmatter must be:
name: my-skill

Platform-Specific Issues

Claude Code

• Skills must be in .claude/skills/ (project) or ~/.claude/skills/ (user) or in a plugin's skills/ directory
• File permissions matter — ensure files are readable
• Symlinks may not be followed in all cases

Claude.ai

• Upload as zip with SKILL.md at the zip root
• Maximum upload size limits may apply
• Skills are per-user, not org-wide

Claude API

• Upload via /v1/skills endpoint
• Skills are workspace-scoped
• Check API documentation for current size limits

Getting Help

If issues persist:

1. Run npx claude-skills-cli validate --strict and fix all reported issues 2. Review development-process.md for the recommended workflow 3. Check testing-guide.md for systematic testing steps 4. Compare against working examples in skill-examples.md

Skill Writing Guide

Detailed guidelines for writing effective Claude skills.

Voice and Tone

Use Imperative Voice

Claude responds best to direct instructions.

Good Examples

Use prepared statements for all database queries. Generate IDs with
nanoid() before inserting records. Store timestamps as Unix epoch
milliseconds. Validate input before saving to database.

Bad Examples

You should use prepared statements for database queries. You'll want
to generate IDs with nanoid(). It's best if you store timestamps as
Unix epoch. Try to validate input before saving.

Be Specific, Not Vague

Provide concrete instructions, not general advice.

Good Examples

// Use nanoid() for ID generation
import { nanoid } from "nanoid";
const id = nanoid();

// Store timestamps as ISO strings
const timestamp = new Date().toISOString();

// Use type-safe interfaces
interface User {
  id: string;
  name: string;
  email: string;
}

Bad Examples

// Use an appropriate ID generator
const id = generateId();

// Store timestamps in a suitable format
const created_at = getCurrentTime();

// Use appropriate types
const user: any;

Avoid Conceptual Explanations

Focus on procedural steps, not theory.

Good (Procedural)

To fetch user data:

1. Import the API client
2. Call the endpoint with typed parameters
3. Handle the response with type checking
4. Return the typed result

Bad (Conceptual)

When thinking about API design, consider REST principles and how
architectural patterns affect your implementation...

---

Description Writing

The description determines when Claude triggers your skill. Make it count.

Write in third person. The description is injected into the system prompt; inconsistent point-of-view causes discovery problems.

Description Formula

[Technology] + [Operations] + [Data Types] + [Trigger Phrase]

Examples

API Client Skill

description: REST API client for user data endpoints with TypeScript types. Use
  when making HTTP requests, handling authentication, or working with
  API responses and error handling.

Breakdown:

• Technology: "REST API", "TypeScript"
• Operations: "HTTP requests", "authentication", "error handling"
• Data types: "user data endpoints", "API responses"
• Trigger: "Use when making...or working with"

Component Skill

description: Create type-safe React components with hooks and TypeScript
  interfaces. Use when building UI components, implementing forms, or
  managing component state and props.

Description Checklist

• [ ] Written in third person
• [ ] Includes technology names
• [ ] Lists specific operations
• [ ] Mentions data types or domains
• [ ] Has "Use when..." trigger phrase
• [ ] Contains searchable keywords
• [ ] Under 1024 characters
• [ ] Over 50 characters (not too short)

---

Degrees of Freedom

Match instruction specificity to the task's fragility and variability.

High Freedom (text-based instructions)

Use when output varies by context and Claude's judgment adds value.

## Code review process
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

Medium Freedom (pseudocode or scripts with parameters)

Use when the process is consistent but details vary.

def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations

Low Freedom (specific scripts, no modification)

Use when exact execution matters (migrations, deployments, compliance).

## Database migration
Run exactly this script:
\`\`\`bash
python scripts/migrate.py --verify --backup
\`\`\`
Do not modify the command or add additional flags.

---

Structure Patterns

Quick Start Section

Show the most common operation immediately.

````markdown

Quick Start

import { apiClient } from "./lib/api";

const response = await apiClient.get("/users");
const users = response.data;

````

Guidelines:

• Minimal working example
• Most common use case
• Copy-paste ready
• Includes imports
• Shows types

Core Patterns Section

Provide 3-5 essential patterns.

````markdown

Core Patterns

GET Requests

// Single resource
const user = await apiClient.get(`/users/${id}`);

// Collection
const users = await apiClient.get("/users");

POST Requests

const newUser = await apiClient.post("/users", {
  id: nanoid(),
  name: "John Doe",
  email: "john@example.com",
  createdAt: new Date().toISOString(),
});

````

Guidelines:

• One pattern per subsection
• Include code examples
• Show variations
• Real project code
• Not invented examples

Advanced Usage Section

Link to detailed references.

## Advanced Usage

For detailed information:

- [references/api-docs.md](references/api-docs.md) - Complete API reference
- [references/authentication.md](references/authentication.md) - Auth patterns
- [references/examples.md](references/examples.md) - 20+ usage examples

Guidelines:

• Brief descriptions of each reference
• Descriptive link text
• Organized by topic
• Not "click here"

---

Code Examples

Use Real Code

Pull examples from actual codebase, not invented scenarios.

Good (Real)

// From src/lib/api/users.ts
const response = await fetch(`${API_BASE}/users/${userId}/stats`, {
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
});

const stats = (await response.json()) as UserStats;

Bad (Generic)

// Generic example
const result = await api.getData();

Include Context

Show imports, types, and surrounding context.

// Complete context
import { nanoid } from "nanoid";
import type { User, CreateUserRequest } from "./types";
import { apiClient } from "./client";

const createUser = async (request: CreateUserRequest): Promise<User> => {
  const user: User = {
    id: nanoid(),
    ...request,
    createdAt: new Date().toISOString(),
  };

  const response = await apiClient.post("/users", user);
  return response.data;
};

Comment Strategically

Explain WHY, not WHAT.

// Good comments (explain why)
// Use Authorization header to verify JWT token
const headers = { Authorization: `Bearer ${token}` };

// Always validate input to prevent injection attacks
const sanitized = validator.escape(userInput);

// Bad comments (state the obvious)
// This creates headers
const headers = { Authorization: `Bearer ${token}` };

// This makes a request
const response = await fetch(url);

---

Size Guidelines

SKILL.md Body

• CLI recommended: <50 lines, <1000 words (optimal when many skills loaded)
• Anthropic official max: 500 lines, ~5k tokens
• Validate: npx claude-skills-cli validate (default strict) or --loose (official limits)
• If exceeding: Move content to references/

Reference Files

• Target: 1k-10k words per file
• Maximum: 15k words per file
• If exceeding: Split into multiple focused files
• Over 100 lines: Include a table of contents at top
• Nesting: Keep references one level deep from SKILL.md

Description

• Minimum: 50 characters
• Target: 100-300 characters
• Maximum: 1024 characters

---

Common Mistakes

Mistake 1: Vague Descriptions

# Bad
description: Helper for API stuff

# Good
description: REST API client with TypeScript types for user endpoints. Use when making HTTP requests, handling auth, or managing API errors.

Mistake 2: Second Person

# Bad

You should always validate input before saving.

# Good

Validate input before saving to database.

Mistake 3: Conceptual Over Procedural

````markdown

Bad

Understanding the importance of authentication tokens in the context of secure API communication is crucial for security...

Good

Include authentication tokens in all API requests:

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${token}` },
});

````

Mistake 4: Duplicate Content

# Bad (repeated in multiple places)

SKILL.md has complete schema
references/schema.md has complete schema

# Good (single source of truth)

SKILL.md has quick reference
references/schema.md has complete schema

---

Anti-Patterns

Avoid Deeply Nested References

Claude may partially read files referenced from other referenced files, using head -100 to preview rather than reading completely.

# Bad: Too deep
SKILL.md → advanced.md → details.md → actual info

# Good: One level deep
SKILL.md → advanced.md (complete info)
SKILL.md → reference.md (complete info)

Avoid Offering Too Many Options

Provide a default with an escape hatch, not a menu of choices.

# Bad
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image..."

# Good
Use pdfplumber for text extraction.
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.

Avoid Time-Sensitive Information

# Bad
If you're doing this before August 2025, use the old API.

# Good
## Current method
Use the v2 API endpoint.

## Old patterns
<details>
<summary>Legacy v1 API (deprecated)</summary>
The v1 endpoint is no longer supported.
</details>

Avoid Windows-Style Paths

Always use forward slashes, even on Windows:

scripts/helper.py     ✅
scripts\helper.py     ❌

---

Workflow Patterns

Checklist Pattern

For complex multi-step tasks, provide a checklist Claude can copy and track:

````markdown

Form filling workflow

Copy this checklist and check off items as you complete them:

Task Progress:
- [ ] Step 1: Analyze the form
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output

````

Feedback Loop Pattern

Run validator → fix errors → repeat. Greatly improves output quality:

## Document editing process
1. Make edits
2. Validate: `python scripts/validate.py`
3. If validation fails: fix issues, run validation again
4. Only proceed when validation passes
5. Rebuild output

Plan-Validate-Execute Pattern

For complex open-ended tasks, have Claude create a plan file, validate it, then execute:

## Batch update workflow
1. Analyze inputs → create `changes.json`
2. Validate plan: `python scripts/validate_changes.py changes.json`
3. If valid → execute changes
4. Verify output

Conditional Workflow Pattern

Guide Claude through decision points:

## Document modification
1. Determine modification type:
   **Creating new content?** → Follow "Creation workflow"
   **Editing existing?** → Follow "Editing workflow"

---

Checklist

Before finalizing a skill:

Content

• [ ] Description in third person
• [ ] Description includes keywords and triggers
• [ ] Imperative voice throughout
• [ ] Specific, not vague
• [ ] Real examples from codebase
• [ ] No TODO placeholders

Structure

• [ ] Quick Start section present
• [ ] 3-5 Core Patterns documented
• [ ] Links to references working
• [ ] Scripts described
• [ ] SKILL.md body under 50 lines (strict) or 500 lines (loose)
• [ ] References one level deep (no nested chains)
• [ ] Long reference files have table of contents

Technical

• [ ] npx claude-skills-cli validate passes
• [ ] YAML frontmatter valid
• [ ] Name is kebab-case, no "anthropic"/"claude", no XML tags
• [ ] Name matches directory
• [ ] No README.md in skill folder
• [ ] Scripts are executable
• [ ] References mentioned in SKILL.md

Testing

• [ ] Tested in real conversations
• [ ] Claude triggers skill correctly
• [ ] Instructions are clear
• [ ] Examples work as shown