My Claude Code OS: 20 Agents, 8 Skills, 11 Hooks, and 5 Aliases | AI PM Portfolio

My Claude Code OS: 20 Agents, 8 Skills, 11 Hooks, and 5 Aliases

April 11, 2026 · 16 min read · Claude Code

Last Updated: 2026-04-11

A production Claude Code setup consists of four layers: agents (specialized sub-processes for specific tasks), skills (reusable slash-command workflows defined in SKILL.md files), hooks (automated shell commands triggered by tool events like file edits or git pushes), and aliases (terminal shortcuts that launch Claude Code with pre-loaded context). Combined with a persistent memory system of 50+ indexed files, this configuration eliminates repeated mistakes, automates 30 minutes of daily overhead, and produces 2-3x faster development velocity compared to vanilla Claude Code.

Why does Claude Code need an operating system?

Out of the box, Claude Code is a powerful coding assistant. But every session starts from zero. It does not remember your architectural decisions. It does not enforce your team's conventions. It does not know that the last three times it suggested a raw fetch() to your storage API, you had to correct it to use the SDK. It forgets everything the moment you close the terminal.

After six months of daily use building a production SaaS application -- 189 API routes, 65+ database tables, 206 modules -- I found myself repeating the same corrections, the same context-setting, the same pre-deployment checks every single session. The cognitive overhead was not the coding. It was the re-onboarding.

The mental model that resolved this: treat Claude Code like a junior engineer you are onboarding permanently. Skills are your SOPs. Memory is your institutional knowledge base. Hooks are your automated guardrails. Agents are your delegation framework. The "OS" is not a metaphor -- it is a literal operating system layer that sits between you and the AI, ensuring consistency, enforcing quality, and accumulating knowledge across every session. I wrote about the first 12 agents and 9 hooks here.

What are the 20 custom agents and why do they exist?

Agents in Claude Code are specialized sub-processes, each spawned with their own context window and a focused task. The parent session orchestrates them. Think of agents as specialists you page when a specific domain requires deep focus -- you would not ask your deployment monitor to also review your database schema.

My 20 agents break into four categories:

Core workflow agents (6)

• deploy-monitor -- watches Vercel build + Sentry after every push, runs in background on the Sonnet model to save tokens
• migration-reviewer -- reviews every Supabase migration for RLS gaps, missing indexes, and FK constraints before apply
• scope-check -- pre-commit detection of scope creep (flags commits touching more than the stated task)
• incident-triage -- production incident diagnosis: pulls Sentry, correlates with recent deploys, suggests rollback or fix
• pre-push-audit -- semantic code audit that catches patterns linting cannot (fire-and-forget async, un-awaited promises at request boundaries)
• context-scout -- pre-feature codebase exploration that maps relevant files, existing patterns, and potential conflicts before you write a line of code

Operations agents (6)

• db-health -- weekly audit of RLS policies, missing indexes, orphaned rows, and trigger integrity
• pr-preparer -- stages, commits, pushes, and creates a PR in one step with auto-generated description
• extraction-debugger -- traces document extraction failures through the full pipeline (upload, OCR, AI extraction, validation)
• client-pulse -- daily pipeline status check: stuck returns, unpaid invoices, incomplete onboarding
• blog-publisher -- drafts, SEO-optimizes, and publishes to Ghost with metadata
• prompt-auditor -- compares prompts in code versus Langfuse, flags drift, measures token cost trends

Debugging agents (4)

• nightly-qa-runner -- analyzes nightly QA test failures and correlates each failure with the commit that introduced it
• email-debugger -- traces email delivery through the full chain: gate logic, template brain, email log, Resend API
• stripe-debugger -- traces payment flows from webhook to invoice status to checkout completion
• onboarding-debugger -- diagnoses why a specific client is stuck: checks documents, tasks, meetings, invoices, and extraction status

Maintenance agents (4)

• perf-profiler -- bundle size analysis, API latency measurement, Lighthouse scores, Core Web Vitals
• dependency-checker -- outdated dependencies, security advisories (CVEs), and blocked upgrade paths
• seo-auditor -- audits blog posts against a 7-pillar keyword strategy with specific gap identification
• release-notes -- generates categorized changelogs between any two git refs

