Skills and Profiles — Configuration at Scale

There is an upper bound on how many instructions Claude can hold in active attention at once. Nobody publishes this number. But anyone who has built a CLAUDE.md past a few hundred lines has felt the effect: Claude follows some rules and quietly ignores others. The instructions are present in the file. They are not present in the behavior.

This is instruction fatigue. The configuration system does not scale horizontally — you cannot solve it by adding more lines to one file. You solve it by making instructions load only when they are relevant.

The Instruction Fatigue Problem

A CLAUDE.md that covers React patterns, API conventions, test standards, database migration rules, deployment procedures, and naming conventions is technically complete. In practice, when Claude is fixing a unit test, it is receiving instructions about Terraform deployment that have zero relevance to the current task. That cognitive overhead accumulates across every task in every session.

The solution is layered configuration: universal rules in CLAUDE.md, file-type rules in path-scoped configs, workflow rules in skills, and agent behavior rules in agent definitions.

Path-Scoped Rules

Claude Code supports configuration files in .claude/ subdirectories that load only when Claude reads files matching a specified path pattern. A rule file at .claude/rules/react.md can be configured to load only when Claude works on *.tsx files. A rule file at .claude/rules/api.md loads only for files in app/api/.

The structure:

.claude/
  settings.json          # Project-level settings
  rules/
    react.md             # Loads for *.tsx, *.jsx
    api.md               # Loads for app/api/**
    tests.md             # Loads for *.test.ts, __tests__/**
    migrations.md        # Loads for prisma/migrations/**

Each rules file is focused and short — 20-40 lines covering only what is relevant to that file type. When Claude works on a React component, it loads the React rules. When Claude writes a test, it loads the test rules. The API conventions are absent, which is correct — they are irrelevant to the current task.

The practical effect: each specialized instruction set is small enough to hold in active attention, and it only appears when it is actually useful.

Skills — Reusable Workflow Templates

A skill is a prompt template invoked by name. Instead of re-explaining a complex workflow every session, you write it once as a skill and invoke it with /skill-name.

Skills live in ~/.claude/skills/<name>/SKILL.md. The anatomy of a skill file:

---
name: feature-team
description: Spawn a 3-agent feature team for implementing a feature from a PRD
allowed-tools: Agent, Read, Bash, Edit, Write, SendMessage
---

# Feature Team Skill

You are an orchestrator spawning a 3-agent feature team.

## Step 1 — Define Territories
Before spawning any agent, establish file territories:
- Backend Dev owns: app/api/, lib/db/, prisma/, lib/types/
- Frontend Dev owns: app/(routes)/, components/, hooks/
- QA Engineer owns: __tests__/, e2e/, *.test.ts

## Step 2 — Write the Definition of Done
Extract acceptance criteria from the PRD or task description.
List each criterion as a checkable item.

## Step 3 — Spawn Agents
Spawn Backend Dev, Frontend Dev, and QA Engineer as Agent tool calls.
Include territories and DOD in each agent's prompt.

## Step 4 — Monitor and Integrate
Monitor SendMessage outputs.
Resolve blockers. Run final integration check.

The frontmatter allowed-tools field restricts which tools the skill can use. This is security-relevant: a skill that should only read and analyze should not be able to spawn agents or write files.

A deploy skill can call a test skill as a prerequisite. A security-review skill can call both static-analyze and dependency-audit skills. You build a library of focused skills and compose them for complex workflows.

What Skills Are Not

Skills are not automatically available to subagents. This is the most common misconception.

When you spawn a subagent via the Agent tool, that agent starts in a fresh session. It has no awareness of the skills in your ~/.claude/skills/ directory. If you want a subagent to follow the feature-team skill's protocol, you must either pass the skill explicitly via the skill flag, or include the relevant instructions in the agent's system prompt.

# Correct — passing skill explicitly
Spawn a Backend Dev agent using the feature-team skill protocol.
skill: feature-team

# Incorrect — assuming skill inheritance
Spawn a Backend Dev agent. Follow the usual feature-team protocol.
# (The subagent has no idea what the "usual protocol" is)

Agent Definitions

Skills define workflows. Agent definitions define persistent agent identities. The difference is scope.

An agent definition file at .claude/agents/backend-dev.md defines a named agent with specific capabilities, model, and system prompt that persists across every time you invoke that agent. It is a stable entity that you dispatch to tasks, not a workflow that you run.

---
name: backend-dev
model: opus
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
mcpServers: []
---

You are a senior backend engineer specializing in Next.js API routes,
Prisma, and TypeScript. You follow the project's conventions in
.claude/rules/api.md and never touch frontend files.

When you complete a task, report the following:
1. What was implemented
2. Test coverage achieved
3. Any follow-on work that is required

Agent definitions solve a real problem in fleet management: instead of writing the same system prompt for the backend developer in every orchestrator skill, you define it once and reference it by name. Changes to the agent's instructions propagate everywhere it is used.

When to Use What

The configuration system has four layers. Knowing which layer a rule belongs to is the routing decision for configuration.

CLAUDE.md — universal project rules that apply to every task and every file. Git workflow, test coverage requirements, commit standards, naming conventions, security rules. If a rule is always relevant, it lives here.

Path-scoped rules — conventions that apply only to specific file types or directories. React component patterns, API route conventions, test writing standards, migration protocols. If a rule is only relevant when working in a specific part of the codebase, it lives in a scoped rules file.

Skills — reusable multi-step workflows. Deployment procedures, agent team dispatch protocols, audit checklists, release processes. If a workflow is repeatable and complex enough to warrant a prompt template, it lives in a skill file.

Agent definitions — stable agent identities. Named agents with specific capabilities, model selections, and system prompts. If you dispatch the same type of agent repeatedly, it lives in an agent definition.

The Tiered File Importance Pattern

One CLAUDE.md technique that scales before you need path-scoped rules: tier your file references explicitly.

## File Importance Tiers

### Tier 1 — Always Load
These files define universal project constraints. Read them at session start.
- src/lib/types/ — TypeScript interfaces
- prisma/schema.prisma — data model

### Tier 2 — Load on Demand
Load these only when working in the relevant area.
- src/components/ui/ — when touching UI components
- app/api/ — when touching API routes

### Tier 3 — Ignore Unless Relevant
- scripts/ — only relevant when explicitly running scripts
- docs/ — reference only when answering documentation questions

This instructs Claude to load context selectively rather than reading every file in the project. For a codebase with 200+ files, this difference is measurable — Claude spends context tokens on relevant code rather than peripheral files.

Lesson 187 Drill

Open your current project's CLAUDE.md and run this audit:

1. For each instruction block, ask: "Is this relevant to every task in this project, or only to specific file types or workflows?"
2. Move any file-type-specific instructions to .claude/rules/<type>.md
3. Identify any repeated workflows you explain to Claude regularly — those are skill candidates
4. Check whether you have any named agents you spawn frequently — those are agent definition candidates

After the decomposition, your CLAUDE.md should be shorter, and each specialized config file should be more focused. The test: when Claude works on a React component, it should not be holding database migration instructions in working memory. When it works on an API route, it should not be holding Playwright test patterns.

Focused instructions produce more reliable behavior than comprehensive ones.