Skills

How Skills Work

What Is a Skill?

A skill is a SKILL.md file that contains instructions for Claude. When you type /skill-name, Claude reads the file and follows the instructions as if you'd typed them yourself — but with much more detail and consistency than you'd write each time.

# Skill directory structure
.claude/skills/
├── new-page/
│   ├── SKILL.md              # The instructions
│   └── references/
│       └── page-templates.md  # Supporting files
├── commit/
│   └── SKILL.md
└── review-pr/
    └── SKILL.md

Anatomy of SKILL.md

A SKILL.md has two parts: frontmatter (metadata) and the instruction body.

---
name: new-page
description: Create a new content page with all required elements
---

# New Page Creator

## Arguments
- `{topic}` — the topic name (e.g., "docker")
- `{level}` — page level: 1 (overview), 2 (core-concepts), 3 (deep-dive)

## Steps

1. Read the page template from `references/page-templates.md`
2. Create the HTML file at `domains/{domain}/{topic}/{page}.html`
3. Fill in all placeholders with topic-specific content
4. Add entry to `js/site-data.js` PAGES array
5. Add URL to `sitemap.xml`

## Rules
- Every page MUST have a TL;DR box
- Include at least 5 Test Yourself questions
- Related Topics must link to real pages, never placeholders

Passing Arguments

Skills can accept arguments passed after the slash command:

# Invoke with arguments
/new-page docker overview

# Claude receives:
# Arguments: docker overview
# Then parses them according to the SKILL.md instructions

Arguments are passed as a single string. The skill's instructions define how to parse them. Common patterns:

• Positional: /new-page {topic} {level}
• Named: /deploy --env production --tag v2.1
• Free-form: /explain How does the auth middleware work?

Reference Files

Complex skills need supporting files — templates, examples, checklists. Put them in a references/ subdirectory:

.claude/skills/new-page/
├── SKILL.md
└── references/
    ├── page-templates.md    # HTML skeletons for each page level
    ├── seo-checklist.md     # SEO requirements
    └── example-page.html    # A completed example for reference

In your SKILL.md, reference them with relative paths:

## Step 1: Read Templates
Read `references/page-templates.md` for the HTML skeleton.
Use the Level 3 template for deep-dive pages.

Real-World Skill Examples

Creating Your Own Skill

Walk-through: create a /changelog skill that generates release notes.

# 1. Create the directory
mkdir -p .claude/skills/changelog

# 2. Write .claude/skills/changelog/SKILL.md

---
name: changelog
description: Generate release notes from recent git commits
---

# Changelog Generator

## Steps
1. Run `git log --oneline` since the last tag
2. Group commits by type (feat, fix, docs, refactor)
3. Write a CHANGELOG.md entry with the version and date
4. Include breaking changes in a separate section

## Output Format
```
## [1.2.0] - 2026-04-04

### Added
- Feature description (#PR)

### Fixed
- Bug fix description (#PR)

### Breaking Changes
- Description of what changed and migration steps
```

# 3. Use it
/changelog

Best Practices

• One skill, one job — a skill should do one thing well. Don't combine "create page" and "deploy site" in one skill.
• Include examples — show Claude what good output looks like. A concrete example beats a page of rules.
• Version control your skills — commit .claude/skills/ to git so the team shares the same workflows.
• Test iteratively — run the skill, see what's wrong, fix the SKILL.md, repeat. Skills improve over time.
• Document arguments — list expected arguments clearly in the SKILL.md so users know what to pass.
• Keep instructions actionable — "Create the file at X with Y content" beats "The file should be good."

Interview Questions