Claude Code Extensions: Organizing 139 Skills and Hooks

After building 95 hooks, 44 skills, 85 commands, and 11 rule files for Claude Code, I’ve learned that choosing the wrong abstraction wastes more time than building the wrong feature. This post is part of the AI engineering work documenting how agent infrastructure matures in production. A skill that should have been a rule bloated my context by 40%. A command that should have been a skill required me to remember to type /fastapi every time I touched an API endpoint.¹

Claude Code has four extension types, each solving a different problem: Rules for always-on invariants, Skills for auto-invoked domain expertise, Commands for user-triggered workflows, and Subagents for isolated task execution. The decision framework is simple, but recognizing when you have chosen the wrong abstraction and migrating is the hard part that saves the most time.

TL;DR

Claude Code provides four ways to extend behavior: Commands (user-triggered prompts), Skills (auto-invoked context), Subagents (delegated task executors), and Rules (always-on constraints). After organizing 139 extensions, I’ve found that the decision framework is simple: Rules for invariants, Skills for domain expertise, Commands for workflows, Subagents for isolation. The hard part is recognizing when you’ve chosen wrong and migrating.

The Four Abstractions (With Real Examples)

Commands: “/commit” and 84 Others

Commands activate when I type /command-name. Each expands into a prompt template.²

My 85 commands include /commit (smart git commit), /review (launch code review agents), /deploy (deployment checklist), /publish-check (blog pre-publish validation), and /deliberate (multi-agent research).

The mistake I made: I built /fastapi as a command that injected FastAPI patterns on demand. The problem: I forgot to type it half the time. Every forgotten invocation meant the agent missed patterns I wanted enforced. The fix was migrating /fastapi to a Skill with auto-activation.

Skills: 44 Auto-Activated Knowledge Modules

Skills activate automatically when the conversation matches the skill’s description. I never type a command; the system injects relevant expertise based on context.³ For a step-by-step walkthrough of creating your own, see building custom skills.

---
description: FastAPI backend development patterns and conventions
---
# FastAPI Skill
When working on FastAPI endpoints, follow these patterns...

My 44 skills cover: - Domain knowledge (8): FastAPI, SwiftUI, HTMX/Alpine, database, testing, debugging, architecture, security - Blog infrastructure (7): blog-writer-core, blog-evaluator, citation-verifier, SEO playbook - Philosophy/quality (5): Shokunin (Jiro), No Shortcuts, Rubin essence, design principles - Multi-agent (3): deliberation, review, content creation - Project-specific (4): personal site content, ResumeGeni blog, Obsidian capture

The 40% context bloat incident: Early on, I put my full FastAPI patterns guide (800 lines) into a Rule file. Rules load into every session. When I worked on iOS apps, CSS, or blog content, 800 lines of irrelevant FastAPI patterns consumed context tokens. Moving the content to a Skill with the description “FastAPI backend development” solved the problem: the skill only loaded during API work.⁴

Subagents: Isolated Reviewers

Subagents run in their own context window with restricted tool access and independent permissions.⁵

My subagents include security-reviewer (read-only access, OWASP vulnerability scanning), test-runner (runs tests, analyzes failures), and conventions-reviewer (project standards checking).

Why isolation matters: During code review, the reviewer should not be able to edit files. A Skill can inject review knowledge, but the review still happens in the main context with full write permissions. A Subagent enforces read-only access architecturally.

Rules: 11 Always-On Constraint Files

Rules load into every conversation automatically. My 11 rule files cover:⁶

~/.claude/rules/
├── security.md        # Never commit secrets, parameterized queries
├── git-workflow.md    # Conventional commits, branch naming
├── corrections.md     # Always use Claude (not OpenAI), current date
├── quality-loop.md    # Quality review loop, pride check
├── api-design.md      # REST conventions, response format
├── testing.md         # pytest conventions, coverage targets
└── aio.md             # AI Overview optimization for web content

The sizing lesson: My rules total roughly 180 lines across 11 files. Every line loads into every session. I originally had 400+ lines before I migrated topic-specific content to Skills. The 180-line rule set covers genuine invariants (security constraints, git workflow, corrections). Everything else belongs in Skills.

The Decision Framework

The Migration Pattern

My .claude/ structure evolved through three phases:

Phase 1 (Month 1-2): Everything in Rules. 400+ lines of always-loaded context. iOS patterns, FastAPI patterns, design guidelines, testing standards. Context was bloated in every session.

Phase 2 (Month 3-4): Migrated topic-specific content to Skills. Rules dropped to 200 lines. Skills grew to 20+ directories. Context bloat dropped by 40%.

