From CLAUDE.md to Skills to Hooks: Claude Code Infrastructure Progression

Mar 21, 2026

Problem

When I started using Claude Code, I kept adding rules to CLAUDE.md. But after about 100 lines, I hit a ceiling—Claude started ignoring instructions and making the same mistakes repeatedly.

The core issue: CLAUDE.md is a rule repository, not infrastructure. Rules degrade; infrastructure doesn’t.

What happened?

I went through a progression of approaches:

Level 1: Raw prompting → No persistence, same mistakes repeatedly
Level 2: CLAUDE.md → Rules persist, but hits ceiling at ~100 lines
Level 3: Skills → Modular expertise, load on demand
Level 4: Hooks → Environmental enforcement
Level 5: Orchestration → Coordinated automation

The Solution: Infrastructure Progression

Level 2: CLAUDE.md (Use as Router, Not Rule Dump)

CLAUDE.md works best when it’s a router, not a rule dump:

# Tool Selection
- For planning: Use planner agent
- For TDD: Use tdd-guide agent
- For security: Use security-reviewer agent

# Global Constraints
- Never commit without running tests
- Always validate user input
- No hardcoded secrets

Keep it under 100 lines. Place universal constraints here.

Level 3: Skills (Modular Expertise)

Skills load on demand and consume zero tokens when inactive:

name: code-reviewer
description: Expert code reviewer for quality and security
triggers:
  - "review this code"
  - "code review"
instructions: |
  Analyze code for:
  - Security vulnerabilities
  - Performance issues
  - Code smell detection
  - Best practice violations

Skills are best for task-specific workflows and specialized knowledge.

Level 4: Hooks (Environmental Enforcement)

Hooks enforce quality without instruction:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": ["prettier --write"]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": ["check-for-dangerous-commands"]
      }
    ]
  }
}

Hooks are best for preventing mistakes and enforcing standards automatically.

Level 5: Orchestration (Coordinated Automation)

For complex workflows, use parallel agents:

async def feature_implementation_workflow():
    # Phase 1: Parallel planning
    plan = await run_agent("planner", requirements)
    security_review = await run_agent("security-reviewer", plan)

    # Phase 2: Parallel implementation
    results = await asyncio.gather(
        run_agent("tdd-guide", plan.module_a),
        run_agent("tdd-guide", plan.module_b),
        run_agent("tdd-guide", plan.module_c)
    )

    # Phase 3: Integration
    return await run_agent("integrator", results)

Why This Matters

The progression from CLAUDE.md to Skills to Hooks is about moving from instruction-based to infrastructure-based AI development:

Level	Approach	Enforcement
CLAUDE.md	Documentation	Probabilistic (70-90%)
Skills	Modular expertise	On-demand loading
Hooks	Automation	Deterministic (100%)
Orchestration	Coordination	Multi-agent workflows

Token efficiency: Skills and hooks reduce context consumption.

Scalability: Infrastructure scales where rules don’t.

Reliability: Hooks enforce quality automatically.

Common Mistakes

Overloading CLAUDE.md: Adding every rule instead of creating skills
Skipping Skills: Jumping from CLAUDE.md to hooks without intermediate modularity
Hook Over-engineering: Creating hooks for things that should be skills
Ignoring Orchestration: Running agents sequentially when parallel would be faster

Summary

In this post, I showed the progression from CLAUDE.md to Skills to Hooks. The key point is: when CLAUDE.md exceeds 100 lines, you’re not solving problems—you’re creating them. Extract to skills, enforce with hooks, coordinate with orchestration.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit: Claude AI Discussion

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!