A critical operational constraint I learned the hard way: never run more than 3 concurrent background agents. Each agent spawns Node.js processes (tsc, vitest, esbuild). At 5+ concurrent agents, memory exhaustion corrupts git's .git/HEAD, kills tsc with exit code 138, disconnects MCP servers, and fails builds with exit 137 (OOM killed). Three concurrent is the safe ceiling on a 16GB machine.

How is an agent file structured?

Each agent lives in .claude/agents/ as a Markdown file with YAML frontmatter. Here is the structure of the deploy-monitor agent:

# .claude/agents/deploy-monitor.md
---
name: deploy-monitor
model: sonnet                    # cheaper model for monitoring tasks
description: Post-push Vercel build + Sentry monitoring
tools: [Bash, Read, Grep, WebFetch]
---

You are a deployment monitor. After a git push:
1. Watch Vercel deployment status until build completes or fails
2. Check Sentry for new errors in the last 5 minutes
3. Report: build status, deploy URL, any new Sentry issues
4. If build fails, extract the error from build logs

Run in background. Do not block the parent session.

The key design decision: assign the cheapest model that can handle the task. Monitoring and linting agents run on Sonnet. Debugging and migration review agents run on Opus. This keeps token costs proportional to task complexity. My production comparison of Claude, Gemini, and GPT informs these model assignments.

What are the 8 skills and how do they differ from agents?

Skills are reusable slash-command workflows. Where agents are specialists you delegate to, skills are SOPs (standard operating procedures) that run in the current session. You type /deploy and a 7-stage pipeline executes. You type /postmortem and a structured incident review begins.

The distinction matters: agents get their own context window and run independently. Skills share your context window and execute sequentially. Use agents for background or parallel work. Use skills for interactive workflows where you want to see every step.

How is a skill file structured?

Each skill is a SKILL.md file inside ~/.claude/skills/[skill-name]/. Here is a simplified example:

# ~/.claude/skills/postmortem/SKILL.md
---
name: postmortem
description: Document a production bug as a permanent memory file.
  Captures what broke, why, the fix, and the pattern to watch for.
argument-hint: "[brief description of the bug]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# Postmortem Skill

You are documenting a production incident for $ARGUMENTS.

## Steps

1. Ask the user: What broke? What was the impact?
2. Ask: What was the root cause?
3. Ask: What was the fix? (Include commit hash if available)
4. Ask: What pattern should we watch for to prevent recurrence?
5. Save to ~/.claude/projects/[project]/memory/ as:
   `project_postmortem_[date]_[slug].md`

## Output Format
---
name: Postmortem - [title]
description: [one-line summary]
type: project
---
**Date:** YYYY-MM-DD
**Impact:** [severity + scope]
**Root Cause:** [technical explanation]
**Fix:** [what was done, commit hash]
**Pattern:** [reusable lesson for future sessions]
**Related:** [[linked memory files]]

The allowed-tools field is a security boundary. The postmortem skill can read and write files but cannot execute arbitrary web requests. The deploy skill gets access to Bash and WebFetch. Each skill gets the minimum permissions it needs. My MCP server setup follows the same principle of minimum necessary access.

What are the 11 hooks and how do they automate quality?

Hooks are shell commands configured in settings.json that fire automatically on specific tool events. They are the guardrails layer -- things that should happen every time, without you remembering to do them.

Claude Code supports five hook events:

1. PreToolUse -- fires before a tool executes (intercept and block)
2. PostToolUse -- fires after a tool completes (validate and transform)
3. SessionStart -- fires when a new session begins (load context)
4. Stop -- fires when Claude finishes a response (notify)
5. StopFailure -- fires when Claude hits an error or rate limit (alert)

My 11 hooks by event type:

PreToolUse hooks (4 -- the gatekeepers)

PostToolUse hooks (3 -- the formatters and auditors)

SessionStart hooks (2 -- the context loaders)

Stop and StopFailure hooks (2 -- the notifiers)

How is a hook configured?

Hooks live in ~/.claude/settings.json. Here is the Prettier auto-format hook:

// ~/.claude/settings.json (excerpt)
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\" 2>/dev/null || true",
        "description": "Auto-format files after Claude writes or edits them"
      }
    ]
  }
}

The matcher field filters which tool invocations trigger the hook. The command receives environment variables like $TOOL_INPUT_FILE_PATH from the tool event. The trailing || true prevents Prettier failures from blocking Claude's workflow. This single hook eliminated every "can you run Prettier?" message from my workflow -- approximately 15-20 times per day.

What are the 5 shell aliases and why do they matter?

