Skills, commands, hooks and subagents

In module 12 you taught Claude Code your project with a CLAUDE.md, and in module 13 you learned to plan, grant permissions and work with Git. After a few sessions you will have noticed two things: you keep repeating the same instructions ("check there are no em dashes left", "run the tests before you finish"), and some rules, however clearly you write them, are not always followed.

This module covers the pieces Claude Code gives you for that: skills (and slash commands, which are now the same thing), hooks and subagents, plus plugins for packaging them. What matters is not the list of files but the rule for deciding which one to reach for. Everything is checked against the official Claude Code documentation as of October 2026.

When do I use CLAUDE.md, a skill, a hook or a subagent?

The four tools answer four different questions about an instruction. The decision rule:

1. 1It is something you want Claude to keep in mind at all times (how the project is organized, the tone you use, what not to touch): it goes in the CLAUDE.md from module 12. That is context read at the start of every session; the model considers it, but uses judgment.
2. 2It is a repeatable procedure (publishing an article, reviewing a pull request, preparing the monthly invoice): it becomes a skill. It loads only when needed, and you can run it with a slash command.
3. 3It is a rule that can never fail (format every edited file, never touch the passwords file): it becomes a hook. Not an instruction to the model but a command Claude Code runs, no matter what.
4. 4It is a self-contained task that needs its own context or its own tools (researching a large folder, reviewing code, writing one piece in parallel): it becomes a subagent.
5. 5It is a bundle of the above that you want to share with your team or across projects: it gets packaged as a plugin.

In the course’s mental model: CLAUDE.md is the new hire’s onboarding manual; a skill, a written procedure; a hook, the lock on the door; a subagent, the specialist colleague you hand an assignment to.

What is a skill and how do I write one?

At its simplest, a skill is a single file called SKILL.md inside a folder named after the skill. It has two parts: a short header (in YAML format, between two lines of three hyphens) with the name and a description of what it does and when to use it, and below that the instructions in plain text, as you would write them for a colleague.

Where you save it decides who sees it. At .claude/skills/skill-name/SKILL.md inside the project, anyone working in that repository gets it (commit it so your team receives it). Under ~/.claude/skills/ on your computer, you have it in every project.

There are two ways to trigger one. Automatic: Claude Code keeps the name and description of every available skill in context at all times, and when a task matches it loads the full content. Manual: you type /skill-name in the terminal, with arguments if it takes them (inside the skill text, $ARGUMENTS is replaced by whatever you typed after the name). That is why the description deserves the most care: it is all the model reads to decide whether the skill applies.

An example: a "publish-article" skill for the blog. Description: "Pre-publish checklist for a blog article; use it when a draft is ready to go out". Instructions: 1) confirm both versions exist, Spanish and English, and that the English is not a literal translation; 2) open every listed source and confirm it says what the text claims; 3) search for em dashes, filler and figures without a source; 4) run the site’s tests; 5) return a report of what was fixed and what still needs human review. A procedure you used to repeat from memory, written down once.

Four header details:

• disable-model-invocation: true means only you can invoke it; useful for actions with consequences, such as deploying.
• allowed-tools pre-approves tools for the turn in which the skill runs, so it does not ask permission at every step.
• context: fork runs the skill in a subagent, with its own context; you will see in a moment why that matters.
• The folder can hold supporting files (a template, a script, a long reference) that load only when needed. The docs advise keeping SKILL.md under 500 lines.

What about slash commands? Until recently there were two mechanisms: skills, and "custom commands" in the .claude/commands/ folder. As of October 2026, the documentation says custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create the same /deploy and work the same way. Old files keep working, but for new work the docs recommend a skill. Claude Code’s built-in commands (/help, /init, /compact, /hooks, /agents, /plugin) remain separate: you do not write those.

What is a hook, and why does it beat "please remember"?

A hook is a terminal command that Claude Code runs on its own at a fixed point in its lifecycle. The documentation’s word for it is deterministic: certain actions always happen, instead of depending on the model choosing to do them. The moments (events) have names: SessionStart when a session begins, PreToolUse before the agent uses a tool (and it can block it), PostToolUse after a tool call succeeds, Stop when Claude finishes responding, among others.

They are configured in a settings file: .claude/settings.json in the project (shared through the repository), ~/.claude/settings.json on your computer (all your projects) or .claude/settings.local.json (personal, that project only). Each hook says which event it responds to, with what filter (for example, only the Edit and Write tools) and which command to run. /hooks lists everything configured.

Two examples from the documentation itself that fit any business:

• Format every edited file. A PostToolUse hook with an "Edit|Write" filter that takes the path of the file Claude just changed and runs the project’s formatter on it (Prettier, in the official example). Result: never again a commit with inconsistent formatting, and nobody had to ask.
• Block edits to protected files. A PreToolUse hook, also on Edit and Write, that runs a small script: if the path contains .env (where passwords and keys usually live), package-lock.json or the .git/ folder, the script writes a "Blocked" message and exits with code 2. That code tells Claude Code to block the action, and the message reaches the model so it adjusts its plan. In your business, the list might include the folder of signed contracts or the pricing file.

