Our review

Guides the creation of a structured Agent Skill under .claude/skills/, with a prescribed SKILL.md format and on-demand reference files.

Strengths

Provides a complete copy-paste skeleton: YAML frontmatter, required sections, and folder layout
Explains progressive disclosure by capping SKILL.md at 500 lines and pushing detail into references/
Emphasises writing a description that carries trigger keywords so the agent activates the skill at the right moment
Points to existing skills in the repo (linear-ticket, write-test) as concrete models

Limitations

Assumes the repository already follows the .claude/skills/ convention and ignores other extension mechanisms
Offers no way to validate or automatically test that the new skill triggers correctly
The codebase-exploration step is a single line, with no guidance on what patterns to look for

When to use it

Use it when adding a new reusable capability, with reference documentation, for the agents working in this repository.

When not to use it

Skip it for a one-off slash command or single prompt that does not warrant the full skill structure.

Examples

New deploy-check skill

Create a new Agent Skill called deploy-check that verifies our staging deployment is healthy before we promote to production.

Skill with reference files

Write a skill for reviewing database migrations in this repo, and add reference files covering our schema naming conventions and rollback rules.

Quick invocation

/write-skill linear-ticket

description: Create a new Agent Skill for this codebase argument-hint: [skill-name] [description]

Write an Agent Skill

You are creating an Agent Skill - a structured capability that coding agents can discover and use to perform tasks more accurately and efficiently.

What is an Agent Skill?

A skill is a folder of instructions, scripts, and resources that agents load on-demand. Unlike slash commands (single prompts), skills provide comprehensive, structured guidance for complex workflows.

Key insight: Skills are consumed by coding agents, not humans. Structure them so an agent can:

Quickly understand what the skill does (from description)
Load core instructions (from SKILL.md)
Access detailed references only when needed (from references/)

Directory Structure

Create in .claude/skills/<skill-name>/:

skill-name/
├── SKILL.md              # Required - core instructions
└── references/           # Optional - detailed docs loaded on-demand
    ├── REFERENCE.md
    └── ...

SKILL.md Format

Frontmatter (Required)

---
name: skill-name          # Lowercase, hyphens only, matches folder name
description: What this skill does and WHEN to use it. Include trigger keywords.
license: Proprietary      # Optional
metadata:                 # Optional
  author: autumn
  version: "1.0"
---

Critical: The description must tell the agent WHEN to activate this skill. Include specific keywords and scenarios.

Body Structure

Write for an agent, not a human. Be direct and actionable.

## What I do

[One sentence - what capability this provides]

## Before Starting

[Prerequisites, files to read first, setup requirements]

## Critical Rules

**DO:**
- [Concrete actions]

**DON'T:**
- [Common mistakes to avoid]

## Process / Template

[Step-by-step instructions or code templates]

## References

Load these on-demand for detailed information:

- [references/TOPIC.md](references/TOPIC.md) - Brief description

Design Principles

Progressive disclosure: Keep SKILL.md under 500 lines. Move details to references/.
Agent-first writing: No fluff. Every line should help the agent do the task correctly.
Include templates: Agents work better with concrete examples and copy-paste templates.
Trigger keywords: The description should include words users might say that should activate this skill.
Reference files: Keep them focused and small. Agents load them on-demand, so smaller = less context used.

Examples in This Codebase

Study these existing skills:

.claude/skills/linear-ticket/SKILL.md - Simple skill, single file, uses MCP tools
.claude/skills/write-test/SKILL.md - Complex skill with multiple reference files

Your Task

Ask what the skill should do if $ARGUMENTS is empty or unclear
Search the codebase for patterns, existing implementations, and conventions
Create the skill directory and SKILL.md
Add references if the skill needs detailed documentation (keep SKILL.md focused)
Verify the skill follows the patterns in existing skills

Naming Convention

Folder: .claude/skills/<skill-name>/
Name must be lowercase with hyphens only
Name must match the folder name
Keep names short but descriptive: write-test, linear-ticket, code-review

Create an Agent Skill

Recommended for