Claude Code Skills vs Slash Commands vs Subagents: Where Should Each One Live?
Claude Code offers multiple behavior-shaping mechanisms (CLAUDE.md, Skills, subagents, Plan Mode) that serve distinct purposes rather than competing with each other CLAUDE.md should contain persistent project context and general instructions that apply broadly across development tasks Skills are reusable workflows and procedures that can be invoked via slash commands, designed for multi-step processes that would otherwise be repeatedly pasted Subagents provide isolated specialized assistants wit
Analysis
TL;DR
- Claude Code offers multiple behavior-shaping mechanisms (CLAUDE.md, Skills, subagents, Plan Mode) that serve distinct purposes rather than competing with each other
- CLAUDE.md should contain persistent project context and general instructions that apply broadly across development tasks
- Skills are reusable workflows and procedures that can be invoked via slash commands, designed for multi-step processes that would otherwise be repeatedly pasted
- Subagents provide isolated specialized assistants with independent context windows and restricted tool access for focused investigation tasks
- Plan Mode enables Claude to explore and propose approaches before executing changes, preventing premature file modifications on complex refactors
Why It Matters
This guidance directly addresses a common scaling problem in AI-assisted development: as teams adopt Claude Code, instruction sprawl degrades effectiveness and maintainability. Understanding the proper home for each type of guidance prevents CLAUDE.md from becoming an unmanageable dumping ground and enables teams to build structured, reusable AI workflows. For AI practitioners, this represents a practical framework for organizing agent behavior at the project level rather than treating Claude Code as a single monolithic configuration.
Technical Details
- CLAUDE.md functions as project context, loaded into every relevant session; it should contain coding conventions, architecture notes, build/test commands, and any instruction Claude should know broadly—answerable by "Would I be annoyed if Claude didn't know this on every task?"
- Skills (formerly custom slash commands, now merged into the Skills model) live in
.claude/skills/<name>/SKILL.md, support supporting files, invocation controls, and automatic triggering based on task description matching; they are invoked via/skill-name - Subagents are specialized AI assistants with their own context window, system prompt, tool access, and permissions; they are designed for isolated investigation tasks (e.g., a security reviewer) that would otherwise flood the main conversation with tool output
- Plan Mode separates investigation from execution, allowing Claude to inspect the repository and produce a plan without modifying source files, then proceed to execution only after plan review
- Skills and subagents are composable: Claude Code supports running Skills inside subagents and preloading Skills into subagents, enabling layered workflows where a Skill defines procedure and a subagent handles specialized execution
Industry Insight
- Teams should adopt a "right home for every instruction" discipline when scaling Claude Code adoption, treating configuration organization with the same rigor as code organization to avoid context management degradation
- The merge of custom slash commands into the Skills model simplifies the mental model for practitioners; documentation and training should reflect this unified framework rather than treating them as separate concepts
- As AI coding tools mature, the differentiator between teams will increasingly be workflow design and instruction architecture—not just tool access—making organizational patterns like those described here a competitive advantage in development velocity and consistency
Disclaimer: The above content is generated by AI and is for reference only.