Claude Code is the one Claude surface that genuinely installs skills from disk, which means the advice for it is different from everything written about Custom Instructions. This is a practical guide: how the folder works, what makes a skill worth keeping, and where people waste their time.
How skills work in Claude Code
Skills live in a .claude/skills/ directory. Each skill is a subfolder with a SKILL.md inside it. Two locations matter:
-
Project -
.claude/skills/inside the repository. The skill travels with the code, so everyone on the team gets it. This is where anything project-specific belongs. - Personal - the same path in your home directory. Applies to everything you work on. This is where your own habits belong.
Unlike Custom Instructions, which holds one thing at a time, Claude Code can hold many skills and pull in whichever one matches what you are doing. That changes what a good skill looks like: it needs a description precise enough that the right one gets picked, and narrow enough that it does not get picked for everything.
What makes a skill actually earn its place
After building a lot of these, the pattern is consistent. Good skills encode decisions, not information.
A skill that lists what a REST API is wastes tokens on something the model already knows. A skill that says "in this repo, every endpoint returns errors in the RFC 7807 shape, and the three places that do not are legacy and must not be copied" is worth keeping forever, because that is a decision the model cannot infer.
The test: if a competent engineer joining your team would need to be told it, put it in a skill. If they would already know it, leave it out.
The categories worth having
Code review with a house standard
Generic review comments are noise. A review skill that carries your team's actual conventions, the things you have argued about and settled, turns review from opinion into a checklist.
Testing conventions
Which framework, what a test is named, what gets mocked and what never does, and what counts as enough coverage for this codebase. Without it you get tests in whatever style was most common in training data.
Debugging and incident work
Where the logs are, which dashboard answers which question, the four things to check before escalating. This is the skill that pays for itself at 3am.
Infrastructure and deployment
The deploy sequence, what is safe to run against production and what is not, which migrations need a maintenance window. Encoding the dangerous parts is the point.
Documentation and technical writing
Where docs live, the structure a page follows, the difference in your house style between a tutorial and a reference.
What to skip
Language tutorials. A skill explaining Python syntax to Claude is a skill explaining Python syntax to something that already knows Python syntax.
Enormous catch-all skills. One skill covering frontend, backend, testing and deployment gets loaded constantly and is mostly irrelevant every time. Split it.
Anything that will be stale in a month. Version numbers, current sprint goals, the name of whoever is on call. Skills are for durable decisions.
Vague descriptions. If the description does not say clearly when the skill applies, it will either never be selected or always be selected. Both are useless.
Starting from a template rather than a blank page
The hardest part is not the idea, it is the shape: how specific to be, what to leave out, how to write the description so selection works. That is the part worth copying from something already tested.
We publish role-based skill files for developers, DevOps and architects, written as plain .md and usable either as a Claude Code skill or pasted into Custom Instructions:
Claude Code skills →
Developer skills →
DevOps skills →
Architect skills →
If you are not using Claude Code and landed here anyway, the equivalent for Claude on the web is Custom Instructions.
KissMySkills is an independent marketplace and is not affiliated with, endorsed by, or connected to Anthropic, OpenAI, or any other AI company. Claude Code is a product of Anthropic.