What you will be able to do
- Pick the right extension mechanism for a repeatable team workflow: CLAUDE.md, a rules file, a skill or slash command, a subagent, a hook, or a plugin
- Write a skill whose description makes Claude load it, and decide when to turn off model invocation
- Define a subagent with a restricted tool list to keep noisy or risky work out of the main conversation
- Turn a rule that must always hold into a hook instead of an instruction
- Package skills, agents and hooks as a plugin with a .claude-plugin/plugin.json manifest and choose an install scope
Key concept
Match the mechanism to how the workflow must run — Each extension point differs in when it loads, whose context it uses, and whether Claude decides to use it. Choose by asking whether the workflow is always-on context, on-demand knowledge, isolated work, or something that must happen every time without Claude choosing. Then package it once it needs to reach another repository.
1.Reading a workflow for the mechanism it needs
Every Claude Code extension answers the same question in a different way: when does this content or action enter the session, and who decides that it does? CLAUDE.md is loaded into every conversation. A skill loads when it is invoked or when it matches the task. A subagent runs in a context window of its own. A hook fires on a lifecycle event whether or not Claude has thought about it. If you pick the wrong one, the workflow either fills up context it never uses or depends on Claude remembering something it is free to skip.
The quickest way to decide is to look at the pain the team keeps hitting, not at the features. Each recurring friction maps to one mechanism:
| What keeps happening | Add |
|---|---|
| Claude gets a convention or command wrong twice | A line in CLAUDE.md |
| You keep typing the same prompt to start a task | A user-invocable skill (a /name command) |
| You paste the same playbook or multi-step procedure into chat for the third time | A skill |
| A side task floods the conversation with output nobody will reference again | A subagent |
| You want something to happen every time without asking | A hook |
| A second repository needs the same setup | A plugin |
Always-on guidance comes in two sizes. CLAUDE.md holds core conventions and build commands for the whole project. Files in .claude/rules/ also load every session, or only when matching files are opened. Their paths frontmatter scopes them to file paths, so they suit language-specific or directory-specific guidelines, such as a set of rules that only matters under a frontend directory. Both kinds are paid for on every request, so long reference material belongs in a skill, which loads on demand. CLAUDE.md files are additive: every level contributes to context at the same time. Skills and subagents are different. When the same name exists at more than one level, one definition overrides the others.
Checkpoint 1 of 9· Match them up
Your team keeps running into each of these problems. Match each one to the extension mechanism it calls for.
Tap a term, then the definition that fits it.
Each mechanism is chosen by when it enters the session and who decides. CLAUDE.md is always loaded. A skill loads on demand. A subagent keeps noisy work in its own context window. A hook fires on its event without Claude choosing to run it. A plugin packages the setup so another repository can use it.
“A side task floods your conversation with output you won’t reference again | Route it through a subagent”Source: code.claude.com
Sources1
2.Skills and slash commands: reusable instructions Claude can find
A skill is a folder holding a SKILL.md file, plus any supporting scripts or reference files. The folder name becomes the slash command. Project skills live in .claude/skills/<skill-name>/SKILL.md, and you commit that folder so the whole team gets them. Personal skills live in ~/.claude/skills/ and follow you across projects on one machine. The older format, a single Markdown file in .claude/commands/, still works. A skill is the better choice for new work because it can carry supporting files. To convert a command, move .claude/commands/deploy.md to .claude/skills/deploy/SKILL.md, and /deploy still works.
---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---
# Codebase Visualizer
Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.
## Usage
Run the visualization script from your project root:
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```Write the description for the moment Claude chooses a skill. At session start only skill descriptions are in context, and the full content loads when the skill is used. A body Claude never sees cannot help it choose. A description that says what the skill does and when to use it, in the words developers actually type, is what gets the skill loaded. Put the main use case first, because the combined description and when_to_use text is truncated at 1,536 characters in the skill listing. If a skill still isn't triggering, check that the description includes keywords users would naturally say, then try invoking it directly with /skill-name.
Some workflows should never start on Claude's judgment. A deploy is the classic case. Setting disable-model-invocation: true stops Claude from loading the skill automatically, so it runs only when someone types /name. It also stops the skill from being preloaded into subagents. The flag gives a skill no priority. It takes the skill out of Claude's automatic choice altogether.
After invocation, the skill's content is added to the conversation once and not re-read on later turns. Two authoring habits follow. Word judgment calls so they cover the whole task: write "Run the tests after every edit" rather than "Run the tests". And put the most important instructions near the top, because after compaction Claude Code may keep only the start of an invoked skill.
Checkpoint 2 of 9· Check yourself
A developer says "I think this branch is ready to ship", and Claude starts the team's /deploy skill without being asked. The team wants deploys to start only when someone types /deploy. What should they change?
disable-model-invocation: true removes the skill from Claude's automatic choice, so it runs only when someone types /name. A line in the body cannot help, because Claude sees only the description until the skill loads. Moving the skill to the personal folder or converting it to a command file does not stop Claude from invoking it.
“Stop Claude from invoking a command on its own: add disable-model-invocation: true to the command file’s frontmatter”Source: code.claude.com
Checkpoint 3 of 9· Exam question
A skill that explains the company's API error format never gets used, even when developers ask about those errors. The body is excellent. Which change most likely fixes it?
Correct answer: D — Rewrite the frontmatter description to state what the skill does and when to use it, using the terms developers actually type.
- A. Incorrect: disabling model invocation prevents Claude from loading the skill by itself and removes its description from context, making the problem worse.
- B. Incorrect: descriptions are truncated in the listing and the body is meant to load on demand; stuffing the body into the description wastes context and still truncates.
- C. Incorrect: forking changes where the skill runs, not whether Claude matches it; the description still drives selection.
- D. Correct: Claude decides whether to load a skill from its description, which is always in context, so a vague description means the body is never reached.
Sources2
3.Subagents: isolated workers that return a summary
A subagent is the right choice when the work matters but its by-product doesn't. Take an integration suite that prints thousands of log lines when the team only needs pass/fail and the failing test names. Run it inside a skill and the full log lands in the main window, because a skill's content and the work it drives add to the main conversation. A subagent uses a separate window with its own input and output tokens. Only its summary returns to the conversation that spawned it. A CLAUDE.md line asking Claude to ignore long output does not stop that output from entering context. And no hook event clears earlier tool output from the transcript.
---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.The tools field also makes a subagent the place to enforce limits. A subagent that lists only Read, Grep, Glob has no edit tools, whatever its prompt says. Leave tools out and it inherits every tool available to subagents. disallowedTools removes tools from that inherited list. A skill is a different kind of thing: it is instructions Claude reads and interprets, so a reviewer that must be unable to modify files belongs in a subagent with a restricted tool list. The description does the same job as a skill's: it tells Claude when to delegate.
| Location | Scope |
|---|---|
| Managed settings | Organization-wide |
| --agents CLI flag | Current session |
| .claude/agents/ | Current project |
| ~/.claude/agents/ | All your projects |
| Plugin's agents/ directory | Where the plugin is enabled |
Skills and subagents also combine well. A skill can spawn subagents for parallel work. For example, an /audit skill can start security, performance and style subagents, each working in isolated context. A subagent's skills field does the reverse: it preloads the full content of named skills into the subagent at startup.
Checkpoint 4 of 9· Check yourself
Which setup keeps an integration suite's thousands of log lines out of the main conversation while still giving the team pass/fail and the names of failing tests?
A subagent works in its own context window, and only its summary comes back to the main conversation. A skill's work adds to the main window. A CLAUDE.md line does not keep output out of context, and no hook event removes earlier tool output from the transcript.
“Context isolation. Work happens separately, only summary returns”Source: code.claude.com
Checkpoint 5 of 9· Fill the gap
This reviewer must be unable to edit files, whatever its prompt says. Which frontmatter field makes it read-only?
---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
? : Read, Grep, Glob
model: sonnet
---
You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.The subagent's tools field lists the only tools it can use, so listing just Read, Grep and Glob leaves it with no edit tools. Putting those same three names in disallowedTools would deny them instead. allowed-tools comes from skill frontmatter, and skills preloads skill content into the subagent.
Source: code.claude.comCheckpoint 6 of 9· Exam question
Engineers complain that running the full integration suite floods the main conversation with thousands of log lines. They only need pass/fail and the failing test names. Which mechanism fits best?
Correct answer: B — A subagent that runs the suite in its own context window and returns only a short summary of failures to the main conversation.
- A. Incorrect: a skill runs in the main conversation's context, so the same log volume would still land there.
- B. Correct: a subagent has a separate context window and only its final summary returns, which keeps verbose output out of the main conversation.
- C. Incorrect: a CLAUDE.md instruction cannot stop the tool output from being added to context; Claude has already received the lines when it reads the rule.
- D. Incorrect: a SessionStart hook fires once when a session begins and cannot prune tool output produced later during test runs.
4.Hooks: rules that must hold every time
Use a hook when the rule cannot depend on Claude remembering it. A skill can say "never edit the lockfile", but Claude interprets the instructions and the outcome can vary. A hook fires on its lifecycle event without Claude deciding. When Claude skips a rule that must hold every time, move the rule into a hook. If the rule belongs with a particular skill, define the hook in that skill's hooks frontmatter. It then applies from the moment the skill is invoked until the session ends.
Pick the event by when the guarantee has to apply:
PreToolUsefires before a tool call executes and can block it, which suits protecting files or refusing unsafe commands.PostToolUsefires after a tool call succeeds, which suits formatting or linting every edited file.SessionStartfires when a session begins or resumes. With thecompactmatcher it can re-inject reminders after compaction.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}Hooks combine differently from skills and subagents. Those override by name, but hooks merge: every registered hook fires for its matching event regardless of where it was defined. A project hook therefore cannot quietly replace a user-level one. Both run. A hook costs no context unless it returns output, which makes it a cheap way to add logging, notifications or formatting to every session.
Checkpoint 7 of 9· Fill the gap
The team's protect-files.sh script has to stop Claude from editing the lockfile, and the edit must be refused before it is applied, not cleaned up afterwards. Which event should this hook be registered under?
{
"hooks": {
" ? ": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}PreToolUse fires before a tool call executes and can block it, so the script can refuse the Edit or Write before it changes the lockfile. PostToolUse fires only after the edit has succeeded, so it suits formatting rather than protection. SessionStart fires when a session begins or resumes, not on each edit.
Source: code.claude.com5.Packaging a workflow as a plugin
A plugin is how a setup that works in one repository reaches the next one. It bundles skills, subagent definitions, hooks and MCP servers into one installable unit. The plugin's components sit under the plugin root as skills/, agents/, hooks/hooks.json and .mcp.json. The manifest that names the plugin lives in its own directory, .claude-plugin/plugin.json.
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}name is the only required field, and it does more than label the plugin. It becomes the prefix on every skill and agent the plugin provides, so a hello skill is invoked as /my-first-plugin:hello. Two plugins can each ship a hello without colliding. version is optional. Setting it keeps users on that version until you change it, so bump it when you release. An existing personal or project skill folder can become a plugin too: add a .claude-plugin/plugin.json to it.
A plugin is distributed through a marketplace, and the install scope decides who gets it:
- User scope enables it for you in every project on the computer.
- Project scope enables it for everyone working in the repository through the committed
.claude/settings.json. Each collaborator still installs it on their own machine. - Local scope enables it for you in this repository only.
Packaging has two costs authors tend to miss. First, the name and description of every skill and agent Claude can invoke on its own sit in context on every turn, even in sessions where nothing from the plugin runs. A plugin with many model-invocable skills is never free. Second, a plugin subagent loses some frontmatter: permissionMode, hooks and mcpServers are ignored for plugin subagents. A guarantee you need has to go in the plugin's own hooks/hooks.json, not in an agent file. Whatever a plugin runs, it runs as you.
Checkpoint 8 of 9· Match them up
A plugin is ready in the team marketplace. Match each install scope to the situation it fits.
Tap a term, then the definition that fits it.
The install scope decides who gets the plugin. User scope covers you in every project on the computer. Project scope turns it on for the whole repository through the committed .claude/settings.json, and each person still installs it themselves. Local scope covers only you, only in this repository.
“Project scope: enabled for everyone who works in this repository, through the committed .claude/settings.json”Source: code.claude.com
Checkpoint 9 of 9· Exam question
At which path does a Claude Code plugin keep the manifest that gives it a name and version?
Correct answer: A — .claude-plugin/plugin.json at the plugin's root directory
- A. Correct: the manifest is a JSON file at .claude-plugin/plugin.json in the plugin root, with components in sibling directories such as skills and agents.
- B. Incorrect: the skills directory holds SKILL.md folders, not the plugin manifest, and the manifest is JSON rather than YAML.
- C. Incorrect: the hooks file declares hooks only; the plugin's name and version live in the manifest.
- D. Incorrect: user settings records which plugins are enabled, but does not define a plugin's own identity.
Sources
(7)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/features-overviewOfficial docs
“You want something to happen every time without asking”
↩︎ Reading a workflow for the mechanism it needs“Every session, or when matching files are opened”
↩︎ Reading a workflow for the mechanism it needs“CLAUDE.md files are additive: all levels contribute content to Claude’s context simultaneously.”
↩︎ Reading a workflow for the mechanism it needs“Zero, unless hook returns additional context”
↩︎ Reading a workflow for the mechanism it needs“Context isolation. Work happens separately, only summary returns”
↩︎ Subagents: isolated workers that return a summary“/audit skill kicks off security, performance, and style subagents that work in isolated context”
↩︎ Subagents: isolated workers that return a summary“Fires on its event without Claude deciding”
↩︎ Hooks: rules that must hold every time“Hooks merge: all registered hooks fire for their matching events regardless of source.”
↩︎ Hooks: rules that must hold every time“Determinism | Fires on its event without Claude deciding | Claude interprets the instructions; outcome can vary”
↩︎ Key concept“Context window impact | Adds to your main window | Uses a separate window with its own input and output tokens”
↩︎ Exam trap 3“A side task floods your conversation with output you won’t reference again | Route it through a subagent”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/skillsOfficial docs
“Prefer a skill for new work, since skills also support supporting files.”
↩︎ Skills and slash commands: reusable instructions Claude can find“move .claude/commands/deploy.md to .claude/skills/deploy/SKILL.md. The folder name becomes the command, so you still type /deploy.”
↩︎ Skills and slash commands: reusable instructions Claude can find“Check the description includes keywords users would naturally say”
↩︎ Skills and slash commands: reusable instructions Claude can find“Claude Code can keep only the start of an invoked skill, so put the most important instructions near the top of SKILL.md.”
↩︎ Skills and slash commands: reusable instructions Claude can find“To keep the rule with the skill, define the hook in the skill’s hooks frontmatter.”
↩︎ Hooks: rules that must hold every time“Set to true to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with /name.”
↩︎ Exam trap 1“Claude skipped a rule that must hold every time: move the rule into a hook.”
↩︎ Exam trap 2“What the skill does and when to use it. Claude uses this to decide when to apply the skill.”
↩︎ Prediction“Stop Claude from invoking a command on its own: add disable-model-invocation: true to the command file’s frontmatter”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/sub-agentsOfficial docs
“Enforce constraints by limiting which tools a subagent can use”
↩︎ Subagents: isolated workers that return a summary“Inherits every tool available to subagents if omitted.”
↩︎ Subagents: isolated workers that return a summary“Lifecycle hooks scoped to this subagent. Ignored for plugin subagents”
↩︎ Exam trap 4 - 4.https://code.claude.com/docs/en/hooks-guideOfficial docs
“Before a tool call executes. Can block it”
↩︎ Hooks: rules that must hold every time - 5.https://code.claude.com/docs/en/plugins/createOfficial docs
“as skills/, agents/, hooks/hooks.json, and .mcp.json.”
↩︎ Packaging a workflow as a plugin“mkdir -p my-first-plugin/.claude-plugin”
↩︎ Packaging a workflow as a plugin“It identifies the plugin and becomes the prefix on every skill and agent the plugin provides.”
↩︎ Packaging a workflow as a plugin - 6.
“Setting it keeps users on that version until you change it”
↩︎ Packaging a workflow as a plugin - 7.https://code.claude.com/docs/en/pluginsOfficial docs
“Each collaborator still installs it on their own machine”
↩︎ Packaging a workflow as a plugin“Those tokens count toward your usage and leave less room in the context window even in sessions where nothing from the plugin runs.”
↩︎ Packaging a workflow as a plugin“Permissions: what the plugin runs, it runs as you.”
↩︎ Packaging a workflow as a plugin“Project scope: enabled for everyone who works in this repository, through the committed .claude/settings.json”
↩︎ Checkpoint