Aliases are terminal shortcuts in ~/.zshrc that launch Claude Code with specific flags or pre-loaded context. They reduce the friction of starting a session with the right configuration.

# ~/.zshrc (Claude Code aliases)

# Standard session with auto-naming (defaults to "Apr11-1430" format)
alias cc='claude --session-name "${1:-$(date +%b%d-%H%M)}"'

# Morning briefing -- loads /morning skill context automatically
alias ccmorning='claude --session-name "morning-$(date +%b%d)" --skill morning'

# Deploy pipeline -- optional "prod" argument for production promotion
alias ccdeploy='claude --session-name "deploy-$(date +%b%d-%H%M)"'

# Bare mode -- 14% faster startup, no hooks or LSP overhead
alias ccbare='claude --bare --session-name "bare-$(date +%H%M)"'

# Dependency audit -- no persistent session, just run and report
alias ccaudit='claude --no-session --skill audit'

The most impactful alias is ccbare. When I need a quick answer or a one-off task, bare mode skips hook initialization, LSP setup, and MCP server connections. The 14% startup speed improvement (measured over 50 launches: 2.1s vs 2.4s average) adds up across dozens of daily sessions. For anything touching production code, I use the full cc alias with all guardrails active.

How does the memory system work?

The memory system is the foundation that makes everything else compound. Without it, every session starts from zero. With it, Claude enters every session knowing your architectural decisions, past mistakes, project state, and team conventions.

The structure:

~/.claude/projects/[project-name]/memory/
  MEMORY.md              # Index file -- Claude reads this first every session
  user_*.md              # About the user (role, preferences, goals)
  feedback_*.md          # Corrections and conventions ("never do X, always do Y")
  project_*.md           # Active project state (in-progress features, bugs, sprints)
  reference_*.md         # Stable reference data (test accounts, API keys, architecture docs)

My production setup has 50+ memory files totaling approximately 45,000 words. The MEMORY.md index file organizes them by domain with one-line descriptions, so Claude can locate the right memory file without reading all of them.

What does a memory file look like?

# ~/.claude/projects/my-app/memory/feedback_stripe_rules.md
---
name: Stripe Integration Rules
description: Webhook debugging patterns, Preview env gotchas,
  customer ID gap between auth and Stripe
type: feedback
---

## Rules
1. Always use `stripe listen --forward-to` for local webhook testing
2. Preview deployments use test-mode keys -- never production
3. Customer ID is created at signup, not at first payment --
   check `stripe_customer_id` column before creating a new customer
4. Webhook signature verification fails silently if the
   endpoint secret is from a different Stripe environment

## Why
Learned from 3 separate production incidents in March 2026.

## Related
- [[project_billing_system]] -- billing feature context
- [[feedback_lazy_sdk_init]] -- never init Stripe at module level

The feedback_*.md files are the most valuable category. Each one captures a correction I made to Claude -- "you suggested X, the right answer is Y, here is why." Over 6 months, these accumulated into a knowledge base of 30+ domain-specific rules that prevent Claude from repeating the same mistakes. According to my git log, the average bug is now fixed in 1.2 iterations instead of 3.4 before the memory system existed -- a 65% reduction in correction cycles.

How do all four layers work together in a daily workflow?

Here is what a typical day looks like with the full OS active:

# 9:00 AM -- Morning briefing
$ ccmorning
# /morning skill runs: git log, open PRs, Sentry errors, CI status
# Output: "3 PRs open, 1 Sentry error (payment webhook timeout), CI green"

# 9:15 AM -- Start a new feature
$ cc feature-onboarding-flow
# SessionStart hooks fire: directory guard, PostCompact recovery
# Memory loads: MEMORY.md index, relevant project files
# /interview skill captures requirements before coding begins

# 11:00 AM -- Code review before merge
# /review runs 4 parallel reviewers (security, backend, frontend, QA)
# Each reviewer has domain-specific checklists loaded from memory

# 11:30 AM -- Deploy to staging
# /deploy runs 7-stage pipeline
# PreToolUse hooks: tsc check, branch isolation
# PostToolUse hooks: audit log captures every command
# deploy-monitor agent runs in background watching Vercel + Sentry

# 2:00 PM -- Bug report comes in
$ cc bugfix-payment-timeout
# @stripe-debugger agent traces the payment flow
# Fix applied, tests pass
# /postmortem captures the incident as a permanent memory file

