How to create high-quality SKILL.md files

• Quick Start
• Core Principles
• File Structure Standards
• Naming and Description Standards
• Content Writing Guide
• Quality Checklist

• User asks to [specific scenario]
• User mentions "[keyword]"

1. Step 1: [Action]
2. Step 2: [Action]

• ✅ Project-specific workflows
• ✅ Special naming conventions or format requirements
• ✅ How to use custom tools and scripts
• ❌ General programming knowledge
• ❌ Obvious steps

undefined

1. Create Python file
2. Import necessary libraries
3. Define functions
4. Write main program logic

• Is there a clear "correct answer"? → Low freedom
• Does it need to adapt to different scenarios? → High freedom
• What's the cost of errors? → High cost = low freedom

SKILL.md (Main document, 200-500 lines)
├── reference.md (Detailed documentation)
├── examples.md (Complete examples)
└── scripts/ (Executable scripts)

• SKILL.md > 500 lines → Split into sub-files
• Sub-files > 100 lines → Add table of contents
• Reference depth ≤ 1 level

---
name: skill-name-here
description: Clear description of what this skill does and when to activate it
---

name

description

• ❌ XML tags, reserved words (

  anthropic

  ,

  claude

  )
• ❌ Vague terms (

  helper

  ,

  utility

  ,

  manager

  )
• ❌ Spaces or underscores (use hyphens

  -

  )

undefined

• User asks to analyze Python code for type errors
• User mentions "mypy" or "type checking"
• User is working in a Python project with type hints
• User needs to add type annotations

**Patterns**:
- Direct request: "User asks to X"
- Keywords: "User mentions 'keyword'"
- Context: "User is working with X"
- Task type: "User needs to X"

1. Scan the project for all

   .py

   files
2. Run

   mypy --strict

   on each file
3. Parse error output and categorize by severity
4. Generate summary report with fix suggestions

**Conditional Branching Flow**:

```markdown

1. Check project type
   • If Django → Use

     django-stubs

     config
   • If Flask → Use

     flask-stubs

     config
   • Otherwise → Use default mypy config
2. Run type checking
   • If errors found → Proceed to step 3
   • If no errors → Report success and exit

**Checklist Pattern** (Validation tasks):

```markdown

• Run tests:

  npm test

  (must pass)
• Build:

  npm run build

  (no errors)
• Check deps:

  npm audit

  (no critical vulnerabilities)

undefined

1. Scan for

   .py

   files
2. Run

   mypy

   on all files

undefined

• Simple commands → Describe directly in SKILL.md
• Complex processes → Provide standalone scripts

#!/usr/bin/env python3
"""
Brief description of what this script does.

Usage:
    python script.py <arg> [--option value]
"""

import argparse

DEFAULT_VALUE = 80  # Use constants, not magic numbers

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("directory", help="Directory to process")
    parser.add_argument("--threshold", type=int, default=DEFAULT_VALUE)

    args = parser.parse_args()

    # Validate inputs
    if not Path(args.directory).is_dir():
        print(f"Error: {args.directory} not found")
        return 1

    # Execute
    result = process(args.directory, args.threshold)

    # Report
    print(f"Processed {result['count']} files")
    return 0

if __name__ == "__main__":
    exit(main())

• ✅ Shebang line and docstring
• ✅ Type annotations and constants
• ✅ Parameter validation and error handling
• ✅ Clear return values (0=success, 1=failure)

• ✅ Provide executable commands and scripts
• ✅ Include input-output examples
• ✅ State validation criteria and success conditions
• ✅ Include Do/Don't lists

• ❌ Include general knowledge Claude already knows
• ❌ Use abstract descriptions instead of concrete steps
• ❌ Omit error handling guidance
• ❌ Use pseudocode instead of real code in examples

• name

  follows naming conventions (lowercase, hyphens, ≤64 characters)

• description

  includes trigger keywords and scenarios (≤1024 characters)
• Name matches directory name
• Only includes information Claude doesn't know
• No redundant or duplicate content

• Has "When to Use" section with 3-5 trigger scenarios
• Has clear execution flow or steps
• At least 2-3 complete examples
• Includes input and expected output
• Error handling guidance provided

• Clear section organization
• Table of contents for >200 lines
• Reference nesting ≤ 1 level
• All paths use forward slashes

  /

• Consistent terminology

• Scripts include usage instructions and parameter documentation
• Scripts have error handling
• Avoid magic numbers, use configuration
• Template format is clear and usable

• Read through for fluency and readability
• Test triggering with actual scenarios
• Appropriate length (200-500 lines, or split)

• Minimum: 50-100 lines
• Ideal: 200-500 lines
• Maximum: 500 lines (split if exceeded)

• Use keywords in

  description

  that users would say
• State specific scenarios ("when user asks to X")
• Mention related tool names

• Use more specific

  description

  to differentiate
• Explain relationships in "When to Use"
• Consider merging into one Skill

• Review quarterly, update outdated information
• Iterate based on usage feedback
• Update promptly when tools or APIs change

• Scenario 1
• Scenario 2

1. Step 1
2. Step 2

• Link

---

• Claude Agent Skills Official Documentation
• Best Practices Checklist
• Template Files - Ready-to-use templates
  • Basic skill template
  • Workflow skill template
• Example Library - Complete Skill examples
  • Good examples
  • Common mistakes