name: claude-skill-creator description: Author high-quality Claude Code skills with proper frontmatter, trigger-optimized descriptions, progressive disclosure structure, and MCP tool integration. Includes file organization patterns, testing approaches, and performance tuning. Consult when building new skills, debugging activation issues, or refactoring existing skill content.

Claude Skill Creator

Comprehensive guide for authoring high-quality Claude skills.

CRITICAL RULES - READ BEFORE CREATING ANY SKILL

These rules are NON-NEGOTIABLE. Violating them wastes tokens and breaks skills.

Rule 1: START SMALL

Maximum files for new skill: 3 (SKILL.md + 2 supporting)
Only add more files after the skill works

Rule 2: NO PLACEHOLDERS

NEVER create empty files
NEVER reference files you haven't written
If you write See [guide.md], then guide.md MUST exist with content

Rule 3: COMPLETE BEFORE LINKING

Write the referenced file BEFORE adding the link to SKILL.md
Test that each referenced file exists and has content

Rule 4: FILE COUNT LIMITS

Complexity	Max Files	When to Use
Simple	1-3	Most skills
Moderate	4-6	Multi-domain skills
Complex	7-10	Rare, justify each file
15+ files	NEVER	You are over-engineering

Before Creating ANY File, Ask:

Can this fit in SKILL.md? - Do that
Will I complete this file RIGHT NOW? - If no, don't create it
Am I anticipating future needs? - Stop. Solve current problem only.

Detailed anti-pattern examples: See references/anti-patterns.md

Latest Official Documentation

Before creating skills, fetch current Anthropic specifications:

Primary: Context7

Resolve: mcp__context7__resolve-library-id with "claude code skills"
Fetch: mcp__context7__get-library-docs with ID /websites/code_claude_en topic "skills"

Fallback: WebFetch

WebFetch url="https://code.claude.com/docs/en/skills"
prompt="Extract skill file structure, frontmatter requirements, and best practices"

Complete retrieval guide: See references/doc-retrieval.md

Core Principles

The Context Window is a Public Good

Your skill shares context with system prompt, conversation history, other skills, and user requests.

Loading Model:

Level 1 (Always): name + description (~100 tokens per skill)
Level 2 (When triggered): SKILL.md body (<5k tokens)
Level 3+ (As needed): Referenced files (effectively unlimited)

Best Practice: Keep SKILL.md under 500 lines.

Frontmatter Structure

---
name: skill-name
description: What it does. Use when [triggers].
allowed-tools: Read, Grep, Glob  # Optional: restrict tool access
---

Requirements

Field	Limit	Notes
`name`	64 chars	Lowercase, hyphens only. No "anthropic"/"claude"
`description`	1024 chars	Third person. Include WHAT + WHEN
`allowed-tools`	Optional	Comma-separated tool list

Naming Convention (Gerund Form)

Use verb + -ing:

processing-pdfs not pdf-processor
analyzing-spreadsheets not spreadsheet-analyzer
generating-commits not commit-generator

Description Formula

[What the skill does]. Use when [trigger conditions].

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents or form automation.

Bad:

description: Helps with documents and files when needed.

File Organization

Directory Patterns

Simple (1 file):

my-skill/
└── SKILL.md

With References (3-4 files):

my-skill/
├── SKILL.md
├── reference.md
└── examples.md

With Scripts (5-7 files):

pdf-skill/
├── SKILL.md
├── FORMS.md
└── scripts/
    ├── analyze_form.py
    └── fill_form.py

Complete guide: See references/file-organization.md

What NOT to Include

README.md (skill IS the documentation)
INSTALLATION_GUIDE.md
CHANGELOG.md
Test files
License files (belongs in plugin)

Progressive Disclosure

Claude navigates skills like a filesystem, reading files only when needed.

Keep references one level deep from SKILL.md:

SKILL.md
├── references to → advanced.md     ✓
├── references to → reference.md    ✓
└── references to → examples.md     ✓

Avoid nested references:

SKILL.md → advanced.md → details.md → more.md    ✗

