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.³ Para un recorrido paso a paso sobre cómo crear los suyos, consulte crear Skills personalizados.

---
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. El contexto es arquitectura explora cómo este patrón de migración refleja un principio más profundo: la estructura del contexto es la decisión arquitectónica que moldea todo el comportamiento del agente. El tutorial de hooks cubre los manejadores de eventos del ciclo de vida que complementan estas cuatro abstracciones. En conjunto, estos tipos de extensión forman la base de Claude Code como infraestructura: el patrón completo está documentado en la guía de Claude Code.

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

Preguntas frecuentes

¿Cuál es la diferencia entre los comandos, skills, reglas y subagentes de Claude Code?

Los Comandos son prompts activados por el usuario que se ejecutan al escribir /command-name. Los Skills son módulos de contexto invocados automáticamente que se activan cuando la conversación coincide con su descripción. Las Reglas son restricciones siempre activas que se cargan en cada sesión. Los Subagentes son ejecutores de tareas aislados, con acceso restringido a herramientas y ventanas de contexto independientes. El marco de decisión: Reglas para invariantes, Skills para conocimiento de dominio, Comandos para flujos de trabajo, Subagentes para aislamiento.

¿Cuántas extensiones de Claude Code son demasiadas?

El número importa menos que la categorización. Mi sistema ejecuta 95 hooks, 44 skills, 85 comandos y 11 archivos de reglas sin problemas de rendimiento, porque cada tipo se carga de forma distinta. Las Reglas (siempre activas) deben mantenerse por debajo de 200 líneas en total. Los Skills solo se cargan cuando son relevantes, así que pueden crecer libremente. Los Comandos se activan bajo demanda. El problema no es la cantidad, sino la clasificación errónea: poner contenido específico por tema en Reglas en lugar de Skills provocó una inflación de contexto del 40% que se resolvió de inmediato al migrar a la abstracción correcta.

¿Debo empezar con reglas o con skills al configurar Claude Code?

Comience con Reglas para los invariantes genuinos (restricciones de seguridad, flujo de trabajo de git, correcciones) que se aplican a cada sesión sin importar el tema. Manténgalas por debajo de 200 líneas en total. Después agregue Skills para las tecnologías que más utiliza, donde la activación automática elimina el problema de “olvidé invocarlo”. Agregue Comandos para sus tres flujos de trabajo más comunes. Deje los Subagentes para el final, solo cuando necesite restricción de herramientas o aislamiento de contexto en tareas como la revisión de código.

¿Cómo se evita la inflación de contexto en las sesiones de Claude Code?

Migre el contenido específico por tema de las Reglas a los Skills. Las reglas se cargan en cada sesión; los skills solo se cargan cuando el tema de la conversación coincide. Mis reglas bajaron de más de 400 líneas a 180 al mover los patrones de FastAPI, los patrones de iOS y las guías de diseño a Skills con un frontmatter descriptivo. La reducción de contexto del 40% fue inmediata. El principio: si el contenido no es relevante para cada sesión, no pertenece a las Reglas.

¿Se pueden compartir los skills de Claude Code entre proyectos?

Sí. Los Skills almacenados en ~/.claude/skills/ están disponibles en todos los proyectos. Los skills específicos de un proyecto van en .claude/skills/ dentro del directorio del proyecto. La portabilidad de los Skills entre proyectos es su principal ventaja sobre la configuración a nivel de proyecto. Los equipos pueden compartir Skills mediante un repositorio común, de modo que cada integrante acceda al mismo conocimiento de dominio y a los mismos estándares de calidad.

Referencias