Fig. 01 · Schematic · Claude Code Customization Primitives

Which one do
I actually need?

Four overlapping ways to teach Claude Code something new — CLAUDE.md, slash commands, Skills, and subagents. They look interchangeable in the docs. They are not. This page is the decision tree.

CLAUDE.md Slash command Skill Subagent

↳ Rule of thumb

If the workflow has supporting files OR you want Claude to invoke it without being told, reach for a Skill. Otherwise climb the tree — the right primitive depends on whether the rule is always-on, whether you need an isolated context window, and whether the prompt is one file or many. ^[5]

§ 01 · The branching diagram

Walk top-to-bottom. The first "yes" wins. ^[5]

☀

CLAUDE.md

Memory file · auto-loaded

Best for: Always-on project rules, facts, conventions
Invokes: Automatic at session start
Context: Pays tokens every turn
Isolation: None — main window

"This repo uses pnpm, not npm. All tests live in __tests__/."

Slash command

Single-file prompt · manual

Best for: Explicit, repeatable workflows you'll type
Invokes: /name in the terminal
Context: Shares main window when run
Isolation: None

"/deploy-staging — kick off the staging rollout I keep mistyping."

⊞

Skill

Folder · auto-invoked · scripts ok

Best for: Procedures with files, templates, or auto-trigger
Invokes: Auto (description match) OR /name
Context: Description always · body on demand
Isolation: None (unless context: fork)

"A section of CLAUDE.md that has grown into a procedure." ^[1]

◊

Subagent

Separate window · returns summary

Best for: Research, multi-step, anything that pollutes context
Invokes: Auto-delegated or via Task tool
Context: Separate window — full isolation
Isolation: Full

"Explore the codebase for X, return a 200-word brief." Main thread stays clean.

§ 02 · Capability matrix

	Auto-invoke	Manual `/name`	Bundles files	Isolated context	Token cost when idle
CLAUDE.md	● always loaded	○ n/a	○ no	○ no	◐ every turn
Slash command	○ no	● yes	○ single file	○ no	● zero
Skill	● on description match	● yes	● folder	◐ with `context: fork`	◐ ~dozen tokens (name+desc)
Subagent	● auto-delegated	● via Task tool	● via Skill	● full window	● zero

§ 03 · Anatomy of a SKILL.md

---
description: Summarizes uncommitted changes and flags
  anything risky. Use when the user asks what
  changed, wants a commit message, or asks to
  review their diff.
allowed-tools: Bash(git diff *) Bash(git status *)
---

## Current changes

!`git diff HEAD`      # ← runs BEFORE model sees skill

## Instructions

Summarize the changes above in two or three
bullet points, then list any risks you notice
such as missing error handling, hardcoded
values, or tests that need updating.
If the diff is empty, say so.

↳ Frontmatter levers

description	The triage line. Capped at 1,536 chars. Front-load the use condition.
allowed-tools	Pre-approves tools while skill is active — skips per-call prompts.
disable-model-invocation	`true` = user-only. For `/deploy`, anything with side-effects.
user-invocable	`false` hides from `/` menu. Background knowledge Claude reads.
context: fork	Runs inside a subagent. Pair with `agent: Explore` or `Plan`.
paths	Glob. Auto-load only when working with matching files (monorepo-friendly).
model, effort	Per-skill overrides of session model / effort.

§ 04 · Reach for a Skill when…

★ Reach for Skill

You'd bundle scripts, templates, or reference docs alongside the prompt — slash commands are single-file. ^[1]
You want Claude to invoke it on its own when the conversation matches the description. ^[5]
A section of CLAUDE.md has grown into a procedure rather than a fact — move it out, pay the tokens only on activation. ^[1]
You want it to work in Cursor, Codex, Gemini CLI, OpenHands too — Skills are a cross-vendor open standard. ^[9]

⛔ Don't reach for Skill

The rule is a static fact about the repo ("uses pnpm") — that belongs in CLAUDE.md.
The workflow needs a long-lived stateful connection (DB session, OAuth, SaaS API) — that's an MCP server. ^[3]
The action has side-effects you want to keep behind explicit typing — a slash command's manual trigger is the feature.
The work would pollute the main context — use a subagent for the isolation; only wrap it in a Skill if you need auto-trigger or bundled files.

§ 05 · The dynamic-context footgun

⚠ Trust boundary · ToxicSkills audit

The same low friction that makes Skills viral makes them a supply-chain target.

The ` !`cmd` ` dynamic-context feature runs before the model ever sees the skill body. Model-level prompt-injection defenses never get a chance to fire. ^[7]

Mitigations: review every project Skill before accepting workspace trust · for untrusted sources, set disableSkillShellExecution: true · prefer source-reference distribution (marketplaces that pin to upstream commits) over copy-paste. ^[12]

36.8%

of audited skills carry at least one security flaw

13.4%

contain a critical-level issue (534 skills)

100%

of confirmed malicious skills carry malicious code

91%

of malicious skills also embed prompt-injection

§ 06 · Skill vs MCP — the live-wire question

↳ Reach for MCP when