writing-skills

Writing Skills

Create effective Claude Code skills that are concise, well-structured, and follow official best practices.

Quick Reference

YAML Frontmatter

Every skill requires frontmatter:

---
name: skill-name
description: Third person description of what skill does and when to use it. Include trigger phrases.
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"]  # Optional
model: sonnet  # Optional: opus, sonnet, haiku
---

Frontmatter Fields

Naming Conventions

Use gerund form (verb ending in -ing):

Rules:

• Lowercase letters, numbers, hyphens only
• No spaces or underscores
• Maximum 64 characters
• Descriptive of what the skill helps accomplish

Progressive Disclosure

Keep SKILL.md focused. Split detailed content to reference files.

Pattern 1: Table of Contents

## Reference Files

| File | Contents |
|------|----------|
| [TEMPLATES.md](./TEMPLATES.md) | Starter templates |
| [EXAMPLES.md](./EXAMPLES.md) | Real-world examples |
| [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) | Common issues |

Pattern 2: Inline Links

For detailed templates, see [TEMPLATES.md](./TEMPLATES.md).

Pattern 3: Conditional Loading

## Advanced Configuration

If you need custom model settings, see [ADVANCED.md](./ADVANCED.md).

Skill Structure

Recommended Sections

1. Quick Reference - Table with key requirements
2. Core Instructions - Main guidance (bulk of skill)
3. Workflows - Step-by-step procedures with checklists
4. Examples - Input/output pairs
5. Reference Files - Links to detailed content

File Organization

skills/
└── skill-name/
    ├── SKILL.md           # Main skill file (required)
    ├── TEMPLATES.md       # Starter templates (optional)
    ├── EXAMPLES.md        # Detailed examples (optional)
    └── TROUBLESHOOTING.md # Common issues (optional)

Skill Discovery Locations

Skills are discovered from these locations:

Nested Skills Discovery (2.1.6+): When working with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills directories. This enables monorepos and multi-package projects to have package-specific skills.

my-monorepo/
├── .claude/skills/          # Root skills (always available)
│   └── deploy/
├── packages/
│   ├── frontend/
│   │   └── .claude/skills/  # Auto-discovered when working in frontend/
│   │       └── component-generator/
│   └── backend/
│       └── .claude/skills/  # Auto-discovered when working in backend/
│           └── api-scaffolder/

Writing Effective Descriptions

Descriptions appear in skill discovery. Make them count.

Structure

[What it does]. [When to use it]. [Key triggers/phrases].

Examples

Good:

Guide for creating effective Claude Code skills. Use when creating new
skills, refactoring existing skills, or validating skill structure.
Covers YAML frontmatter, progressive disclosure, and naming conventions.

Avoid:

A skill for writing skills.

Workflows

Include step-by-step workflows with copyable checklists.

Workflow Template

## Workflow: [Name]

### Prerequisites
- [ ] Requirement 1
- [ ] Requirement 2

### Steps

1. **Step Name**
   - [ ] Action item
   - [ ] Action item

2. **Step Name**
   - [ ] Action item

### Validation
- [ ] Check 1
- [ ] Check 2

Examples Section

Show concrete input/output pairs.

Example Template

## Examples

### Example: [Scenario Name]

**Input:**

User request or context

**Output:**

Expected result or response

**Why:** Brief explanation of approach.

Validation Checklist

Before finalizing a skill:

• Name uses gerund form
• Name is lowercase with hyphens only
• Description is third person
• Description includes when to use
• SKILL.md is under 500 lines
• Reference files are one level deep
• Workflows have copyable checklists
• Examples show input/output pairs

Common Mistakes

Advanced Configuration

Forked Context

Run skills in an isolated sub-agent context using context: fork:

---
name: complex-analysis
description: Deep analysis that benefits from isolated context
context: fork
agent: Explore  # Optional: specify agent type
---

When to use:

• Long-running analysis that shouldn't pollute main context
• Skills that generate large outputs
• Isolated workflows that should not affect main conversation

Visibility Control

Control how skills appear and can be invoked:

---
name: internal-helper
description: Helper skill only invoked by other skills
user-invocable: false  # Hide from slash menu
---

Skills with Hooks

Add lifecycle hooks that run during skill execution:

---
name: validated-deploy
description: Deploy with validation hooks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./validate.sh"
          once: true
---

See creating-hooks for complete hook documentation.

Skills in Subagents

Skills can be auto-loaded for custom subagents using the skills field in agent definitions:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code using specialized skills
skills:
  - code-review
  - security-practices
---

Note: Built-in agents (Explore, Plan, general-purpose) do not have skill access.

Reference Files