Claude Code Skills Deep Dive (10): Where Should a Capability Live?
TL;DR: Put stable, broadly applicable rules in CLAUDE.md or Rules; reusable knowledge and multi-step methods in Skills; actions that must run on a lifecycle event in hooks; atomic interfaces in tools; external-system cap
TL;DR: Put stable, broadly applicable rules in
CLAUDE.mdor Rules; reusable knowledge and multi-step methods in Skills; actions that must run on a lifecycle event in hooks; atomic interfaces in tools; external-system capabilities behind MCP; work requiring a separate context in subagents; and multiple extensions that must install together in a plugin. A Skill sits in the middle: it does not create a new execution primitive. It loads, on demand, the knowledge of how to combine existing capabilities to accomplish a class of work.
Part 9: From Personal Folders to Team Plugins covered distribution. We have now followed a Skill through its full lifecycle:
Folder format β metadata discovery β user/model invocation
β prompt rendering β inline/forked execution
β permissions, hooks, and sandbox β compaction
β project, plugin, or managed distribution
This final article adds no new mechanism. It answers a design question: when Claude lacks a capability, should you add a CLAUDE.md instruction, Skill, tool, hook, subagent, MCP server, or plugin?
Don't start by choosing a folder
Suppose a user says:
Before every release, run tests, inspect the changelog, confirm the version, summarize risks, and obtain my approval before publishing.
That request contains several kinds of concern:
- βThis project uses pnpmβ is a stable project fact.
- βCheck these things in this orderβ is a reusable workflow.
- βNever push to production without approvalβ is an enforcement requirement.
- βRead deployment statusβ is an external action.
- βAudit many filesβ may benefit from context isolation.
- βInstall this across the teamβ is distribution.
Putting the entire sentence into one Skill may appear to work, but mixes responsibilities. First ask whether each part is an always-on fact, on-demand method, atomic action, fixed trigger, independent worker, or packaging concern.
Decision 1: Should every relevant task know it?
Yes β CLAUDE.md or Rules. Good candidates include the package manager, build commands, project conventions, directory boundaries, naming or testing rules that apply to most work, and path-specific instructions.
βThis repository uses pnpm onlyβ
β CLAUDE.md
βChanges under migrations/** must remain backward-compatibleβ
β path-scoped Rule
These instructions are broadly present or loaded when the relevant path is touched. If they are irrelevant to 90% of tasks, keeping them always in context adds noise.
No β ask whether this is a reusable method. A release, review, incident, migration, or documentation workflow belongs in a Skill when needed only for that kind of task.
βWhen preparing a release, follow these eight checksβ
β Skill
Both mechanisms contain instructions. The important difference is frequency and load time: every task should know it β CLAUDE.md; a class of tasks should know it β Skill.
Decision 2: Is the missing piece βhowβ or βcanβ?
Missing method β Skill. It can package domain knowledge, checklists, multi-step workflows, judgment criteria, orchestration order, and navigation to references, scripts, or assets.
βHow should we review a database migration?β
β Skill
Missing action β tool. A tool exposes a model-callable interface to read a source, create a ticket, query a deployment, change an object, or run an operation with a stable input/output contract.
βQuery the current staging deployment versionβ
β tool
Together:
release-check Skill
1. Call deployment-status tool
2. Run test-related tools or Bash
3. Read the changelog
4. Decide whether release criteria are met
The Skill need not reimplement the tool; the tool need not understand the entire release policy. A tool exposes an affordance; a Skill organizes affordances.
Decision 3: Is the action local or from another system?
Claude Code already has tools such as Read, Edit, and Bash. For a deterministic local operation, a bundled script may be enough. Use one when it serves only this Skill, runs through an existing execution tool, and need not be independently discovered by other workflows:
release-check/scripts/validate-version.py
Use an MCP tool when the capability comes from an external service or process, multiple Skills or ordinary tasks need it, structured schemas and results matter, and authentication or lifecycle should be managed independently:
deployment server
ββ get_status(environment)
ββ deploy(version, environment)
ββ rollback(deployment_id)
The Skill knows when to query, deploy, or roll back; the server performs those actions. A private deterministic step suggests a bundled script. A reusable external action suggests a tool, commonly supplied through MCP.
Decision 4: Should the model decide, or must an event trigger it?
A Skill is interpreted by the model. If the requirement is βrun the formatter after every Edit,β putting that sentence in a Skill depends on Claude remembering and choosing to run it. A PostToolUse hook can respond to the Edit event directly.
Hooks fit fixed lifecycle events, repeated mandatory actions, blocking checks, and automation that should not depend on model initiative. Skills fit context-sensitive choices, branching workflows, reasoning, collaboration, and explanations. They can work together:
security-review Skill
β explains the review method
PreToolUse hook
β validates a dangerous command before it runs
Claude must decide how β Skill. The event itself must cause an action β hook. For truly hard guarantees, also use the platform's actual policy, authorization, or CI controls; instructions alone are not enforcement.
Decision 5: Main conversation or independent worker?
An inline Skill fits work that needs the full conversation, continued dialogue with the user, or tightly shared planning, implementation, and verification context.
A forked Skill or subagent fits self-contained work with extensive intermediate search or logs, a concise return value, or specialized tools, model, and permissions. It prevents the main context from being flooded.
A custom subagent is useful when the worker's role is more stable than any one workflow:
code-reviewer agent
system prompt + tools + model + permissions
+ preloaded review Skills
A Skill stores reusable content; a subagent provides an independent context and execution identity. A Skill can fork an agent, and an agent can preload Skills. Do not create an agent merely to store a prompt; do not force a large independent audit into an inline Skill.
Decision 6: One configuration or an installation unit?
Shared within one repository
β .claude/skills/ (project Skill)
Personal use across local projects
β ~/.claude/skills/ (personal Skill)
Install Skills + agents + hooks + MCP across projects
β plugin
Deploy an approved version across an organization
β managed configuration
A plugin is not another behavior layer. It packages existing components under a namespace and version. Do not turn a one-repository Skill into a plugin just to look formal. Conversely, do not keep copying one multi-component capability into ten repositories merely because it started standalone.
The complete decision tree
New capability requirement
β
ββ Fact or rule every relevant task should know?
β ββ Whole project β CLAUDE.md
β ββ Specific path β Rule / nested CLAUDE.md
β
ββ Knowledge or multi-step method needed for one class of tasks?
β ββ Skill
β ββ Needs main conversation β inline
β ββ Self-contained work β context: fork
β
ββ Must run when a fixed event occurs?
β ββ Hook
β
ββ Missing an atomic action?
β ββ Private deterministic step β bundled script
β ββ Reusable local operation β tool / executable
β ββ External service or process β MCP tool
β
ββ Needs separate context, role, model, or tools?
β ββ Subagent
β
ββ Multiple extensions need one installation/update path?
ββ Plugin / managed distribution
One complete capability will often match several branches. That is layered composition, not a contradiction.
Worked example: a production release
Break the opening requirement into a stack.
CLAUDE.md β broad project rules
- This project uses pnpm.
- Production release requires explicit user approval.
- The changelog follows Keep a Changelog.
Skill β on-demand workflow
release-check
1. Confirm target version and environment.
2. Inspect workspace and tests.
3. Validate changelog and version.
4. Query current deployment.
5. Summarize blockers.
6. Wait for the user's decision.
Scripts β deterministic validation
validate-version.py
check-changelog.py
MCP tools β deployment platform actions
get_deployment_status
deploy_release
rollback_release
Hook β deterministic checkpoint
PreToolUse
Validate approval and target environment before deployment.
Subagent β isolated audit
release-auditor
Read extensive changes and test output;
return a concise risk summary.
Plugin β multi-repository distribution
acme-release/
skills + agents + hooks + MCP configuration + scripts
If everything lives in one SKILL.md, every layer relies on model compliance. Separating mechanisms lets each carry the responsibility it handles best. For production approval, the hook must verify an actual authorization signal rather than infer consent from a prompt.
A decision tree inside a Skill
After deciding to build a Skill, choose its shape:
Mostly reference knowledge?
β Inline reference; optionally not user-invocable.
Task workflow?
ββ Must only the user choose its timing?
β β disable-model-invocation: true
ββ Needs the main conversation?
β ββ yes β inline
β ββ no, and intermediate work is large β context: fork
ββ Large, infrequently used details? β references/
ββ Deterministic processing? β scripts/
ββ Final templates or media? β assets/
These choices follow the earlier articles on format, discovery, invocation, rendering, and execution.
Quality: test triggering, then outcomes
A Skill needs at least two kinds of evaluation.
Trigger evaluation. Prepare positive, negative, and boundary prompts:
Should trigger:
βIs this version ready to release?β
βRun a release readiness check.β
Should not trigger:
βWhat does semver mean?β
βFix one typo in the README.β
Boundary:
βGenerate a changelog, but do not run the full release check.β
Check the description's precision and recall. Testing only manual /release-check invocation says nothing about automatic discovery.
Outcome evaluation. In fresh sessions, compare the same task with the Skill enabled and disabled. Did it follow the workflow, omit fewer checks, use references/scripts/tools correctly, avoid unnecessary context and calls, meet its output contract, and avoid new side-effect risks? Invocation proves routing; an improvement over baseline proves capability.
Maturity does not mean a longer SKILL.md
A useful progression might be:
v0 repeated prompt
v1 clear description + core workflow
v2 layered references / scripts / assets
v3 invocation control + permissions + verification
v4 evaluations + versioned distribution
Appending another warning to SKILL.md after every failure creates a huge prompt, not a mature capability. Fix the failure at the right layer:
| Failure | Better place to repair it |
|---|---|
| Never triggers | Description |
| Triggers incorrectly | What/when boundary, path scope |
| Skips a step | Core workflow |
| Gets rare details wrong | Reference |
| Deterministic operation is unstable | Script or tool |
| Mandatory action is occasionally skipped | Hook, CI, or policy |
| Permissions are too broad | Permissions, sandbox, authorization |
| Main context is flooded | Forked subagent |
| Team versions drift | Project, plugin, or managed distribution |
A Skill should not become the dumping ground for every defect.
Anti-patterns at a glance
| Anti-pattern | Consequence | Better approach |
|---|---|---|
Occasional workflows in CLAUDE.md
|
Permanent context noise | Skill |
| A Skill emulates an atomic structured API | Fragile arguments and output | Tool or MCP |
| A Skill says βalwaysβ without an enforcing mechanism | Depends on model memory | Hook, CI, or policy |
| A subagent exists only to hold reference material | Separate worker without a task | Inline or preload |
allowed-tools is treated as a strict allowlist |
Other tools may still be available | Deny rules, policy, agent tool list |
| Dynamic shell performs the main task before Claude reads it | Hidden side effects | Normal tool loop |
All material lives in SKILL.md
|
Expensive activation and compaction | Progressive disclosure |
| Task progress is stored in a Skill | Stale state contaminates future invocations | Task, session, or memory |
| Folder copying is called team distribution | Version and provenance drift | Project Git or plugin |
| Plugin packaging is treated as security review | Scripts and dependencies remain risky | Audit, pinning, sandbox |
A capability can move between layers
The first choice is not permanent:
Repeated pasted prompt β personal Skill
Personal workflow becomes project convention β project Skill
Many repositories need it β plugin
A step becomes stable and reusable β script, tool, or MCP
A recommendation becomes mandatory β hook, CI, or policy
A Skill's instruction is needed on every task β CLAUDE.md / Rule
Inline work overwhelms the main context β forked Skill / subagent
Reverse migrations also make sense. Move a release-only global rule into a Skill; return a single-repository plugin to project scope; move a forked task that always needs the full conversation inline; reduce a single-Skill-only tool to a bundled script. Good architecture keeps moving responsibility to the layer that actually owns it, rather than maximizing extension count.
The series in one sentence
A Skill is not merely a longer prompt, a convenient slash command, or a tool without a schema. It combines aspects of all three, but occupies its own place:
Prompt β instructions
β reuse and folder structure
Skill β discovery, on-demand loading, orchestration
β calls
Tools / MCP β atomic execution
It can extend the current agent inline or package a method for a forked worker. Permissions, hooks, and sandboxing govern execution; project, plugin, and managed scopes govern distribution.
A Skill is an on-demand package of operational knowledge: metadata makes it discoverable, instructions tell Claude how to work, resources and scripts supply material, tools turn the method into actions, and the runtime determines its context and permissions.
What comes after Skills?
Skills explain how to organize existing capabilities into workflows. The next question is how Claude Code obtains tools and data it did not previously have. That leads to the MCP research series: server tool schemas, connections, discovery, invocation, permissions, transports, and external lifecycles.
References
- Claude Code: Extend Claude Code
- Claude Code: Skills
- Claude Code: Tools reference
- Claude Code: Custom subagents
- Claude Code: Hooks reference
- Claude Code: Plugins
- Agent Skills specification
- Part 0: From Repeated Prompts to Callable Capabilities
- Part 1: From a Markdown File to a Portable Folder
- Part 2: From Description to Full Instructions
- Part 3: From a Directory to Claude's Candidate List
- Part 4: From User Request to Skill Activation
- Part 5: From Arguments to Dynamic Context
- Part 6: From Inline to Forked Subagents
- Part 7: From Invocation to Safe Execution
- Part 8: From Loading to Compaction
- Part 9: From Personal Folders to Team Plugins
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.