# 5:00 PM -- End of day
# Stop hook fires: macOS notification with summary
# Audit log contains full record of every command executed

The compounding effect is the point. Each postmortem adds a memory file. Each /wrong entry refines Claude's future behavior. Each hook prevents a class of errors automatically. After 6 months, the system has accumulated enough institutional knowledge that Claude rarely makes the same mistake twice.

How does a configured Claude Code setup compare to alternatives?

The comparison is not "which tool is best." Each serves a different workflow. GitHub Copilot excels at inline completion. Cursor excels at IDE-integrated chat. Claude Code excels at terminal-native, agentic workflows on complex codebases. The OS layer amplifies Claude Code's strengths for developers who live in the terminal and work on production systems daily.

What does the setup actually cost and what is the ROI?

The honest accounting:

• Initial setup time: approximately 2 weeks of incremental configuration, adding 1-2 components per day alongside normal development work. Not 2 weeks of full-time configuration.
• Ongoing maintenance: approximately 30 minutes per week -- mostly updating memory files and occasional hook tuning.
• Token cost increase: approximately 15-20% higher token usage due to memory file loading and agent spawning. At current Claude API pricing, this adds roughly $30-50/month for heavy daily use.

The measurable returns:

• Context-setting time eliminated: 25-30 minutes per day previously spent re-explaining project context, conventions, and past decisions to Claude. With memory, this drops to near zero.
• Bug correction cycles: reduced from an average of 3.4 iterations to 1.2 iterations per bug fix (65% reduction), measured across 47 bug fixes over 3 months.
• Deployment confidence: zero production incidents caused by missing pre-push checks since implementing the hook system (previously: 2-3 per month).
• Repeated mistakes: the /wrong system has logged 34 corrections. Of those 34 patterns, only 2 have recurred -- a 94% non-recurrence rate.

The net effect: development velocity improved approximately 2-3x compared to vanilla Claude Code, measured by features shipped per week (from 3-4 to 8-10 on the same codebase). The improvement is not from Claude being smarter. It is from Claude not being forgetful.

How do you get started in 30 minutes?

You do not need all 20 agents and 11 hooks on day one. Here is the minimum viable setup that delivers immediate value:

The 30-Minute Starter Kit: 1 skill, 1 hook, 3 memory files, 1 alias. This covers 60% of the value with 10% of the configuration effort.

Step 1: Create a memory index (5 minutes)

# Create the memory directory
mkdir -p ~/.claude/projects/my-app/memory

# Create the index file
cat > ~/.claude/projects/my-app/memory/MEMORY.md << 'EOF'
# Project Memory

## Architecture
- [reference_architecture.md](./reference_architecture.md) -- tech stack, key patterns

## Rules
- [feedback_conventions.md](./feedback_conventions.md) -- project-specific do/don't rules

## Active Work
- [project_current_sprint.md](./project_current_sprint.md) -- what's in progress
EOF

Step 2: Create your first feedback file (5 minutes)

cat > ~/.claude/projects/my-app/memory/feedback_conventions.md << 'EOF'
---
name: Project Conventions
description: Rules Claude must follow in this codebase
type: feedback
---
## Rules
1. Always use the Supabase SDK for storage -- never raw fetch
2. All API routes must have error handling with proper status codes
3. Use TypeScript strict mode -- no `any` types
4. Run Prettier before committing
EOF

Step 3: Add the Prettier hook (5 minutes)

// Add to ~/.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

Step 4: Create a postmortem skill (10 minutes)

mkdir -p ~/.claude/skills/postmortem

cat > ~/.claude/skills/postmortem/SKILL.md << 'EOF'
---
name: postmortem
description: Document a bug fix as a permanent memory file
argument-hint: "[brief description of the bug]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

Document a production bug for $ARGUMENTS.

1. Ask: What broke? What was the user impact?
2. Ask: What was the root cause?
3. Ask: What was the fix?
4. Ask: What pattern should we watch for?
5. Save to the project memory directory
EOF

Step 5: Add a session alias (5 minutes)

# Add to ~/.zshrc
alias cc='claude --session-name "${1:-$(date +%b%d-%H%M)}"'

# Reload
source ~/.zshrc

That is 30 minutes. From here, add one component per day as you encounter friction. Each hook you add eliminates a manual check. Each memory file you write prevents a future correction. Each skill you create codifies a workflow you would otherwise repeat from scratch. The OS grows organically from your actual workflow, not from a template. The official Claude Code documentation covers the underlying configuration format.

