Skill Writing

Writing Effective Claude Code Skills

Core Principle: Progressive Disclosure

The most important concept for building skills is progressive disclosure — show just enough information to help Claude decide what to do next, then reveal more details as needed.

• Keep SKILL.md under 500 lines
• Move detailed reference material to separate files
• Reference supporting files so Claude knows when to load them

Skill File Structure

Every skill needs a SKILL.md file with two parts:

---
name: my-skill-name
description: What this skill does and when to use it
---

# Skill Title

[Instructions Claude follows when the skill is invoked]

## Examples
## Guidelines

Directory Structure

my-skill/
├── SKILL.md           # Main instructions (required)
├── reference.md       # Detailed docs (loaded when needed)
├── examples/          # Example outputs
└── scripts/           # Executable scripts

Frontmatter Reference

Types of Skill Content

Reference Skills (Knowledge)

Add conventions, patterns, or domain knowledge Claude applies to current work:

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats

Task Skills (Actions)

Step-by-step instructions for specific actions. Usually user-invoked only:

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to deployment target

String Substitutions

Invocation Control Matrix

Best Practices

DO

• Use active, directive language ("Run tests", not "Tests should be run")
• Break complex tasks into numbered sequential steps
• Include concrete examples showing expected format
• Specify output formats when consistency matters
• Test skills with both direct invocation and natural language

DON'T

• Put reference content in task skills (use context: fork instead)
• Create skills for one-off tasks (just ask Claude directly)
• Exceed 500 lines in SKILL.md (use supporting files)
• Use disable-model-invocation for reference skills

When to Create a Skill

Create a skill when:

• You type the same prompt repeatedly across conversations
• Team knowledge should be codified and shared
• A workflow has specific steps that must be followed
• You want Claude to automatically apply certain patterns

Use CLAUDE.md instead when:

• Instructions apply to the entire project always
• Context is needed for every conversation
• Settings are project-wide conventions

Skill Locations

Example: Well-Structured Skill

---
name: review-pr
description: Review a pull request for code quality, security, and best practices
argument-hint: [pr-number]
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

# Pull Request Review

Review PR #$ARGUMENTS for:

## 1. Code Quality
- Readability and maintainability
- Consistent naming conventions
- Appropriate abstractions

## 2. Security
- Input validation
- Authentication/authorization
- No secrets in code

## 3. Testing
- Adequate test coverage
- Edge cases handled

## Context
- PR diff: !`gh pr diff $ARGUMENTS`
- PR description: !`gh pr view $ARGUMENTS`

Provide actionable feedback with specific line references.

Additional Resources

For the official specification, see Agent Skills. For Claude Code documentation, see Extend Claude with skills.

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