Commands, Skills, Subagents, Rules: What I Learned Organizing 139 Extensions

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. 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.¹

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.³

---
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.

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

References