Orchestrating
Commands, Skills,
Agents & Hooks

Use this to decide which layer is right for each piece of knowledge or behavior:

Start with a lean .claude.md for your project. Under 300 lines. Include:

• Tech stack and framework versions
• Build, test, and dev commands
• Code conventions and file organization
• Key architectural patterns

# .claude.md

## Tech Stack
Next.js 14, TypeScript, Tailwind, Supabase

## Commands
- npm run dev — Start dev server
- npm test — Run test suite
- npm run build — Production build

## Conventions
- Components in src/components/
- Server actions in src/actions/
- Tests in __tests__/ directories

Add hooks for things that must always happen. Start with protected files and auto-formatting.

// ~/.claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "prettier --write \"$FILEPATH\""
      }]
    }],
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/block-protected.sh"
      }]
    }]
  }
}

Why hooks over prompting? Prompting says "please format code." Hooks say "code is always formatted." One is a suggestion. The other is a guarantee.

Connect Claude to the services you use repeatedly. Start with GitHub and your database.

# Add GitHub MCP
claude mcp add --transport stdio github \
  -- npx -y @anthropic/mcp-server-github

# Add PostgreSQL MCP
claude mcp add --transport stdio postgres \
  --env DATABASE_URL=${DATABASE_URL} \
  -- npx -y @modelcontextprotocol/server-postgres

Notice patterns you explain repeatedly. Create your first skill with progressive disclosure: a lean SKILL.md (~500 words) with detailed references on demand.

# ~/.claude/skills/company-metrics/SKILL.md (~500 words)

---
name: company-metrics
description: "Company metric definitions and calculation patterns"
---

## Key Metrics
- MRR: SUM(subscription_amount) WHERE status='active'
- Churn: See references/churn-calculation.md
- LTV: See references/ltv-model.md

# ~/.claude/skills/company-metrics/references/churn-calculation.md
# (detailed docs, loaded only when relevant)

Progressive disclosure: Load 500 words upfront, 10,000 words on-demand. Context stays clean.

Create agents for specialized behavior. The key: agents are for behavior, not knowledge. Put knowledge in skills and let agents inherit it.

# .claude/agents/code-reviewer.md

---
name: code-reviewer
description: "Reviews code for quality, security, and convention compliance"
---

You are a code reviewer. Review with fresh perspective.
Focus on: security issues, missing error handling,
convention violations, and test coverage gaps.

Load the api-standards skill for pattern reference.

Once you know your workflow, encode it into commands. Commands are the glue — they orchestrate skills, agents, and tools into repeatable sequences.

# .claude/commands/start-work.md
# Fetches issue, creates branch, runs baseline,
# detects TDD requirements, reviews available tools

# .claude/commands/ship-it.md
# Builds, tests, commits, pushes, writes changelog, creates PR

# .claude/commands/document.md
# Converts conversation into a GitHub issue
# using the github-issue-creator skill

Commands are where the five layers come together. A single /start-work 247 can fetch an issue (MCP), create a branch (bash), load skills (knowledge), spawn agents (behavior), and enforce TDD (hooks).

# ~/.claude/skills/your-skill/SKILL.md

---
name: your-skill-name
description: "One line that tells Claude when to load this"
---

# Skill Name

## Purpose
What this skill teaches Claude to do.

## Core Knowledge (~500 words max)
The essential information Claude needs immediately.
Keep this lean — it's loaded into context.

## References (load on demand)
- See references/detailed-schemas.md for table schemas
- See references/query-patterns.md for SQL patterns
- See references/edge-cases.md for known gotchas

## When to Use
Activate when user asks about [triggers].
Don't use for [anti-triggers].

# .claude/agents/your-agent.md

---
name: your-agent-name
description: "What this agent does (behavior, not knowledge)"
---

You are a [role]. Your job is to [specific behavior].

# Load relevant skills for domain knowledge:
Load the [skill-name] skill for reference.

# Focus areas:
- [Specific thing to look for]
- [Specific thing to look for]
- [Specific thing to look for]

# Output format:
Report findings as:
1. Issue description
2. Location (file + line)
3. Severity (critical/warning/info)
4. Suggested fix

# .claude/commands/your-command.md

# /your-command - Short description

What this command does in one sentence.

## Usage
/your-command <argument>

## Workflow Steps
Execute in order. STOP and report if any step fails.

### Step 1: Pre-flight
[Validation checks]

### Step 2: Main action
[The core work — can invoke skills, agents, tools]

### Step 3: Verification
[Confirm the work succeeded]

### Step 4: Report
[Show results to user]

## Error Handling
| Error | Action |
|-------|--------|
| [Error type] | [What to do] |