Comandos, Skills, Subagentes, Reglas: Lo que aprendí organizando 139 extensiones

Después de construir 95 hooks, 44 skills, 85 comandos y 11 archivos de reglas para Claude Code, he aprendido que elegir la abstracción incorrecta desperdicia más tiempo que construir la función equivocada. Un skill que debería haber sido una regla infló mi contexto en un 40%. Un comando que debería haber sido un skill me obligaba a recordar escribir /fastapi cada vez que tocaba un endpoint de API.¹

TL;DR

Claude Code ofrece cuatro formas de extender su comportamiento: Comandos (prompts activados por el usuario), Skills (contexto invocado automáticamente), Subagentes (ejecutores de tareas delegadas) y Reglas (restricciones siempre activas). Después de organizar 139 extensiones, he descubierto que el marco de decisión es simple: Reglas para invariantes, Skills para conocimiento de dominio, Comandos para flujos de trabajo, Subagentes para aislamiento. Lo difícil es reconocer cuándo se ha elegido mal y migrar.

Las cuatro abstracciones (con ejemplos reales)

Comandos: “/commit” y 84 más

Los comandos se activan cuando escribo /command-name. Cada uno se expande en una plantilla de prompt.²

Mis 85 comandos incluyen /commit (commit inteligente de git), /review (lanzar agentes de revisión de código), /deploy (lista de verificación de despliegue), /publish-check (validación previa a la publicación del blog) y /deliberate (investigación multiagente).

El error que cometí: Construí /fastapi como un comando que inyectaba patrones de FastAPI bajo demanda. El problema: olvidaba escribirlo la mitad de las veces. Cada invocación olvidada significaba que el agente no aplicaba los patrones que quería que se cumplieran. La solución fue migrar /fastapi a un Skill con activación automática.

Skills: 44 módulos de conocimiento con activación automática

Los skills se activan automáticamente cuando la conversación coincide con la descripción del skill. Nunca escribo un comando; el sistema inyecta la experiencia relevante según el contexto.³

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

Mis 44 skills cubren: - Conocimiento de dominio (8): FastAPI, SwiftUI, HTMX/Alpine, base de datos, testing, depuración, arquitectura, seguridad - Infraestructura de blog (7): blog-writer-core, blog-evaluator, citation-verifier, SEO playbook - Filosofía/calidad (5): Shokunin (Jiro), No Shortcuts, Rubin essence, principios de diseño - Multiagente (3): deliberación, revisión, creación de contenido - Específicos de proyecto (4): contenido del sitio personal, blog de ResumeGeni, captura en Obsidian

El incidente del 40% de inflación de contexto: Al principio, puse mi guía completa de patrones de FastAPI (800 líneas) en un archivo de reglas. Las reglas se cargan en cada sesión. Cuando trabajaba en aplicaciones iOS, CSS o contenido de blog, 800 líneas de patrones irrelevantes de FastAPI consumían tokens de contexto. Mover el contenido a un Skill con la descripción “FastAPI backend development” resolvió el problema: el skill solo se cargaba durante el trabajo con API.⁴

Subagentes: revisores aislados

Los subagentes se ejecutan en su propia ventana de contexto con acceso restringido a herramientas y permisos independientes.⁵

Mis subagentes incluyen security-reviewer (acceso de solo lectura, escaneo de vulnerabilidades OWASP), test-runner (ejecuta pruebas, analiza fallos) y conventions-reviewer (verificación de estándares del proyecto).

Por qué importa el aislamiento: Durante la revisión de código, el revisor no debería poder editar archivos. Un Skill puede inyectar conocimiento de revisión, pero la revisión aún ocurre en el contexto principal con permisos completos de escritura. Un Subagente impone el acceso de solo lectura de forma arquitectónica.

Reglas: 11 archivos de restricciones siempre activos

Las reglas se cargan en cada conversación automáticamente. Mis 11 archivos de reglas cubren:⁶

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

La lección del dimensionamiento: Mis reglas suman aproximadamente 180 líneas en 11 archivos. Cada línea se carga en cada sesión. Originalmente tenía más de 400 líneas antes de migrar el contenido específico por tema a Skills. El conjunto de reglas de 180 líneas cubre invariantes genuinos (restricciones de seguridad, flujo de trabajo de git, correcciones). Todo lo demás pertenece a los Skills.

El marco de decisión

El patrón de migración

Mi estructura .claude/ evolucionó a través de tres fases:

Fase 1 (Mes 1-2): Todo en Reglas. Más de 400 líneas de contexto siempre cargado. Patrones de iOS, patrones de FastAPI, guías de diseño, estándares de testing. El contexto estaba inflado en cada sesión.

Fase 2 (Mes 3-4): Migré el contenido específico por tema a Skills. Las Reglas bajaron a 200 líneas. Los Skills crecieron a más de 20 directorios. La inflación de contexto se redujo en un 40%.

Fase 3 (Mes 5+): Agregué Subagentes para tareas que requerían aislamiento (revisión de código, auditoría de seguridad). Los Comandos se estabilizaron en 85 para flujos de trabajo explícitos. Los Skills crecieron a 44 a medida que agregué experiencia específica por dominio.⁷

La lección: comience con Reglas (económicas, siempre disponibles), descubra qué es específico por tema (migre a Skills) y agregue Subagentes solo cuando necesite aislamiento.

Skills potenciando Subagentes

Un patrón poderoso: inyectar Skills en el contexto del Subagente usando el campo skills del frontmatter:

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

Los skills security y testing-philosophy inyectan su contenido en el prompt del sistema del subagente. El revisor obtiene conocimiento especializado dentro de su contexto aislado y de solo lectura.⁸

Mi pipeline de revisión usa este patrón: tres subagentes (correctness-reviewer, security-reviewer, conventions-reviewer) reciben cada uno diferentes inyecciones de skills. El revisor de corrección recibe debugging-philosophy. El revisor de seguridad recibe el conjunto de reglas de seguridad. El revisor de convenciones recibe los estándares de codificación del proyecto.

Mi arquitectura en producción

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

Conclusiones clave

Para desarrolladores independientes: - Comience con Reglas para estándares específicos del proyecto (mantenga menos de 200 líneas en total) - Agregue Skills para las tecnologías que más utiliza; la activación automática elimina el problema de “olvidé invocarlo” - Cree Comandos para sus tres flujos de trabajo más comunes primero - Agregue Subagentes solo cuando necesite restricción de herramientas o aislamiento de contexto

Para equipos: - Estandarice las Reglas a nivel de proyecto para consistencia en todo el equipo - Comparta Skills mediante un repositorio común; la portabilidad de los Skills entre proyectos es su principal ventaja sobre la configuración a nivel de proyecto

Referencias