Phase 3 (Month 5+): Added Subagents for tasks requiring isolation (code review, security audit). Commands stabilized at 85 for explicit workflows. Skills grew to 44 as I added domain-specific expertise.⁷

The lesson: start with Rules (cheap, always available), discover what’s topic-specific (migrate to Skills), and add Subagents only when you need isolation. Context Is Architecture explores how this migration pattern reflects a deeper principle: context structure is the architectural decision that shapes all agent behavior. The hooks tutorial covers the lifecycle event handlers that complement these four abstractions. Taken together, these extension types form the foundation of Claude Code as infrastructure — the full pattern is documented in the Claude Code guide.

Skills Powering Subagents

A powerful pattern: inject Skills into Subagent context using the skills frontmatter field:

---
description: Code reviewer with security expertise
allowed-tools: [Read, Grep, Glob]
skills: [security, testing-philosophy]
---
Review code for quality, security, and test coverage...

The security and testing-philosophy skills inject their content into the subagent’s system prompt. The reviewer gets specialized knowledge within its isolated, read-only context.⁸

My review pipeline uses this pattern: three subagents (correctness-reviewer, security-reviewer, conventions-reviewer) each receive different skill injections. The correctness reviewer gets debugging-philosophy. The security reviewer gets the security rule set. The conventions reviewer gets the project’s coding standards.

My Production Architecture

~/.claude/
├── commands/     # 85 — User-triggered workflows
│   ├── commit.md, review.md, deploy.md
│   ├── publish-check.md, deliberate.md
│   └── morning.md, analytics.md, plan.md
│
├── skills/       # 44 — Auto-invoked expertise
│   ├── fastapi/, swiftui/, htmx-alpine/
│   ├── blog-writer-core/, citation-verifier/
│   └── jiro/, no-shortcuts/, rubin-essence/
│
├── agents/       # Isolated task executors
│   ├── security-reviewer.md
│   ├── correctness-reviewer.md
│   └── conventions-reviewer.md
│
├── rules/        # 11 files, ~180 lines — Always-on constraints
│   ├── security.md, git-workflow.md
│   ├── corrections.md, quality-loop.md
│   └── api-design.md, testing.md, aio.md
│
└── hooks/        # 95 — Lifecycle event handlers
    ├── git-safety-guardian.sh
    ├── recursion-guard.sh
    └── blog-quality-gate.sh

Key Takeaways

For solo developers: - Start with Rules for project-specific standards (keep under 200 lines total) - Add Skills for your most-used technology stacks; auto-activation eliminates the “forgot to invoke” problem - Create Commands for your three most common workflows first - Add Subagents only when you need tool restriction or context isolation

For teams: - Standardize Rules at the project level for team-wide consistency - Share Skills via a common repository; the portability of Skills across projects is their primary advantage over project-level configuration

FAQ

What is the difference between Claude Code commands, skills, rules, and subagents?

Commands are user-triggered prompts activated by typing /command-name. Skills are auto-invoked context modules that activate when the conversation matches their description. Rules are always-on constraints that load into every session. Subagents are isolated task executors with restricted tool access and independent context windows. The decision framework: Rules for invariants, Skills for domain expertise, Commands for workflows, Subagents for isolation.

How many Claude Code extensions is too many?

The number matters less than the categorization. My system runs 95 hooks, 44 skills, 85 commands, and 11 rule files without performance issues because each type loads differently. Rules (always-on) should stay under 200 lines total. Skills load only when relevant, so they can grow freely. Commands activate on demand. The problem is not quantity but misclassification: putting topic-specific content in Rules instead of Skills caused a 40% context bloat that was immediately solved by migrating to the correct abstraction.

Should I start with rules or skills when setting up Claude Code?

Start with Rules for genuine invariants (security constraints, git workflow, corrections) that apply to every session regardless of topic. Keep them under 200 lines total. Then add Skills for your most-used technology stacks, where auto-activation eliminates the “forgot to invoke” problem. Add Commands for your three most common workflows. Add Subagents last, only when you need tool restriction or context isolation for tasks like code review.

How do you prevent context bloat in Claude Code sessions?

Migrate topic-specific content from Rules to Skills. Rules load into every session; Skills load only when the conversation topic matches. My Rules dropped from 400+ lines to 180 lines by moving FastAPI patterns, iOS patterns, and design guidelines into Skills with descriptive frontmatter. The 40% context reduction was immediate. The principle: if the content is not relevant to every session, it does not belong in Rules.

Can Claude Code skills be shared across projects?

Yes. Skills stored in ~/.claude/skills/ are available across all projects. Project-specific skills go in .claude/skills/ within the project directory. The portability of Skills across projects is their primary advantage over project-level configuration. Teams can share Skills via a common repository, giving every team member access to the same domain expertise and quality standards.

References