Choose between a skill, a slash command, and a subagent

You’ve now built a procedure the agent runs by itself. But “package some work and reuse it” describes three different tools in Claude Code, and reaching for the wrong one is a common way to fight the grain. This lesson is the decision: when the finish-pr ritual is genuinely a skill, and when the next thing you want to package is really a slash command or a subagent instead.

The same file, two ways to fire

Start with the one that trips people up, because in Claude Code a skill and a custom slash command are now the same underlying thing. Custom commands were merged into skills — a file at .claude/commands/finish-pr.md and a skill at .claude/skills/finish-pr/SKILL.md both create /finish-pr and run the same way. The skills page documents the merge.

So the distinction isn’t two formats — it’s two ways the same thing can fire:

• As a skill — the agent reads the description, recognizes the situation, and invokes it itself. That’s what we built: you say “this is ready” and the ritual runs.
• As a command — you type /finish-pr and it runs because you said so, full stop. The agent never decides.

Every skill can be invoked by hand with its /name; that’s the command behavior, always available as a fallback. The real choice is whether you also want the agent to fire it on its own. You make a skill command-only by adding one frontmatter flag — disable-model-invocation: true — which takes it off the agent’s automatic menu. The decision rule:

• Let the agent invoke it when running it at the wrong moment is harmless — checks, summaries, lookups, regenerating something. Our finish-pr qualifies: worst case the agent runs four read-mostly checks a beat early.
• Make it command-only when running it at the wrong moment is expensive or irreversible — anything that deploys, pushes, sends a message, or spends money. You don’t want the agent deciding your code “looks ready” and shipping it.

If finish-pr ended in git push and opened the PR, you’d flip it to command-only — the checks can fire on recognition, but the act of shipping should wait for you to type the command.

When the job wants a subagent instead

The third tool is the one from the last chapter, and it answers a different question entirely. A skill or command is a procedure — a fixed set of steps you want run. A subagent is a context — an isolated window where the agent does open-ended work without polluting your main thread.

The tell is whether the work is a known routine or an open investigation:

• Known routine → skill/command. The four wrap-up steps never change. You’re not asking the agent to figure out what to do; you’re handing it a script. That’s a skill.
• Open investigation → subagent. “Trace every place the charge amount gets mutated and report back” has no fixed steps, generates a pile of intermediate reading you don’t want in your main context, and ends in a summary. That’s a subagent.

The two aren’t rivals — they compose. A skill can be told to run in a forked context, so a heavy procedure does its noisy work in isolation and returns only a summary, exactly the way a subagent does. That’s a skill borrowing the subagent’s context isolation; the mechanics are on the skills page. The point isn’t to memorize the overlap — it’s to start from the right question.

The three-way test

When you’re about to package something, ask in this order:

1. Is it a fixed procedure, or open-ended work? Open-ended, context-heavy, ends in a report → subagent. A fixed set of steps → skill, and read on.
2. Should the agent run it on its own, or only when I say so? Harmless if mistimed → skill (model-invoked, fires on recognition). Expensive or irreversible → command-only (disable-model-invocation: true).
3. Is it actually a fact, not an action at all? “Always format money as cents,” “our API returns errors in this shape” — that’s not a procedure the agent runs, it’s context it should hold. That belongs in rules, not a skill.

That third one is the quiet mistake: cramming a standing fact into a skill body, where it only loads when the skill fires, instead of into the rules file where it’s always in view. Rules are what the agent knows; skills are what it does; subagents are where it does the heavy stuff. Keep those three straight and you’ll almost always reach for the right one.

Where this leads

Skills close a real gap: the agent now owns the procedures you used to narrate, firing them when the situation calls. But a skill can only orchestrate what the agent can already reach — your files, your shell, the commands on your machine. The moment the ritual needs to touch a system outside the repo — file a ticket, query the production database, post to a channel — or needs a check that runs every time, deterministically, no matter what the agent decides, you’ve reached the edge of what a skill alone can do.

That’s the next chapter. Extending Claude Code gives the agent reach into external systems with MCP servers, deterministic gates that fire on their own with hooks, and a way to ship a whole setup — skills, rules, servers, and gates together — as one installable unit with plugins. Skills taught the agent your procedures; next you give it new things to do them to.