Agent skills are the reusable unit I was missing

The difference isn't the words — a skill is still just instructions. The difference is that a skill has a name, a home, and a contract. I invoke it by name; its instructions load into the turn; and it behaves the same way today as it did last month, because it's a file I version, not a sentence I improvise.

Once a workflow has a name, it stops being knowledge trapped in my head and becomes something the system owns. That is the whole move: the proven procedure goes from "the thing I remember to type" to "the thing the machine already knows how to do." It's the same reason I write down what an agent should carry between sessions instead of re-briefing it each time — durable capability beats a memory I keep re-supplying.

The second time I wrote out the same procedure for an agent was the signal it wanted to be a skill — the same instinct that tells you a copied function wants to be a library.

Mechanically, a skill is simple. It's invoked by name — a slash command I type, or auto-selected when the task matches. Its instructions load into the current turn and steer the work in place of my default approach. And it can run two ways: inline, where the instructions guide the agent I'm already talking to, or in a subagent that goes off, does the whole job, and hands back a finished result.

That second mode is the one that changed my leverage. A skill isn't only a script I read — it can be a unit of work I dispatch. "Run the SEO audit" isn't me walking an agent through twenty steps; it's a name that resolves to an agent that returns the audit. That is the seam that lets one operator run a fleet instead of a single assistant: work fans out to named jobs, and I read results instead of narrating steps.

A skill on disk is a small folder with a Markdown file at its root and a metadata header at the top. The header is where the intelligence lives. It carries the name I invoke, a description that doubles as the trigger, and — the part I underrated for months — an explicit list of the tools the skill is allowed to touch.

---
name: deploy-to-production
description: |
  Use when shipping a built change to prod — build, unblock the
  gate, purge caches, verify a real request. Skip when the change
  is docs-only or not yet merged.
allowed-tools:
  - Bash
  - Read
  - Edit
---
# then the steps, in plain Markdown

The reason for the split is cost. Only the header is always in context — dozens of one-line descriptions the agent scans to decide what's relevant. The body loads only when the skill is chosen. So a hundred skills cost a hundred short sentences of attention, not a hundred full procedures — which lets the library grow without drowning every prompt in instructions it doesn't need this turn.

Most of what I learned is about restraint. A skill that tries to do three things fires at the wrong time and does none of them well. The three properties I hold every skill to:

Here's the shape of the part that does the deciding — the metadata that tells an agent whether this skill is even the right tool before it reads a single step:

# the part that earns its keep is the trigger, not the steps
name: deploy-to-production
description: Use when shipping a built change to prod —
  build, unblock the gate, purge caches, verify a real request.
  Skip when the change is docs-only or not yet merged.

Once the pattern clicked I stopped writing one-off procedures almost entirely. The skills I lean on cluster into a few kinds: audits (SEO health, content quality, a security pass), operations (deploy helpers, dependency checks, branch hygiene), content (a structured code review, a coverage sweep), and interaction (a click-through decision form, a question round-trip to my phone when an agent needs a call it can't make alone).

Some of these are barely a paragraph long and still worth naming. My global instruction to write in Simplified Technical English is, in effect, a tiny always-on skill: one rule, applied the same way in every repo, so I never re-explain the house style. The heavier ones — an adversarial plan review, a portfolio-wide indexing assessment — are hundreds of lines that fan out multiple agents. The same packaging serves a one-line convention and a multi-agent workflow.

The same idea shows up wherever agents do real work — Claude Code has skills; the broader "agent skills" pattern is the same shape under a different roof. The portability is part of the point: a well-drawn skill is a description of a job, not a binding to one tool.

The skills that changed how much I can run in a day are the ones that don't just guide a turn — they launch a whole crew. My plan-review skill grounds itself in my own catalogued past mistakes, fans out a panel of adversarial agents, and returns a ranked risk list with a go / no-go verdict. My indexing assessment spreads diagnosis agents across the portfolio and collapses their findings into one leverage-ranked plan. Each is one name I invoke; behind it is a small workforce.

The thing that makes me willing to point those at real projects is a rule baked into every one of them: they propose, they don't mutate. The audit writes a report and queues an approval; it never submits the sitemap, purges the cache, or edits the content on its own. The heavier and more autonomous a skill is, the harder its default leans toward read-only — because a dispatched agent I'm not watching should never be one that can do something I can't cleanly undo.

That restraint is what turns "autonomous" from a scary word into a boring one. A skill that only ever proposes can run unattended, because the worst case is a report I ignore, not a change I have to chase down. The irreversible move stays behind a human gate; everything up to it runs at machine speed.

The real payoff isn't that I type less. It's that a skill is written once and reused by every agent I run. When I improve the deploy skill, every future deploy — by me or by any agent in the fleet — gets the improvement. The knowledge stops living in one head or one session and becomes a shared capability, the way a good tool outlives the person who first sharpened it.

That's why skills sit underneath the rest of how I operate. Dispatching work to a fleet of agents only scales because the agents share a library of named, tested procedures instead of each relearning the job. Skills are the vocabulary the fleet speaks, and every one I add is a word all of them can suddenly use.

The reframe that took me too long: an agent's real power isn't a clever one-off prompt — it's the accumulated library of jobs it already knows how to do well. Every time I package a workflow I use twice, the system gets permanently more capable, and I get to stop being the place that knowledge lives. Prompts got me answers. Skills gave me infrastructure.