What are the advanced patterns worth knowing?

Agent Teams for parallel execution

Claude Code supports an experimental Agent Teams mode (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) that allows multiple agents to coordinate on a shared task. I use this for the /review skill: four reviewer agents (security, backend, frontend, QA) run in parallel on the same diff, each with their own domain expertise. The combined review takes 45-60 seconds instead of the 3-4 minutes it would take sequentially.

Audit log rotation

The audit log (~/.claude/audit.jsonl) grows quickly with heavy use -- approximately 5-10MB per week. A cron job runs weekly to gzip and archive old logs with 30-day retention:

# Crontab entry
0 0 * * 0 ~/.claude/rotate-audit-log.sh

# The rotation script gzips the current log and starts fresh
# 30 days of compressed logs use approximately 50MB total

MCP server pruning

I started with 33 MCP servers connected. After measuring actual usage over 4 weeks, I pruned to 11 active servers. Each unused MCP server consumes connection overhead and token budget for tool descriptions. The pruning reduced session startup time by approximately 0.8 seconds and saved roughly 2,000 tokens per session in tool description overhead. Rule of thumb: if you have not used an MCP server in 2 weeks, disable it.

What are the pitfalls to avoid?

1. Over-engineering on day one. Start with the 30-minute kit. Add complexity only when you feel specific friction. Building all 20 agents before you understand your workflow produces agents that do not match your actual needs.
2. Memory file sprawl. Without the index file (MEMORY.md), Claude loads every memory file at session start, consuming context window. Keep the index curated. Archive stale memory files to a subdirectory.
3. Hook performance. Heavy hooks (like running full test suites on every file save) make Claude feel sluggish. Keep hooks under 2 seconds. Move expensive checks to skills or agents that run on demand.
4. Agent OOM. Three concurrent background agents is the safe limit on a 16GB machine. Five agents caused git corruption, killed processes, and disconnected MCP servers in my testing. Respect the limit.
5. Treating Claude Code like an IDE. It is not Cursor. It is not VS Code. It is a terminal-native agent that excels at multi-file orchestration, background tasks, and complex workflows. Trying to use it for inline autocomplete misses its strengths entirely.

Frequently Asked Questions

How long does it take to set up a full Claude Code OS like this?

Approximately 2 weeks of incremental work, adding 1-2 components per day alongside normal development. The starter kit takes 30 minutes and covers 60% of the value. The remaining 40% accumulates organically as you encounter specific friction points in your workflow. Do not try to build all 44 components in a single session.

Does this work with Claude Code on a team or just solo developers?

The memory and skills directories can be committed to your repo's .claude/ folder, making them shared across the team. Hooks in ~/.claude/settings.json are per-machine. In practice, teams share skills and memory files via git while each developer maintains their own hooks and aliases. The postmortem and wrong-tracking skills are especially valuable on teams because they create a shared knowledge base of past mistakes.

What is the token cost impact of the memory system?

Memory files add approximately 15-20% to token usage per session. My 50+ memory files total roughly 45,000 words, but Claude reads the index file first and only loads relevant files per task. At current API pricing, the additional cost is approximately $30-50/month for heavy daily use (8+ hours). The ROI from eliminated context-setting and reduced correction cycles far exceeds this cost.

Can I use this setup with Cursor or GitHub Copilot instead?

The memory system (markdown files in a project directory) works with any AI tool that reads project files. The skills, hooks, and agents are Claude Code-specific features with no direct equivalent in Cursor or Copilot. However, the philosophy -- treating your AI tool as a junior engineer you onboard with SOPs and institutional knowledge -- applies universally regardless of which tool you use.

What happens when Claude Code updates and breaks my hooks or skills?

In 6 months of daily use across 15+ Claude Code version updates (v2.1.72 through v2.1.91), I have had zero breaking changes to hooks or skills. The configuration format has been stable. Agents and skills are plain Markdown files -- they are version-agnostic. The main risk is new features that duplicate your custom setup, in which case you simplify by removing your custom version in favor of the built-in one.

Dinesh Challa is an AI Product Manager building production software with Claude Code. Follow him on LinkedIn.

Published April 11, 2026. Part of a series on Claude Code configuration and AI-assisted development workflows. Built from 6 months of daily production use on a SaaS application with 189 API routes, 65+ database tables, and 206 modules.