Skills Guide

Requirements: Claude Code installed (Node.js only needed for the optional npx skills add method) — full walkthrough in 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.

---
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:

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 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

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

skills-guide