Building Custom Skills

A skill is a Markdown file that Claude reads and follows as a procedure. Writing your own lets you encode workflows specific to your team or project — things like your preferred debugging approach, your PR checklist, or a domain-specific code review process.

File structure

A skill is a .md file with a YAML frontmatter block and a body:

---
name: my-skill-name
description: One sentence describing when this skill applies and what it does.
---

# Skill Title

Instructions go here. Write them the way you'd brief a capable colleague
who has never done this task before.

## Step 1: Do the first thing

Explain what to do and why.

## Step 2: Do the second thing

...

The name is how the skill is invoked. The description is used to decide whether the skill is relevant to a given task — make it specific.

Where to put skills

Skills live in a skills/ directory inside a plugin. For personal skills, the simplest place is your second brain:

~/second-brain/skills/
└── my-plugin/
    ├── my-skill.md
    └── another-skill.md

Point your Claude Code config at this directory to make the skills available.

Writing good instructions

Write for someone with no context. A skill gets loaded fresh — Claude doesn’t remember previous conversations. Every step needs to be self-contained.

Be procedural, not descriptive. “Check whether the failing test is testing the right thing” is better than “make sure tests are good.” Give Claude a concrete action at each step.

Include decision points. Skills often need to branch: “if X, do Y; otherwise do Z.” Make these explicit rather than leaving Claude to infer.

Keep scope tight. A skill that tries to do too much produces inconsistent results. One skill per workflow, one workflow per skill.

Testing a skill

Invoke the skill on a real task and check whether Claude followed the procedure correctly. The most common failure modes:

• Too vague — Claude fills gaps with assumptions; tighten the instructions
• Too long — Claude skips or conflates steps; break into smaller skills
• Wrong trigger — the description doesn’t match the situations you want it to activate; rewrite it

Sharing skills

Skills are just files — share them the same way you share any other code. Commit them to a repo, distribute them as a plugin package, or reference them from a shared second brain.

See Superpowers Skills for how the built-in skill library is organised.