Claude Skill Creator

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

Before Creating ANY File, Ask:

1. Can this fit in SKILL.md? - Do that
2. Will I complete this file RIGHT NOW? - If no, don't create it
3. 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

1. Resolve: mcp__context7__resolve-library-id with "claude code skills"
2. 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

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:

1. Claude A (Author): Describes desired behavior
2. Claude B (Tester): Uses skill in realistic scenarios
3. 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

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

Broken References

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

Multiple Skills Conflict

1. Make descriptions more specific
2. Use "Use when [specific scenario]" phrases
3. 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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.