Skip to content

config-types.md

Latest commit

 

History

History
281 lines (203 loc) · 6.94 KB

config-types.md

File metadata and controls

281 lines (203 loc) · 6.94 KB

Config Types Deep Dive

Detailed guide for each Claude Code configuration type.

1. Agents (~/.claude/agents/)

Purpose: Specialized subagents for delegated tasks with limited scope.

When to Create an Agent

Create an agent when you need:

  • Focused expertise on a specific domain (security, architecture, testing)
  • Limited tool access (don't need full toolset)
  • Reusable specialist that can be invoked across projects
  • Separation of concerns in complex workflows

Agent Structure

---
name: agent-name
description: What this agent does. When to use it. Be specific about triggers.
tools: Read, Grep, Glob, Bash  # Limit to what's needed
model: opus  # or sonnet for faster/simpler tasks
---

You are a [role] specialist focused on [primary goal].

## Your Role
- Responsibility 1
- Responsibility 2

## Process
### 1. Phase Name
- Step 1
- Step 2

## Output Format
[Define expected output structure]

## Best Practices
[Domain-specific guidance]

Key Fields

Field Purpose Examples
name Identifier for invocation planner, code-reviewer
description Triggers automatic invocation Include "Use when..."
tools Limited tool access Read, Grep, Glob, Bash
model Model selection opus (complex), sonnet (fast)

Best Practices

  1. Limit Tools: Agents don't need full toolset. Give only what's required.
  2. Specific Description: Include trigger phrases so Claude knows when to delegate.
  3. Clear Process: Define step-by-step workflow.
  4. Output Format: Specify expected output structure.
  5. Model Selection: Use opus for complex reasoning, sonnet for simpler tasks.

2. Rules (~/.claude/rules/)

Purpose: Always-follow guidelines loaded into every session.

When to Create a Rule

Create a rule when you need:

  • Non-negotiable invariants (security, style)
  • Automated enforcement without user prompting
  • Universal application across all projects
  • Checklists that must be verified

Rule Structure

# Rule Name Guidelines

## Mandatory Checks

Before [trigger action]:
- [ ] Check 1
- [ ] Check 2

## Category 1

```code
// NEVER: Bad example
bad_code

// ALWAYS: Good example
good_code

Response Protocol

If [violation] found:

  1. Action 1
  2. Action 2

### Best Practices

1. **Keep Concise**: Rules are always loaded - minimize token usage.
2. **Use Checklists**: Easy to verify compliance.
3. **Show Examples**: NEVER/ALWAYS patterns are clear.
4. **Define Protocols**: What to do when violations found.
5. **Non-Negotiable Only**: Rules should be invariants, not preferences.

---

## 3. Commands (`~/.claude/commands/`)

**Purpose**: Slash commands for quick execution (`/command-name`).

### When to Create a Command

Create a command when you need:
- User-triggered workflow (not automatic)
- Repeatable process with consistent output
- Quick access to complex operations
- Standardized workflow invocation

### Command Structure

```markdown
---
description: What this command does in one line.
---

# Command Name

## What This Command Does
[Explanation]

## When to Use
[Triggers]

## How It Works
[Process steps]

## Example Usage
[Concrete example with input/output]

## Related Agents
[Which agent this command invokes]

Best Practices

  1. Action-Oriented Description: Start with verb (e.g., "Enforce test-driven...")
  2. Clear Triggers: When should user invoke this?
  3. Concrete Examples: Show realistic input/output.
  4. Link to Agents: Commands often invoke specialized agents.
  5. Wait for Confirmation: Some commands (like /plan) should wait before acting.

4. Hooks (~/.claude/settings.json)

Purpose: Trigger-based automations fired on tool events.

When to Create a Hook

Create a hook when you need:

  • Automatic actions before/after tool use
  • Guardrails and safety checks
  • Automated formatting or validation
  • Session lifecycle management

Hook Types

Type When Fired Use Case
PreToolUse Before tool executes Block unsafe commands, warn about patterns
PostToolUse After tool executes Auto-format, lint, validate
PreCompact Before context compaction Save state
SessionStart New session begins Load previous context
Stop Session ends Final audits, persist state

Hook Structure

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool == \"Bash\" && tool_input.command matches \"pattern\"",
        "hooks": [
          {
            "type": "command",
            "command": "#!/bin/bash\ninput=$(cat)\n# Logic here\necho \"$input\""
          }
        ],
        "description": "What this hook does"
      }
    ]
  }
}

Matcher Syntax

tool == "ToolName"                    # Match specific tool
tool_input.field matches "pattern"    # Match field with regex
*                                     # Match all

Best Practices

  1. Specific Matchers: Don't use * unless necessary.
  2. Exit Codes: exit 1 to block, exit 0 to allow.
  3. Pass Through Input: Always echo "$input" at end to allow tool execution.
  4. Descriptive Messages: echo '[Hook] MESSAGE' >&2 for user feedback.
  5. Test Thoroughly: Hooks can break workflows if misconfigured.

5. Skills (~/.claude/skills/)

Purpose: Domain knowledge and workflow definitions.

When to Create a Skill

Create a skill when you need:

  • Project-specific knowledge (schemas, APIs, patterns)
  • Framework-specific guidance
  • Reusable workflow that spans multiple commands
  • Documentation that Claude needs to reference

Skill Structure

skill-name/
├── SKILL.md              # Main skill file
├── references/           # Supporting documentation
│   └── detailed-guide.md
└── assets/               # Templates, scripts
    └── template.md

Best Practices

  1. Concise SKILL.md: Keep under 500 lines.
  2. Progressive Disclosure: Put details in references/.
  3. Clear Triggers: Description should specify when to use.
  4. No Redundancy: Don't duplicate content between SKILL.md and references.
  5. Templates in Assets: Things to copy, not read into context.

6. CLAUDE.md (Project & User Level)

Purpose: Project context and personal preferences.

Project-Level (./CLAUDE.md)

Put in your project root for:

  • Project overview and tech stack
  • Build/test commands
  • File structure documentation
  • Project-specific patterns
  • Environment variables

User-Level (~/.claude/CLAUDE.md)

Put in ~/.claude/ for:

  • Personal coding preferences
  • Universal rules you always want
  • Links to your modular rules/agents
  • Editor integration notes

Best Practices

  1. Project-Specific in Project: Don't duplicate user-level content.
  2. Link to Rules: Reference ~/.claude/rules/ instead of duplicating.
  3. Keep Updated: Update CLAUDE.md as project evolves.
  4. Quick Reference: Include command reference for fast lookup.