For a while, I kept a notes file of prompts. "When writing a migration, remember…", "When I ask for a LinkedIn post, follow these rules…", "Before touching this codebase, check…". Every few days I'd copy one into Claude Code, tweak it, and paste it in.

It worked, but it was me doing the remembering. The agent was smart; the process around it was a pile of sticky notes.

Custom skills replaced most of that file. A skill turns "the way I like this task done" into something the agent can find and follow on its own. If you do any task with an AI agent more than a couple of times a week, it's worth knowing how they work.

What a skill actually is

Strip away the name and a skill is surprisingly plain: a folder with a Markdown file of instructions, optionally with scripts, templates or reference files next to it. Anthropic introduced Agent Skills in October 2025, and in Claude Code they live in .claude/skills/ in a project, or in your home directory for skills you want everywhere.

The clever part is how they load. At the start of a session, the agent only sees each skill's name and a one-line description. When a task matches a description, it reads the full instructions. When the instructions mention a script or a reference file, it opens that only if needed.

That means you can have many skills without stuffing all of them into every conversation. It's the difference between giving a new hire a 300-page manual on day one and giving them a shelf of short manuals with clear labels on the spines.

Anatomy of a skill

Here's a small, generic example, a skill for drafting release notes:

---
name: release-notes
description: Draft release notes from merged pull requests since the
  last tag. Use when asked for release notes, a changelog or "what shipped".
---

# Release notes

1. Find the latest tag and list merged PRs since then.
2. Group them: Features, Fixes, Internal. Skip dependency bumps.
3. Write each line for users, not developers: what changed for them.
4. Flag anything that needs a migration or config change at the top.
5. Show me the draft. Never publish or tag anything yourself.

## Style
- One line per change, past tense, no PR numbers in the text.

Three things are doing the work here:

• The description is the trigger. It's what the agent reads to decide whether this skill applies. Say what it does and when to use it, in the words you'd actually type.
• Numbered steps. Agents follow a clear sequence much more reliably than a paragraph of good intentions.
• Explicit boundaries. "Never publish or tag anything yourself" is the kind of line you only think to write after you've thought about what could go wrong.

Two skills I use

A post-writing skill. I publish posts on LinkedIn regularly, and the routine has many small rules: facts about my work I'm allowed to use, things I never mention, a rotation of formats so it doesn't get repetitive, and an image for most posts. The skill holds all of that. It tells the agent to read a file of facts and rules first, look at recent posts to choose a different format and topic, write the post, generate the image with a script, and then look at the image to check nothing is cut off before handing it over. I still review and edit every post. The skill just makes sure the boring checks are never skipped.

A codebase knowledge-graph skill. This one builds a map of a codebase, its modules and how they connect, so the agent can answer "what's involved when X happens?" without exploring dozens of files first. I wrote about the idea in more detail earlier this year. As a skill, it's one command away whenever I start work in a large repository.

What they have in common: both are tasks I do often, both have rules I'd otherwise have to repeat, and both end with a verification step.

What makes a skill good

Write the rules you keep repeating

The best source material for a skill is your own corrections. Every time you tell the agent "no, not like that", that sentence belongs in a skill.

Let scripts do the deterministic parts

If a step has one right answer (rendering an image, running a linter, formatting a file), put it in a script the skill calls. Language models are great at judgement and wording; a script is better at doing the same thing identically every time.

End with a check

"Run the tests", "open the generated file and confirm it looks right", "re-read the output against the rules above". A skill that verifies its own work catches far more mistakes than one that stops at "done".

Keep it short

Long skills get followed loosely. If a skill grows, move details into separate reference files and point to them from the main instructions, so they're only read when relevant.

Skill, project instructions or sub-agent?

Claude Code gives you a few places to put knowledge, and they're easy to mix up:

Other tools have their own versions of the same ideas: Cursor has project rules, GitHub Copilot has custom instructions, and many tools read an AGENTS.md file. The names differ; the principle is the same. Write down how you work, once, where the agent can find it.

Start with one

Pick the task you repeat most: writing tests in your project's style, preparing a PR description, reviewing a migration, drafting release notes. Write ten lines of instructions, use it for a week, and add a line every time it gets something wrong. That's honestly the whole method.

If you've built a skill (or a rules file, or a prompt library), what's the task it handles? I'm always looking for repetitive work I haven't thought of automating yet.