ailiteracynepal 🇳🇵
Text size

Chapter 05 · Section II · 12 min read

Anatomy of a skill

Every skill boils down to three parts — a name, a description, and a prompt. Optional pieces (resources, argument hints, subagent glue) hang off that core. Once you can read one skill file, you can read them all.

A skill is a directory. The directory contains at minimum a manifest and a prompt file. Everything else — templates, sample outputs, checklists — is optional context the skill can pull in when it runs. Once you have seen one, they are all variations on the same theme.

The manifest

Every skill has a SKILL.md at its root. The frontmatter is small:

---
name: migration-safety
description: >
  Audit a pending database migration for safety issues:
  destructive ops, missing indexes, incompatible column changes.
argument-hint: (optional) filename of the migration to audit
---

Three fields do most of the work:

  • name. How the skill is invoked. /migration-safety.
  • description. What the skill does, in one or two sentences. Claude Code shows this in /help and uses it to decide relevance.
  • argument-hint. A short note on what arguments the skill accepts, if any.

The prompt body

Everything below the frontmatter in SKILL.md is the prompt that gets loaded into Claude’s context when the skill is invoked. It is a system-level briefing: the goal, the constraints, the steps, the output format.

A well-shaped skill body reads like a short checklist:

# Migration safety audit

You are reviewing a pending SQL migration for safety. Follow this order:

1. Identify the migration file: use the argument if provided,
   otherwise ask.
2. Read the file. Look for:
   - Column type changes on populated tables.
   - `DROP` statements.
   - New NOT NULL columns without defaults.
   - Missing indexes on foreign keys.
3. Produce a report with severity (blocking / worth-fixing / ok).

Never edit the migration yourself. Report only.

Short is a feature. The clearer the checklist, the more consistent the output.

Attached resources

A skill directory can include supporting files:

.claude/skills/migration-safety/
├── SKILL.md
├── checklist.md
└── examples/
    ├── unsafe-drop-column.sql
    └── good-migration.sql

The skill body can reference these (“compare against examples/good-migration.sql”) and Claude will Read them at execution time. Handy for keeping the SKILL.md itself short while making the reference material available.

Skills that call subagents

A skill can be a thin wrapper that briefs and spawns a subagent. Useful when the work is broad enough to want isolation but common enough to want a slash command. The skill body just says: “spawn a general-purpose subagent with the following briefing…” — and Claude follows.

Reading someone else’s skill

The fastest way to learn how skills are written is to read one. ~/.claude/skills/ has any you already have installed; the repo .claude/skills/ has team-specific ones. Open a SKILL.md. Read the frontmatter, read the body, read any attached files. Twenty minutes of that beats an hour of documentation.

Check your understanding

Quick check

—

Which of the following is the minimum needed to make a Claude Code skill runnable?