claude-plugins/claude-skills/SKILL.md

name, description

name	description
Skill Creator	Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use when building new skills or improving existing ones.

Skill Creation Best Practices

When to Use This Skill

Use this skill when:

• Creating a new Agent Skill from scratch
• Improving or refactoring an existing skill
• Debugging why a skill isn't triggering correctly
• Understanding skill architecture and design patterns
• Optimizing skill structure for token efficiency

Core Principle: Progressive Disclosure

Progressive disclosure is the fundamental design pattern for Agent Skills. It works in three layers:

Layer 1: Metadata (Always Loaded)

• What: YAML frontmatter with name and description
• When: Pre-loaded at every session start
• Cost: ~100 tokens per skill
• Purpose: Trigger detection - helps Claude decide if skill is relevant

Layer 2: Instructions (Triggered)

• What: Main SKILL.md content
• When: Loads when Claude determines skill applies
• Cost: Variable (keep focused and concise)
• Purpose: Procedural guidance, workflows, best practices

Layer 3: Resources (On-Demand)

• What: Additional files, scripts, reference materials
• When: Only when explicitly needed
• Cost: Only when accessed
• Purpose: Deep reference, executable code, examples

Skill Structure Requirements

Mandatory: SKILL.md File

Every skill MUST have a SKILL.md file with YAML frontmatter:

---
name: Your Skill Name
description: Clear description of what this does and when to use it
---

Critical Constraints:

• Name: Maximum 64 characters
• Description: Maximum 1024 characters
• The description is crucial - it determines when Claude triggers the skill

Optional: Additional Resources

Structure additional files strategically:

my-skill/
├── SKILL.md                 # Main entry point (required)
├── reference.md             # Deep reference material (load on-demand)
├── examples.md              # Code samples and templates
├── workflows/               # Step-by-step procedures
│   ├── advanced.md
│   └── beginner.md
└── scripts/                 # Executable utilities
    └── helper.sh

Writing Effective Descriptions

The description field is your skill's trigger mechanism. Make it count:

Good Descriptions

✓ Specific use cases: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables" ✓ Clear triggers: "Use when building React components following atomic design principles" ✓ Domain clarity: "Debug Swift applications using LLDB for crashes, memory issues, and runtime errors"

Poor Descriptions

✗ Too vague: "Helps with coding" ✗ No trigger context: "Python utilities" ✗ Feature list without purpose: "Has functions for A, B, and C"

Template for Descriptions

[Action verb] [specific domain/task] [with/for/using] [key capabilities].
Use when [primary trigger scenario] [and optional secondary scenarios].

Example: "Create professional PowerPoint presentations with custom themes, charts, and animations. Use when building slide decks, pitch presentations, or visual reports."

Best Practices for SKILL.md Content

1. Start with "When to Use This Skill"

Immediately clarify trigger scenarios:

## When to Use This Skill

Use this skill when:
- [Primary scenario]
- [Secondary scenario]
- [Edge case to include]

Do NOT use this skill for:
- [Common confusion case]
- [Related but different scenario]

2. Structure for Scannability

Use clear hierarchies and action-oriented headers:

## Quick Start
[Minimal example to get started]

## Core Workflows
### Workflow 1: [Name]
1. Step one
2. Step two

### Workflow 2: [Name]
1. Step one
2. Step two

## Advanced Techniques
[Less common but powerful approaches]

## Common Pitfalls
[Known issues and how to avoid them]

3. Include Concrete Examples

Always provide working examples, not abstract descriptions:

## Example: Creating a User Authentication Module

**Scenario**: Building JWT-based auth for a Flask API

**Steps**:
1. Install dependencies: `pip install pyjwt flask-login`
2. Create auth.py with [specific structure]
3. Configure middleware in app.py
4. Add protected routes with @login_required

**Result**: Users can register, login, and access protected endpoints

4. Reference Additional Files Explicitly

When you need to split content, reference it clearly:

## Deep Dive: Advanced Patterns

For comprehensive examples of [topic], see [examples.md](examples.md).

For API reference, consult [reference.md](reference.md).

Optimizing for Token Efficiency

When to Split Files

Keep in SKILL.md if:

• Information is needed for 80%+ of use cases
• Content is under ~2000 tokens
• Steps are sequential and interdependent

Split to separate file if:

• Content is mutually exclusive (e.g., Python vs JavaScript examples)
• Material is reference-heavy (API docs, configuration options)
• Information is advanced/edge-case focused

Code as Documentation

Executable scripts serve dual purposes:

1. Tools Claude can run without loading code into context
2. Documentation by example showing best practices

## Generating Boilerplate

Run the initialization script to create project structure:

