# Skills Guide

**Requirements:** Claude Code installed (Node.js only needed for the optional `npx skills add` method) — full walkthrough in [SETUP.md](SETUP.md).

A practical guide to Claude Code skills: what they are, where they live, how to
write one, and how to install skills someone else built.

This repo is documentation, not a dump. It does not contain any of 19Keys'
private skills — it teaches you the format so you can build your own.

## What is a skill

A skill is a packaged instruction set that Claude Code loads on demand for a
specific kind of task. Instead of you re-explaining "how we do code review
here" or "how our deploy process works" every session, you write it once as a
skill. Claude reads a one-line description of every installed skill at the
start of a session, and when your request matches that description, it loads
the full instructions for that task only — not all of them, all the time.

Think of a skill as a reusable, named procedure: a checklist, a workflow, a
house style guide, a wrapper around a CLI. It is markdown, not code. It works
because Claude is good at following clear written instructions when they show
up at the right moment.

## Where skills live

Skills are discovered from two locations:

- **Global**: `~/.claude/skills/<skill-name>/SKILL.md` — available in every
  project on your machine.
- **Per-project**: `.claude/skills/<skill-name>/SKILL.md` — available only
  inside that one repo, and can be checked into version control so your team
  shares it.

Each skill is a directory containing at minimum a `SKILL.md` file. The
directory name is the skill's identifier. A skill can also include extra
reference files (templates, scripts, longer docs) alongside `SKILL.md` — keep
those in the same folder and point to them from the instructions.

## The SKILL.md format

Every `SKILL.md` starts with YAML frontmatter (between `---` lines), then the
instructions as plain markdown below it.

```markdown
---
name: readme-clarity-review
description: Reviews a README for clarity and completeness — flags missing sections, jargon, and unclear quickstart steps. Use when the user asks to review, audit, or improve a README file.
---

# README Clarity Review

When the user asks you to review a README:

1. Read the full file first.
2. Check for these sections: what the project is, why it matters, how to
   install/run it, and how to configure it. Flag any that are missing.
3. Flag jargon or acronyms used without a first definition.
4. Try to follow the quickstart literally, step by step, as written. If a
   step assumes something the reader hasn't been told yet, flag it.
5. Report findings as a short list: section, issue, one-line fix. Do not
   rewrite the whole file unless asked — just report what's wrong.
```

Two frontmatter fields matter:

- `name` — the skill's identifier. Should match the directory name.
- `description` — the single line Claude sees when deciding whether this
  skill applies to the current request. This is the most important line in
  the file. It needs to say what the skill does AND when to trigger it
  ("Use when...").

Everything after the frontmatter is the actual instructions, written the same
way you'd write instructions for a careful junior teammate: concrete steps,
not vague goals.

## Installing a shared skill

If someone has published a skill in a git repo, install it with:

```bash
npx skills add <owner>/<repo> --skill <skill-name>
```

This pulls the named skill's directory into your local skills folder. Check
which location (global vs. project) the installer places it in, and move it
if you want the other scope.

To install everything a repo offers, omit `--skill` and follow the tool's
prompts, or copy the skill directories manually — a skill is just a folder,
so copying it by hand works too.

## Writing your own well

A handful of rules separate skills that trigger reliably and stay useful from
ones that don't:

- **One job per skill.** A skill that tries to cover "deployment and code
  review and commit messages" will have a vague description and won't
  trigger reliably for any of the three. Split it into three skills.
- **Write the trigger explicitly.** The description should name concrete
  phrases or situations: "Use when the user asks to deploy to staging" beats
  "Helps with deployment." Claude matches on this line before it ever reads
  the rest of the file.
- **Keep it short.** A skill is loaded into context when it triggers. Long
  skills cost tokens every time they fire. Put the essential steps in
  `SKILL.md` and push long reference material (full API docs, large
  examples) into separate files in the same directory that the instructions
  point to only when needed.
- **Put project facts in the project, not the skill.** A skill should
  describe a repeatable process. Facts that are specific to one project or
  change over time — API keys, current file paths, this quarter's numbers —
  belong in that project's own config or CLAUDE.md, not hardcoded into a
  skill you might reuse or share elsewhere.
- **Test the trigger, not just the instructions.** After writing a skill, ask
  a question that should trigger it and one that's adjacent but shouldn't,
  and confirm the description discriminates correctly.

## Example

See [`examples/hello-skill/SKILL.md`](examples/hello-skill/SKILL.md) for a
complete, minimal skill that reviews a README for clarity. Copy it into
`~/.claude/skills/readme-clarity-review/` or `.claude/skills/` in a project
to try it, or use it as a template for your own first skill.

## Make it your own

1. Copy `examples/hello-skill/` into `.claude/skills/<your-skill-name>/` in a
   project, or `~/.claude/skills/<your-skill-name>/` to make it global.
2. Rename the directory and update `name` in the frontmatter to match.
3. Rewrite `description` to describe your actual task and its trigger.
4. Replace the instructions with your own steps.
5. Ask Claude something that should trigger it and confirm it loads.