How Claude Code Skills Work and How to Build Good Ones

The word "automation" is selling Claude Code skills short

Here is a position I will defend for the rest of this article: treating a Claude Code skill as an automation is the most common and most expensive mistake people make with them. It is technically true that a skill can run scripts, call APIs, create files, and delegate to sub agents. But if that is all you see, you will build a handful of clever shortcuts and miss the thing that actually changes a business. I am Madhuranjan Kumar, and I think a skill is better understood as captured judgment, a way to take the best version of a process that lives in one person's head and hand it to everyone, forever.

The automation framing quietly limits you. Automation says: I do this task a lot, let me make it push button. That is fine, and it saves time. But it treats the skill as a convenience for the person who already knows how to do the job well. The judgment framing says something more valuable: the reason our best work is inconsistent is that only one or two people know the right way to do it, and everyone else improvises. A skill fixes that specific problem. It is the difference between saving yourself ten minutes and making your whole team as good as your best operator.

A skill is an SOP that never forgets and keeps improving

Strip away the mechanics and a skill is a standard operating procedure written for an agent instead of a new hire. When you train a person, you hand them a document that explains how to do a task the right way, they read it, and they do the work. A skill is the same document, except the agent reads it every single time and never has an off day, never forgets a step, and never quietly drifts from the process because it was busy.

Mechanically it is unglamorous, and that is the point. A skill is a folder with a markdown file inside, usually at a path like .claude/skills/skill-name, and the file has two parts. At the top is a small block of front matter holding the name and a description of when to use the skill. Below that are the step by step instructions the agent follows once it decides this is the right skill for the job. That is genuinely it. A useful skill can be a fifty line file. The barrier to entry is not technical skill, it is the willingness to write down how you actually do something.

The supporting cast is where the detail lives. When a task needs a specific tone of voice, a style guide, a checklist, or a data file, that material goes into separate reference files, and the markdown simply points to the right path. The skill file stays the lean brain, and the references are tools it pulls in only when a task calls for them. This layering is not decoration. It is what lets the skill stay readable while still carrying deep, accurate detail.

Why the "leverage" everyone talks about is really a people problem

The word people reach for when they get excited about skills is leverage, and it is the right word for the wrong reason. Yes, one person can fire off several jobs at once and have them run in parallel because each skill carries its own context. But the leverage that matters is organizational, not personal. One person works out the best way to do a task, encodes it, and now the entire team runs that exact process. The group gets better all at once, which is the only kind of improvement that actually compounds into growth.

This is why I push back on the automation view so hard. If you build skills only for yourself, you have made yourself faster. Useful, but bounded. If you build skills as a way to distribute your best thinking, you have changed what your whole team is capable of, and you have done it without hiring, training, or hoping people remember the good process under pressure. The productivity graph most people imagine for skills, quality climbing from good on the first run to excellent by the thirtieth, is real, but the important axis is not one person's speed. It is how many people now clear that bar.

The contrarian catch: your first skill will be mediocre, and that is correct

Here is the part that trips up people who expect automation to mean instant reliability. You will not write a good skill on the first try, and if you demand that you will quit before the payoff. A skill is built through a feedback loop, not a single act of authorship. You do a task with the agent, notice you do it often, and say let us turn this into a skill. Then you invoke it, watch it work, tell it what to fix, and run it again. The first couple of runs feel generic. By the twentieth, the skill is sharp enough that you can walk away for ten minutes and come back to finished work.

People who treat skills as automations expect run one to be perfect and get discouraged when it is not. People who treat skills as captured judgment expect run one to be a rough draft of a process, and they invest the ten or twenty rounds of correction that make it genuinely good. That mindset difference is the whole game. The value is not in the first version. It is in the fact that every correction is permanent, so the skill only ever gets better, unlike a human who needs the same feedback repeated.

A worked example: turning a law firm's intake into a skill

Let me ground this in one business. Picture a small law firm that drafts the same kinds of documents over and over: engagement letters, intake summaries, and document request lists. The partners are excellent at this, but the quality of a first draft depends entirely on which paralegal happens to prepare it. That inconsistency is a judgment problem, which is exactly what a skill solves.

