Claude Code Skills: The Three I Wrote and Kept (2026 Field Log)

Quick Answer: Claude Code skills are folders holding a SKILL.md file, a bit of YAML frontmatter plus markdown instructions, that Claude loads on demand when your request matches the skill's description, or that you fire by hand with /skill-name. After a month of running them on a real repo in 2026, my honest verdict is that the value is not in the hundreds of community skills you can download. It is in the two or three you write for your own codebase. This is a field log of the ones I wrote and kept, the ones I deleted, and the rule I now use to decide whether something should be a skill at all.

I did the dumb thing first. I found a community list of 300-plus Claude Code skills, installed about 30 of them, and watched my / menu turn into a wall I could not read. A week later I deleted nearly all of them. What survived were three skills I wrote myself, for my own repo, plus a couple of the bundled ones that ship with Claude Code.

So this is not a "best skills to install" post. There are enough of those. This is the honest version: what a skill is actually good for once the novelty wears off.

What a skill actually is

A skill is a directory with a SKILL.md inside it. The file has two parts: YAML frontmatter that tells Claude when to use the skill, and a markdown body with the instructions Claude follows when it runs. The directory name becomes the command. Drop a folder at .claude/skills/release/SKILL.md and you get /release.

The part that took me a while to feel in my hands: the body loads only when the skill is used. The description is the piece that sits in context up front so Claude can decide whether to reach for it. The 40 lines of detail underneath cost almost nothing until the skill actually fires. That single fact changes how you should write them.

Skills live in three places. Personal skills at ~/.claude/skills//SKILL.md follow you across every project. Project skills at .claude/skills//SKILL.md live in the repo and ship to your teammates through git. Plugins can carry skills too. When names collide, personal overrides project, and any of them can override a bundled skill of the same name.

They also follow an open standard, Agent Skills, so the same SKILL.md format is meant to work in other agents too: Cursor , OpenAI Codex , and Gemini CLI . I only run them in Claude Code, so treat the cross-tool angle as a note, not a promise I tested.

The three I wrote and kept

None of these are clever. That is the point.

api-conventions, so new endpoints stop drifting. Every time I asked Claude to add an endpoint it reinvented my error shape and forgot the auth guard. That is not a knowledge gap, it is a procedure. So I moved it out of a bloated CLAUDE.md section into a small auto-invoked skill:

---
name: api-conventions
description: Rules for adding an HTTP endpoint in this repo. Use when the user adds, edits, or reviews a route, handler, or API endpoint.
---

The body is nine lines: the zod-validate-first rule, the { ok, data, error } envelope, the auth guard import, and where the integration test goes. Claude loads it on its own now because the description names the trigger.

db-migration, so I stop breaking prod schema at midnight. Same shape, tighter body: generate the migration, the naming convention, the backfill script location, and the one-line rollback note I always forget. Auto-invoked whenever I touch the schema.

release, the one I never let Claude run on its own. My deploy runbook. This one is different because I do not want the model deciding to ship. So I set disable-model-invocation: true, which means it only runs when I type /release:

---
name: release
description: Deploy checklist for this app
disable-model-invocation: true
allowed-tools: Read Bash
---

That flag is the feature I underused at first. Anything that touches production or money should be a skill you trigger by hand, never one the model can pick up because a description sounded relevant.

What I deleted

Almost everything from the big community skill libraries. Not because they are bad, but because most generic skills say things the base model already does. A skill named "write clean code" or "act like a senior engineer" is noise. It burns a slot in your / menu and adds a description to the always-loaded pile for no lift.

There is a well-shared Reddit take that Claude skills are "mostly a marketing trick." After a month I think that is half right, and the half it gets right is exactly the generic ones. A skill that repackages good-advice prose is a trick. A skill that encodes your repo's actual procedure is the opposite: it is the thing you were pasting into chat five times a week, finally written down once.

The rule I run now: skill, CLAUDE.md, or MCP

The docs gave me the cleanest line I have found for this: create a skill when a section of CLAUDE.md has grown into a procedure rather than a fact. I turned that into a three-way test.

• If it is a fact about the project (the stack, the conventions, the do-not-touch list), it stays in CLAUDE.md. Always in context, always true. I wrote up how I run that file agents-md-vs-claude-md-field-log-2026.
• If it is a procedure I repeat and it is specific to this repo, it becomes a skill. Loaded on demand, triggered by its description.
• If it needs a new capability Claude does not have, a database client, a browser, a real API, that is not a skill at all. That is an MCP server. I keep that list short on purpose mcp-servers-i-actually-run-claude-code-2026.

Skills are instructions using tools you already have. MCP servers hand Claude new tools. Confusing the two is how people end up with a skill that quietly does nothing because it is describing an integration that was never wired up.

Three failure modes nobody warns you about

A vague description means the skill never fires. The description is the only part loaded up front, so if it does not name the trigger, auto-invocation just misses it and you assume the skill is broken. Write it as "Use when the user does X." That one habit fixed most of my "why didn't it run" moments.

An over-broad description makes the wrong skill fire. I had two skills both claiming review territory, and Claude kept grabbing the wrong one. Narrow the descriptions so they do not overlap, or set disable-model-invocation: true on the one you would rather drive by hand.

Stuffing the skill into CLAUDE.md "to be safe." This defeats the whole design. The point of a skill is that the body is free until you use it. If you paste it into your always-loaded context, you pay the token tax every single session and lose the one advantage skills have over a plain instruction file.

Where I landed

Three skills. All project-scoped, all committed to the repo, all encoding something I was already repeating by hand. The download-30-and-see approach cost me an afternoon and taught me nothing except which slots to free up. The two hours I spent writing my own three earned back every day since.

If you are starting from zero, do not browse a marketplace. Open your CLAUDE.md, find the section that reads like a checklist instead of a fact, and move it into a SKILL.md. That is your first real skill, and it will be better than anything you could have installed.