claudekit / guides / build-skill
[ Guide · Advanced · 12 min ]

Build Your Own Skill

published · updated

A step-by-step guide to building your own Skill. Covers where files go, how to write the description that triggers it, and reference examples to study.

What is a Skill?

Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name. Unlike CLAUDE.md content, a skill’s body loads only when it’s used, so long reference material costs almost nothing until you need it.

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way, and existing .claude/commands/ files keep working. Skills can also declare hooks, pre-approved tools, or a forked subagent in their frontmatter. To distribute several skills together with agents, hooks, or MCP servers, package them as a Plugin.

File layout

~/.claude/skills/<skill-name>/
├── SKILL.md          # required — frontmatter + body
└── (helper files)    # optional — references, templates

SKILL.md template

---
name: <skill-name>
description: <Specific trigger conditions for invoking this Skill>
---

# Skill title

## When to use
Describe the situations that should invoke this Skill.

## Procedure
1. First step
2. Second step
3. ...

## Checklist
- [ ] Item 1
- [ ] Item 2

name is optional and defaults to the directory name.

Useful frontmatter fields

FieldPurpose
disable-model-invocation: truePrevent Claude from loading the skill automatically; trigger it manually with /name
user-invocable: falseHide it from the / menu so only Claude invokes it (background knowledge)
pathsGlob patterns that limit automatic loading to matching files
allowed-toolsTools Claude can use without asking permission during the turn that invokes the skill

Why the description matters

Claude uses description to decide when to apply the skill. The combined description and when_to_use text is truncated at 1,536 characters in the skill listing, so put the key use case first. Hallmarks of a good description:

  • Explicit trigger conditions — “when doing X”, “when handling Y files”
  • Includes feature names and keywords — words users actually use
  • Optional negative conditions — “skip if Z”

Good

description: |
  Use when creating or modifying SQL migration files in db/migrations/.
  Enforces naming convention (timestamp_description.sql), reversibility,
  and schema review checklist. Skip for read-only queries.

Bad

description: Database stuff  # too vague — Claude won't trigger reliably

Body principles

1. Number the procedure

Numbered steps are followed more reliably than prose.

2. Bold the don’ts

**Never**:
- Delete migration files manually
- Alter columns without an explicit ALTER TABLE

3. Include verification

## Verify
- After applying: `npm test`
- Roundtrip: `npm run db:rollback && npm run db:migrate`

4. Use absolute references

When you reference another Skill or doc, name it explicitly.

Example: a content review Skill

---
name: review-content
description: |
  Use when reviewing or modifying content files in src/content/.
  Checks frontmatter schema, ko/en pair consistency, link validity,
  and applies the project quality rules.
---

# Content Review

## When to run
- After any content file is created or modified
- Before deployment

## Procedure
1. Verify frontmatter against schema
2. Check ko/en pair consistency (slug, dates align)
3. Validate external links
4. Review tone consistency

## Verify
\```bash
npm run build
\```

Where skills load

LocationLoads in
~/.claude/skills/<name>/SKILL.md (Personal)All your projects on this machine
.claude/skills/<name>/SKILL.md (Project)Sessions in this repository; commit it so your team gets it too
<plugin>/skills/<name>/SKILL.md (Plugin)Wherever the plugin is enabled, as /plugin-name:skill-name
.claude/skills/ in the managed settings directory (Enterprise)All users on machines where your organization deploys it

To share with a team, commit .claude/skills/ to version control. For distribution across repositories or to the public, bundle the skill into a plugin and list it on a marketplace.

Claude Code watches skill directories for file changes, so adding or editing a SKILL.md takes effect in the current session without a restart. If you create a top-level skills directory that didn’t exist when the session started, run /reload-skills.

Common mistakes

  • ❌ description too short — Claude won’t trigger
  • ❌ Body written as prose — split into steps
  • ❌ Skill scope too broad — one Skill = one procedure
  • ❌ Trigger conditions overlap with another Skill — keep them distinct

Next steps

§ 10

Frequently Asked Questions

frequently asked
§ 10.1
What is a Skill?
A `SKILL.md` file with instructions that Claude adds to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`; the frontmatter `description` tells Claude when to apply it.
§ 10.2
How is it different from a Plugin?
A Skill is a single set of instructions; a Plugin is a package that can bundle skills, agents, hooks, and MCP servers for distribution. Custom commands have been merged into skills, so a skill on its own creates a `/name` command.
§ 10.3
Where do Skill files live?
Personal: `~/.claude/skills/<skill-name>/SKILL.md`, loaded in all your projects. Project: `.claude/skills/<skill-name>/SKILL.md`, committed so your team gets it too. Plugin: `<plugin>/skills/<skill-name>/SKILL.md`, invoked as `/plugin-name:skill-name`.
§ 10.4
Why does the description matter?
Claude uses the `description` to decide when to apply the skill. Put the key use case first: the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing.
§ 10.5
Are there good examples to learn from?
The skills in Jesse Vincent's Superpowers plugin (obra/superpowers), such as brainstorming, systematic-debugging, and writing-plans, are useful references for description format, body structure, and procedure phrasing.