Learn

Get the max out of skills.

A pragmatic guide, drawing on Anthropic's published guidance and what actually ships in practice. Short, opinionated, and written for busy engineers.

Seven principles for great skills

1
Narrow beats broad
A skill should do one thing, exceptionally. If yours covers three workflows, split it into three skills. Smaller scope means clearer prompts, tighter tools, and easier trust.
2
Separate the human trigger from the machine action
"What the user does" is one sentence. "What the skill does" is the real behavior. Keep them decoupled — that's what lets people remix the surface without breaking the core.
3
Grant the fewest tools you need
Every extra tool is extra surface area. Start with Read and Grep. Add Bash, Write, network only when the skill visibly benefits.
4
Instructions are a playbook, not a description
Don't re-explain what the skill does. Say what matters in edge cases: priorities, what to refuse, how to decide ties. Trust Claude's defaults for the rest.
5
Make success verifiable
Tests pass. File exists. Diff applied. Always give the skill a concrete signal to check, not just a vibe. "Never approve without running the tests" is worth 10 paragraphs of tone.
6
Show, don't tell
A single preview — a real example run — builds more trust than any description. Skills with previews get 3× more downloads in practice.
7
Ship v1, iterate in public
Your first version will miss an edge case. That's fine — the comments section exists for this. Read the feedback, version up, publish a changelog, move on.

These are the proven shapes that show up across the library. Pick one as a starting point in the wizard.

🧐

The Reviewer

Shape. Reads a diff → pulls context → posts severity-tagged findings with suggested diffs.

Gotcha. Don't lint. Reviewers that spam style nits get muted. Ship opinions on correctness & security.

🧪

The Generator

Shape. Reads existing samples → learns style → writes new artifacts that match.

Gotcha. Always learn from the repo's conventions first. Never invent your own naming or folder layout.

📝

The Translator

Shape. Input in one shape (PRs, logs, Slack thread) → output in another (docs, postmortem, ticket).

Gotcha. Match the voice of the output system, not the input. Changelog voice ≠ commit voice.

🔍

The Auditor

Shape. Walks a graph / codebase → reports findings ranked by severity.

Gotcha. No false positives. A noisy auditor loses trust after one bad report. Demand a clear exploit path.

🛠

The Scaffolder

Shape. Prompts for minimal input → writes files with types, tests, and validation wired up.

Gotcha. Always generate the test alongside the code. Scaffolders without tests are half a skill.

🧭

The Triager

Shape. Classifies incoming items → routes to the right queue / person / action.

Gotcha. Surface confidence. Never silently decide when the signal is weak.

Over-granting tools. If Bash is in your tool list, everything in your shell is reachable. Ask: "Would I want this skill to be able to run that command unattended?"
Chatty instructions. Long instructions hide the important bits. If your prompt is 50 lines, 40 of them are noise.
Hidden state. Don't assume environment vars, git identity, or paths. State your assumptions in the instructions and fail loudly if they're missing.
Skills that can't say no. Great skills refuse out-of-scope work. "If the diff has no test changes, skip the test-quality pass" is a feature, not a limitation.
Forgotten error paths. The happy path is 80% of the skill. The other 20% is how it behaves when things break — that's what users remember.

For deeper reading, start with Anthropic's guides. We keep this list short on purpose — these three will cover 90% of what you need.

Note: verify the links when you deploy — docs paths can shift.