```bash
./scripts/init-project.sh my-app

This creates [description of what's created].

Claude can execute this without the script code consuming context tokens.

## Development Workflow

### 1. Start with Evaluation

**Don't guess what skills you need.** Instead:
1. Run Claude on representative tasks
2. Identify where it struggles or asks repetitive questions
3. Capture successful patterns from those sessions
4. Codify into a skill

### 2. Iterate with Claude

Build skills collaboratively:
1. Work with Claude on a task
2. When you find a good solution, ask: "Should we capture this as a skill?"
3. Let Claude help structure the skill content
4. Test with new similar tasks
5. Refine based on actual usage

### 3. Monitor Trigger Accuracy

After creating a skill, test whether it triggers correctly:

**Test scenarios:**
- Direct requests that SHOULD trigger it
- Similar requests that SHOULD trigger it
- Related requests that should NOT trigger it

If triggering is unreliable, refine the `description` field.

### 4. Start Simple, Grow Organically

Begin with a minimal SKILL.md:
- Clear metadata
- One core workflow
- A few examples

Add complexity only when you encounter actual needs:
- Split files when SKILL.md exceeds ~3000 tokens
- Add scripts when you repeat the same commands
- Create reference files for API documentation

## Common Patterns by Domain

### Code Development Skills

```markdown
---
name: [Framework/Language] [Pattern] Guide
description: [Action] [framework] applications following [specific pattern/principles]. Use when building [type of apps] with [key requirements].
---

## When to Use This Skill
Use when building [specific project type] with [language/framework]

## Project Structure
[Standard directory layout]

## Core Workflows
### Create New [Component Type]
[Step-by-step process]

### Common Patterns
[Frequently used code patterns with examples]

## Testing Strategy
[How to test this type of code]

Workflow/Process Skills

---
name: [Task] Workflow
description: [Action] for [domain] following [methodology]. Use when [scenario].
---

## When to Use This Skill
Use when you need to [primary task] and [key differentiator]

## Prerequisites
[What's needed before starting]

## Step-by-Step Process
### Phase 1: [Name]
[Detailed steps]

### Phase 2: [Name]
[Detailed steps]

## Quality Checklist
- [ ] [Verification step]
- [ ] [Verification step]

Reference/Documentation Skills

---
name: [Topic] Reference
description: [Type of information] for [domain/tool]. Use when [looking up/configuring/understanding] [specific aspects].
---

## Quick Reference
[Most common lookups in concise format]

## Detailed Documentation
See [reference.md](reference.md) for comprehensive API documentation.

## Common Tasks
### Task 1
[Quick example]

### Task 2
[Quick example]

Security Considerations

For Skill Creators

Never include in skills:

• Hardcoded credentials or API keys
• Personal identifying information
• Proprietary code without permission
• Instructions to make unsafe system changes

Always consider:

• Can this skill be misused if shared?
• Does it access sensitive file locations?
• Are external dependencies from trusted sources?

For Skill Users

Before installing a skill:

1. Audit all files in the skill package
2. Check for network access attempts
3. Review any bundled scripts for malicious code
4. Verify the source is trustworthy

Debugging Skills

Skill Doesn't Trigger

Checklist:

1. Is the description specific enough?
2. Does the description mention the trigger scenario?
3. Is the name too generic?
4. Test with explicit requests mentioning keywords from the description

Example fix:

• Before: description: "Python development helpers"
• After: description: "Create Python projects using Hatch and Hatchling for dependency management. Use when initializing new Python packages or configuring build systems."

Skill Triggers Too Often

Checklist:

1. Is the description too broad?
2. Add negative cases: "Do NOT use for..."
3. Make the domain more specific

Content Doesn't Load

Checklist:

1. Verify file paths in references are correct
2. Check that additional .md files are in the skill package
3. Ensure script paths are relative to skill root

Skill Metadata Checklist

Before finalizing a skill, verify:

• Name is under 64 characters
• Description is under 1024 characters
• Description includes specific use cases
• Description mentions when to trigger the skill
• SKILL.md has YAML frontmatter with both fields
• "When to Use This Skill" section is present
• At least one concrete example is included
• No sensitive information is hardcoded
• File references are accurate
• Tested triggering with target scenarios
• Tested NOT triggering with related but different scenarios

Resources

Official Documentation

• Agent Skills Overview
• Engineering Blog Post
• Using Skills Guide

Example Skills

Study Anthropic's pre-built skills for reference:

• Excel (xlsx) - Complex domain with many features
• Word (docx) - Document generation workflows
• PowerPoint (pptx) - Creative + structured content
• PDF (pdf) - File manipulation and analysis

Quick Start Template

Use this template to begin a new skill:

---
name:
description:
---

# [Skill Name]

## When to Use This Skill

Use this skill when:
-
-

Do NOT use this skill for:
-

## Quick Start

[Minimal working example]

## Core Workflows

### Workflow 1: [Name]

1.
2.
3.

**Example:**

[Code or command]

**Result:** [What this achieves]

## Common Pitfalls

### Issue: [Problem]
**Solution:** [How to avoid/fix]

### Issue: [Problem]
**Solution:** [How to avoid/fix]

## Advanced Topics

[Optional: complex scenarios or optimizations]

---

Remember: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.