Here is how I would set this up for that client. I would build an intake summary skill whose markdown describes the steps in plain language: read the new client questionnaire, pull the firm's standard clauses from a reference file, summarize the matter in the firm's own structure, and flag any missing information a paralegal needs to chase before the file moves forward. The firm's tone, its standard language, and its templates live in reference files the skill points to, so the brain of the skill stays small while the detail stays accurate and on brand.

Because a skill can run scripts and delegate, a heavier step like searching the firm's matter management system can be handed to a sub agent, keeping the main skill fast and stopping it from blowing its context window on a side quest. The first few intake summaries get reviewed line by line, and the skill is corrected each time. After a handful of rounds, every new client produces a clean, consistent summary in minutes, in the firm's voice, and any associate can trigger it with one command instead of starting from a blank page. The senior lawyer's judgment, once trapped in their head, now ships with every intake.

That same captured process pays off well beyond the legal work itself. The structured client summaries the skill produces feed cleanly into the firm's CRM and website stack, so follow up and matter tracking stop depending on someone remembering to log the details. The consistency also shows up in client facing content, because the firm's voice, once written down as a reference file, can guide the drafts that support its SEO and organic search presence without a separate effort.

How progressive loading keeps the whole approach cheap

One objection to building dozens of skills is cost: surely loading all that instruction into every request gets expensive. It does not, and understanding why removes the last excuse not to start. Skills use progressive context loading in three levels. At level one, the agent scans only the name and description across all your skills, which is tiny. At level two, once it picks the right skill, it reads the full markdown file. At level three, it loads extra reference files or scripts only when the specific request actually needs them.

That layering is why you can have a whole library of skills without burning your context window on every question. You are not paying for knowledge you are not using. It also reinforces the judgment framing: the description at level one is you telling the agent when this captured process applies, the markdown at level two is the process itself, and the references at level three are the deep detail. Each layer earns its place only when it is needed.

The trap of building skills for tasks that are not actually stable

There is a failure mode that the automation framing walks people straight into, and it is worth naming so you avoid it. Not every repeated task deserves a skill. If a process is still changing every week, encoding it too early just means you spend your time rewriting the skill instead of doing the work, and you get the worst of both worlds. The tasks that reward a skill are the ones that are both frequent and stable, where the right way to do them has settled and only the inputs change. A monthly client report, a standard intake, a recurring content format: these are stable enough that captured judgment pays off. A brand new experiment you are still figuring out is not.

This is another place where the judgment lens beats the automation lens. Someone thinking only about automation asks what can I make push button, and they build skills for everything they touch, including the volatile stuff, then wonder why maintenance eats the savings. Someone thinking about captured judgment asks a sharper question, which is where do we already know the right way to do this and just fail to do it consistently. That question naturally points you at the stable, high value processes and steers you away from premature ones. Pick those, and the twenty rounds of feedback you invest keep paying off for months because the underlying task is not moving under your feet.

Build skills like you are training your best hire

If you take one thing from my contrarian take, let it be this: stop asking what tasks you can automate and start asking what your best people know that nobody else does. That is where the valuable skills are. Follow a simple frame when you write one. Give it a name and a clear trigger, a one sentence goal, the step by step process, the reference files it needs, the rules and guardrails, and a habit of self improvement. Pick one thing you repeat, do it once with the agent, then ask it to turn that into a skill and to question you until it has everything. Keep the markdown focused and push heavy detail into reference files. If a skill should follow you everywhere, install it globally in your home directory so every project can use it, which is ideal for company context and tone you always want present.

One more habit separates people who build a couple of skills from people who build a real library. Keep a running note of the moments you catch yourself repeating an instruction, because those moments are your best backlog. Every time you find yourself explaining the same process to the agent for the third time, that is a signal that a skill is waiting to be written, and the explanation you just gave is most of its first draft. Treated this way, your skill library grows out of your actual work rather than out of a planning session, which is why the good ones feel so precise: they were captured at the exact moment the need was obvious.

You can build solid skills yourself with patience and a few feedback rounds. If you would rather have the structure, the reference files, and the guardrails set up correctly the first time so the output is reliable in front of clients, that is the kind of work an expert can wire up cleanly for you.