Why this beats a sentence in CLAUDE.md: CLAUDE.md is context. The model reads it and almost always respects it, but in a long session, with a full context window, "almost always" is not "always". A hook is not read or interpreted: it is executed. It is the difference between a "do not enter" sign and a locked door. The rule from module 9 (trust, but verify) turns into code here: the checks that cannot fail are not requested from the model; they are imposed on the process.

What is a subagent, and when is it worth it?

A subagent is a specialized assistant that the main agent delegates a task to. According to the documentation, each one runs in its own context window, with its own system prompt, specific tool access and independent permissions; optionally, with a different model (a fast, cheap one for searching, a more capable one for writing). When it finishes, it returns a summary to the main conversation, not everything it read.

It is defined in a Markdown file with a YAML header, like a skill, but in a different folder: .claude/agents/ in the project, or ~/.claude/agents/ for all your projects. Only two fields are required: name and description (again, what Claude uses to decide when to delegate). The most useful optional ones: tools, the tools it may use; model; permissionMode; and skills, the ones loaded into it at startup. Below the header goes the system prompt: who it is, what it does, what format it returns. The /agents command shows the ones you have.

Claude Code ships with a few built in, such as Explore (read-only, for searching a repository quickly) and Plan (research during plan mode). You can delegate three ways: letting Claude do it on its own when the task matches the description, asking in plain language ("use the reviewer subagent to look at the changes"), or @-mentioning it to guarantee it runs. It can work in the foreground (the conversation waits) or in the background, while you carry on with something else.

When they help, according to the docs:

• The task produces a lot of text you do not need in your context. Reading fifty files to answer one question: the subagent reads everything and hands you three paragraphs.
• You need to restrict tools or permissions. A reviewer that can only read will not "fix" anything on its own.
• The work is self-contained and can be summarized. Writing one piece (an article, a report, a course module) from a clear brief, while you do something else.

When they get in the way: when the task needs back-and-forth with you, when the phases share a lot of context, or when latency matters. A new subagent starts with an empty context: it has not seen your conversation or the files you already read, so Claude writes it a delegation message and it has to find its bearings again, spending its own tokens (which count against your plan’s limit). The rule: one subagent per task with a name, a clear input and a summarizable output; never one "just in case". Coordinating several at once, with cross-review, is the subject of module 18, on orchestration.

This is a task I keep repeating in Claude Code and I want to turn it into a skill:

[DESCRIBE THE TASK STEP BY STEP, AS YOU WOULD EXPLAIN IT TO A NEW COLLEAGUE]

Criteria for a job well done: [CRITERIA]
What it must never do: [LIMITS]

Create the folder .claude/skills/[SKILL-NAME]/ with a SKILL.md that has:
1. A YAML header with name and a one- or two-sentence description saying what it does and when to use it (Claude uses it to decide whether to load the skill).
2. The instructions as numbered steps, including the criteria and the limits.
3. At the end, the exact format in which it should deliver the result.

If the task has consequences (deploying, sending, deleting), add disable-model-invocation: true so only I can invoke it. Show me the file before creating it.

I want a Claude Code subagent for this task: [TASK].

Business context: [TWO OR THREE LINES]
Input it receives: [WHAT I WILL HAND IT]
Output I expect: [EXACT FORMAT OF THE RESULT]
What it must not do: [LIMITS, FOR EXAMPLE: NO EDITING FILES, NO INVENTED FIGURES]

Write the file .claude/agents/[NAME].md with:
- name and description (the description must say what it is for and what it is NOT for, because Claude uses it to decide when to delegate).
- tools: only the tools it needs; if it must not change anything, read and search only.
- model: propose one and explain why, outside the file.
- The system prompt: role, who it serves, voice or quality rules, facts discipline and the exact output format.

Explain in three lines when Claude will delegate to it on its own and how I invoke it myself.

These are the rules in my project that can never fail, even if the model forgets them:

[LIST OF RULES, FOR EXAMPLE: "no file in the contracts/ folder gets edited", "every edited file gets formatted", "no command that deletes folders is run"]

For each rule, tell me whether a hook is the right tool or whether a line in CLAUDE.md or a permission is enough, and why. For the ones that are hooks, propose the event (PreToolUse, PostToolUse, Stop or another), the tool filter and the command, in Claude Code’s .claude/settings.json format. Prefer short, readable scripts in .claude/hooks/ over long one-line commands.

Do not change anything yet: show me the configuration, explain what each line does and how to test each hook with a harmless change.

What is a plugin, and when do I need one?

A plugin is a folder of skills, subagents, hooks or MCP servers that Claude Code installs and loads as one unit, usually from a catalog called a marketplace, with the /plugin command. You only need one when you want to package several pieces for your team or for many projects; a standalone skill or hook works without a plugin. Two warnings from the docs: an enabled plugin takes up context in every session, even when you do not use it, and whatever it runs, it runs as you. Review it before you install it.

The next module closes Part 3: MCP, the cloud and agents that work while you sleep, where you connect Claude Code to your tools and schedule routines like the automations from module 8.