Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 10 min read

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.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 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

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.