claude-config git:20260618.11f99f3A

Immutable. This exact content never changes and is served at /api/v1/blob/89472934d65fa102.

---
name: claude-config
description: How agents, skills, and commands work in Claude Code projects.
when_to_use: Creating or modifying files in .claude/ — agents, skills, commands, or settings.
---

# Claude Configuration Primitives

Three distinct configuration types in `.claude/`. Each has a clear purpose — never conflate them.

## Agents = Roles

An agent defines **who you are**. It shapes focus, identity, and constraints for a subagent.

- Role identity ("You are a senior backend reviewer")
- Tool and permission constraints
- What the agent cares about (evaluation criteria, output format, confidence thresholds)
- Runs in an isolated subagent context

**Agents are not workflows.** They define a lens for approaching work, not steps to follow. A backend-reviewer says "you care about async correctness and session handling" — not "Step 1: read the diff."

**Good:** Role identity, focus areas, evaluation criteria, output format, what to read for context.
**Bad:** Step-by-step procedures, bash scripts, workflow orchestration.

## Skills = Context and Knowledge

A skill defines **what you know**. It provides conventions, recommendations, how-tos, and reference material.

- Reference knowledge ("Here's how migrations work in this project")
- Conventions ("Module files follow this structure")
- Recommendations ("When writing docs, prefer tables over prose")
- Templates and examples when they're the core value

**Skills are not workflows.** They provide knowledge for good decision-making.

A skill MAY include a sequence when it's critical reference — but as illustrative guidance, not a script to execute.

**Good:** Conventions, patterns, templates, recommendations, how-tos, reference material.
**Bad:** Rigid step-by-step procedures, orchestration logic, state management.

## Commands = Workflows

A command defines **what to do**. An explicit, purposeful sequence triggered by the user.

- Specific workflow with clear start and end
- Defines what happens in what order
- Has a trigger (`/command-name`) and expected output
- May include specific commands to run, but skills inform the how

**Commands are workflows.** They define *what* to do; skills inform *how* to do each step well.

**Good:** Step sequences, action triggers, workflow orchestration, expected outcomes.
**Bad:** General knowledge, conventions, recommendations unrelated to the workflow.

## How They Interact

- Commands trigger action, skills provide context, agents provide specialized focus
- Commands may invoke agents as part of their workflow
- Agents may preload skills for additional project context

## Naming

- **Agents** answer "who is this?" — `backend-reviewer`, `issue-planner`
- **Skills** answer "what does this teach?" — `logging-patterns`, `github-conventions`
- **Commands** answer "what does this do?" — `plan-issue`, `review-pr`

Naming should be predictable within a category but not forced into a single suffix.

## Testing the Distinction

1. **Defines a role identity?** -> Agent
2. **Provides knowledge or recommendations?** -> Skill
3. **Executes a sequence of actions?** -> Command

If a file does two of these, split it.

## Workspace

`.claude/workspace/` is the conventional path for working documents — plans, research, scratch files. Skills and commands that need to write intermediate files should use this directory.