For files >100 lines: Include a table of contents.

Complete patterns: See references/progressive-disclosure.md

MCP Tool References

Always use fully qualified tool names: ServerName:tool_name

Use `Salesforce:query` for SOQL queries.
Use `BigQuery:bigquery_schema` for table schemas.
Use `mcp__context7__get-library-docs` for documentation.

Why: Tool names conflict across servers. Qualified names ensure correct invocation.

Complete guide: See references/mcp-tools.md

6-Step Creation Process

Step 1: Understand

Gather concrete usage examples. Ask: "What would trigger this skill?"

Step 2: Plan

Identify resources needed. STOP AND CHECK: Can this be 1-3 files?

Step 3: Initialize

Run python scripts/init_skill.py <skill-name> --path <output-dir>

Step 4: Edit

Implement SKILL.md and referenced files. Every file you reference must exist.

Step 5: Package

Run python scripts/package_skill.py <skill-dir> to validate and package.

Step 6: Iterate

Test with realistic scenarios. Refine based on Claude's navigation patterns.

Testing

Use the three-agent pattern:

Claude A (Author): Describes desired behavior
Claude B (Tester): Uses skill in realistic scenarios
You (Observer): Watch navigation, refine based on observations

Watch for:

Unexpected file access order
Missed references
Ignored files (may be unnecessary)

Complete guide: See references/testing.md

Troubleshooting

Skill Doesn't Load

Check YAML frontmatter syntax (opening/closing ---)
Verify file location: .claude/skills/<name>/SKILL.md
Check description specificity - is it triggering?

Broken References

Verify all referenced files exist
Check paths use forward slashes (/)
Ensure no placeholder files

Multiple Skills Conflict

Make descriptions more specific
Use "Use when [specific scenario]" phrases
Consider merging related skills

Security

Only use skills from trusted sources:

Skills you created
Skills from Anthropic
Verified, audited skills

Skills can direct Claude to invoke tools in unintended ways. Audit untrusted skills thoroughly.

Quick Reference

Checklist

SKILL.md under 500 lines
Name ≤64 chars, description ≤1024 chars
Description includes "what" AND "when"
All referenced files exist with content
No empty placeholder files
File count within limits (3 for simple, 6 for moderate)
MCP tools use fully qualified names
Tested with realistic scenarios

Do's

Start with 1-3 files
Write third-person descriptions
Use gerund naming (processing-pdfs)
Complete files before referencing

Don'ts

Create 15+ file structures
Reference files you haven't written
Use generic descriptions
Nest references more than one level

Examples

Complete working examples:

examples/simple-skill.md - Single-file skill
examples/multi-file-skill.md - Multi-file with references
examples/code-skill.md - Skill with scripts

Claude CLI Plugin Commands

The Claude CLI has direct plugin management commands (not just interactive /plugin):

claude plugin marketplace add <source>    # Add marketplace from URL, path, or GitHub repo
claude plugin marketplace list            # List configured marketplaces
claude plugin marketplace remove <name>   # Remove a marketplace
claude plugin marketplace update [name]   # Update marketplace(s)
claude plugin validate <path>             # Validate plugin/marketplace manifest
claude plugin install <plugin>            # Install plugin from marketplace

Supported marketplace sources:

Local paths: /path/to/marketplace or ./relative/path
GitHub repos: owner/repo (shorthand)
Git URLs: https://github.com/owner/repo.git
Direct marketplace.json URLs

Not supported: Azure DevOps URLs (use local clone instead)

Additional Resources

Quick Reference: See QUICK-REFERENCE.md
Official Docs: https://code.claude.com/docs/en/skills
Plugin Integration: https://code.claude.com/docs/en/plugins-reference

Name	claude-skill-creator
Description	Author high-quality Claude Code skills with proper frontmatter, trigger-optimized descriptions, progressive disclosure structure, and MCP tool integration. Includes file organization patterns, testing approaches, and performance tuning. Consult when building new skills, debugging activation issues, or refactoring existing skill content.