Guía práctica de Rules, Skills y Agents de Claude Code

Las extensiones de Claude Code no son todas el mismo tipo de prompt. Rules son instrucciones que se aplican continuamente, Skills son procedimientos de trabajo reutilizables de forma repetida y Agents son ejecutores por función que trabajan en contextos separados. Distinguir correctamente estas tres funciones permite reducir la repetición de prompts y, al mismo tiempo, gestionar de forma eficiente el contexto de la conversación principal.

Este documento se basa en la configuración a nivel de proyecto. Dado que los metadatos o las pantallas compatibles pueden variar según la versión de Claude Code, los campos que no funcionen deben comprobarse de nuevo en la documentación oficial de la versión instalada.

Paso 1: Definir el directorio .claude y el alcance de la configuración

Las Rules, Skills y Agents que se compartirán en un proyecto suelen colocarse dentro de .claude, en la raíz del repositorio.

my-project/
├── .claude/
│   ├── rules/
│   │   ├── code-style.md
│   │   └── api.md
│   ├── skills/
│   │   └── fix-issue/
│   │       └── SKILL.md
│   └── agents/
│       ├── code-reviewer.md
│       └── test-runner.md
├── src/
└── package.json

Los directorios pueden crearse de la siguiente manera.

mkdir -p .claude/rules
mkdir -p .claude/skills/fix-issue
mkdir -p .claude/agents

Dos malentendidos sobre .claude

1. .claude no es obligatorio para todas las instrucciones de Claude Code. Las instrucciones del proyecto también pueden gestionarse mediante CLAUDE.md en la raíz o .claude/CLAUDE.md, mientras que la configuración personal del usuario puede colocarse dentro de ~/.claude, en el directorio de inicio.
2. Según el sistema operativo, los nombres de archivo distinguen entre mayúsculas y minúsculas. Es más seguro crear el archivo de entrada de una Skill como SKILL.md, en mayúsculas, de acuerdo con el formato oficial. Si se guarda como skill.md, podría no ser reconocido.

Criterios para elegir entre configuración de proyecto y personal

Solo deben enviarse a Git los archivos que utilizará todo el equipo. No deben registrarse en Rules ni Skills claves secretas, tokens o contraseñas de servidores internos.

Paso 2: Crear instrucciones persistentes con Rules

Rules es una función para gestionar las instrucciones del proyecto que Claude debe consultar al trabajar, dividiéndolas en varios archivos Markdown. Entre las reglas situadas bajo .claude/rules, los archivos sin una condición paths se cargan como instrucciones del proyecto, mientras que los que especifican condiciones de ruta se aplican al trabajar con archivos relacionados.

Ejemplo de una Rule básica

Puede crearse .claude/rules/code-style.md de la siguiente manera.

# Principios de escritura de código

- El nuevo código de la aplicación debe escribirse en TypeScript.
- En las funciones públicas deben explicarse los valores de entrada, los valores de retorno y las condiciones de fallo.
- No se deben eliminar pruebas existentes para ocultar fallos.
- Después de realizar cambios, deben ejecutarse las pruebas relacionadas y la comprobación de tipos.
- Las explicaciones deben escribirse en coreano, pero los identificadores de código deben seguir las convenciones de nomenclatura existentes.

Una buena Rule puede verificarse. “Escribir código elegante” es menos claro que “ejecutar npm test y npm run typecheck después de realizar cambios”.

Rule que se aplica solo a rutas específicas

Si las reglas del frontend y del backend son distintas, puede limitarse el alcance mediante paths en el YAML front matter.

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.ts"
---

# Reglas de la API

- Todas las entradas de la API deben validarse mediante un esquema.
- Los fallos de autenticación y la falta de permisos deben tratarse como errores diferentes.
- Si se modifica un endpoint, también deben actualizarse las pruebas de API correspondientes.

Las reglas por ruta reducen el problema de que instrucciones innecesarias ocupen el contexto de todos los trabajos.

Contenido que no debe incluirse en Rules

• Procedimientos de migración que se ejecutarán una sola vez
• Requisitos detallados necesarios únicamente para una incidencia específica
• Instrucciones absolutas que entren en conflicto entre sí
• Frases extensas que repitan contenido ya impuesto por el código o la configuración del linter
• Datos sensibles como contraseñas, claves de API o información de clientes

Rules no es un “mecanismo mágico de garantía que siempre se cumple”. Si las instrucciones son ambiguas o contradictorias, los resultados pueden variar, por lo que deben utilizarse conjuntamente medios de verificación deterministas, como pruebas, linters y controles de permisos.

Paso 3: Automatizar procedimientos repetitivos con Skills

Una Skill agrupa una descripción, un procedimiento de trabajo, las herramientas necesarias y materiales auxiliares en una única unidad reutilizable. La estructura básica de una Skill de proyecto es .claude/skills/<skill-name>/SKILL.md y, si es necesario, pueden añadirse plantillas o scripts en el mismo directorio.

A diferencia de Rules, una Skill se utiliza cuando resulta necesaria para un trabajo específico. Claude puede seleccionarla automáticamente a partir de su descripción, o el usuario puede invocarla explícitamente con el formato /<skill-name>. No funciona necesariamente solo de manera manual.

Ejemplo de una Skill para corregir incidencias

Un ejemplo de .claude/skills/fix-issue/SKILL.md es el siguiente.

---
name: fix-issue
description: Reproduce un error, delimita su causa y después realiza una corrección mínima y pruebas de regresión.
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Edit, Bash(npm test:*)
---

# Procedimiento para corregir incidencias

Incidencia objetivo: $ARGUMENTS

1. Investiga el código relacionado y las pruebas existentes.
2. Antes de modificarlo, resume el método de reproducción y el comportamiento esperado.
3. Explica la causa raíz en un párrafo.
4. Aplica la modificación con el menor alcance posible.
5. Añade una prueba de regresión o comprueba que las pruebas existentes verifican el problema.
6. Ejecuta las pruebas permitidas y resume los resultados.
7. Informa de los archivos modificados, los riesgos restantes y los elementos que requieren comprobación manual.

Esta Skill puede invocarse de la siguiente manera.

/fix-issue El problema por el que la foto de perfil no se actualiza después de iniciar sesión

disable-model-invocation: true resulta útil cuando se quiere impedir que Claude ejecute esta Skill por iniciativa propia y limitarla a la invocación directa por parte del usuario. Los campos de front matter compatibles pueden variar según la versión de Claude Code.

Ejemplo de una Skill que prioriza el diseño

Si se quiere que primero se cree un documento de diseño en lugar de empezar a programar de inmediato, puede incluirse en una Skill el siguiente flujo.

1. Separar los requisitos de los aspectos ambiguos.
2. Investigar la estructura existente y los módulos reutilizables.
3. Diseñar el flujo de datos, las interfaces y las condiciones de fallo.
4. Crear un documento de diseño bajo docs/design/.
5. Implementar después de comprobar la aprobación del usuario o las condiciones de aprobación especificadas.
6. Presentar las pruebas y el método de reversión.

Condiciones de una buena Skill

• La entrada y el resultado final están claros.
• Se especifican el orden del procedimiento y las condiciones de interrupción.
• Solo se permiten las herramientas necesarias.
• Los materiales de referencia extensos se separan en archivos independientes.
• Si se produce un fallo, se indica que debe informarse de él en lugar de continuar arbitrariamente.
• Una sola Skill no tiene demasiados objetivos.

Los trabajos repetitivos con un inicio y un final claros, como la creación de commits, la revisión de código, la comprobación de versiones y el diseño de API, son adecuados para Skills.

Paso 4: Separar funciones y contextos con Agents

Los subagentes de Claude Code desempeñan una función específica en un contexto separado y devuelven los resultados a la conversación principal. Son útiles cuando no se desea acumular en el contexto principal grandes cantidades de resultados de búsqueda o registros de pruebas.

Los agentes del proyecto suelen definirse en .claude/agents/<agent-name>.md. Es posible consultar o gestionar los agentes mediante el comando /agents, y también puede solicitarse en lenguaje natural que una tarea se delegue en un agente específico.

Ejemplo de un agente de revisión de código

Puede crearse .claude/agents/code-reviewer.md de la siguiente manera.

---
name: code-reviewer
description: Revisor centrado en la lectura que examina el código modificado para detectar defectos, riesgos de seguridad y pruebas ausentes
tools: Read, Grep, Glob, Bash
model: sonnet
---

Eres un agente dedicado a la revisión de código.

Realiza la revisión con el siguiente orden de prioridades.

1. Defectos que puedan provocar fallos reales o pérdida de datos
2. Problemas de seguridad relacionados con la autenticación, los permisos y la validación de entradas
3. Problemas de concurrencia, transacciones y gestión de errores
4. Ausencia de pruebas que verifiquen los requisitos
5. Estructuras que reduzcan considerablemente la mantenibilidad

Cada hallazgo debe incluir la ruta del archivo, el fundamento, las condiciones en las que se produce y la orientación para una corrección mínima.
No informes como defectos las preferencias de estilo que carezcan de fundamento.
No modifiques directamente el código; devuelve únicamente los resultados de la revisión.

Puede solicitarse de la siguiente manera.

Pide al agente code-reviewer que revise los cambios de la rama actual.

Diferencias entre Skill y Agent

Agents y Agent Teams son diferentes

El hecho de que un subagente normal utilice un contexto separado no significa que los agentes puedan conversar libremente entre sí. Por lo general, los subagentes siguen una estructura de delegación en la que realizan la tarea asignada y devuelven los resultados al agente principal. La función Agent Teams, en la que varias sesiones independientes intercambian mensajes entre sí, es una función distinta, y su estado de compatibilidad y sus condiciones de activación deben comprobarse en la documentación oficial.

Si se diseña un flujo de trabajo suponiendo que un agente seguirá creando otros agentes en cadena, puede fallar debido a las restricciones de versión o permisos. Es más seguro comenzar con una estructura sencilla en la que el agente principal distribuya el trabajo entre subagentes según sus funciones y sintetice los resultados.

Paso 5: Verificar la carga, los permisos y la calidad

No debe suponerse que los archivos de configuración funcionan según lo previsto solo por haberlos creado. Cada componente debe verificarse por separado mediante tareas pequeñas.

Orden de verificación recomendado

1. Comprobar Rules: solicitar tareas tanto para archivos a los que se aplican las reglas como para archivos a los que no se aplican, con el fin de comprobar las condiciones de ruta.
2. Comprobar Skills: invocar explícitamente una Skill y comprobar que funcionan los argumentos de entrada, los resultados y las condiciones de interrupción.
3. Comprobar Agents: asignar tareas de bajo riesgo, como una revisión de solo lectura, y comprobar el formato de los resultados.
4. Comprobar permisos: revisar que las herramientas con capacidad de realizar cambios, como Bash y Edit, solo se hayan concedido a las configuraciones que realmente las necesiten.
5. Verificación automática: comprobar de manera independiente los resultados de la IA mediante pruebas, comprobaciones de tipos, linters y análisis de seguridad.

Elementos que deben comprobarse en caso de fallo

• ¿Se encuentra .claude en la raíz real del proyecto?
• ¿El nombre del archivo de la Skill es exactamente SKILL.md?
• ¿La Skill tiene la estructura .claude/skills/<nombre>/SKILL.md?
• ¿El archivo del Agent es un archivo Markdown situado directamente bajo .claude/agents?
• ¿El inicio y el final del YAML front matter están delimitados con ---?
• ¿name y description son lo bastante específicos como para diferenciar el trabajo?
• ¿Los patrones de ruta coinciden con la estructura real del proyecto?
• ¿La versión instalada de Claude Code admite los metadatos utilizados?
• ¿Los permisos de las herramientas o las políticas de la organización están bloqueando la ejecución?

Por qué deben diseñarse conjuntamente el presupuesto de contexto y la seguridad

El propósito de Rules, Skills y Agents no consiste únicamente en añadir funciones. También son medios de ingeniería de contexto que permiten controlar qué información se incorpora al contexto y en qué momento.

Si las reglas son demasiado extensas, instrucciones ajenas al trabajo actual ocuparán el contexto y aumentará la posibilidad de conflictos. Por el contrario, si la exploración y el análisis de registros se asignan a subagentes, en la conversación principal pueden conservarse únicamente las conclusiones y sus fundamentos.

Desde el punto de vista de la seguridad, son importantes los siguientes principios.

• Revisar Rules y Skills igual que cualquier otro código del repositorio.
• Leer antes de ejecutar los archivos de Agent o Skill recibidos de fuentes externas.
• Minimizar los permisos para ejecutar comandos del shell, acceder a la red y modificar archivos.
• No confiar automáticamente en los comandos incluidos en la entrada del usuario o en el contenido de una incidencia.
• Incluir una etapa de aprobación humana para despliegues, eliminaciones, pagos y migraciones de datos.
• No almacenar información secreta en archivos de prompts; utilizar un sistema independiente de gestión de secretos.

Qué función debe elegirse

Puede decidirse rápidamente mediante las siguientes preguntas.

• ¿Deben seguirla todos los trabajos relacionados? → Rule
• ¿Es un procedimiento repetitivo con un inicio y un final? → Skill
• ¿Se necesitan una función separada y un contexto independiente? → Agent
• ¿Debe ejecutarse un comando determinista antes o después de un evento específico? → Considerar un Hook

Por ejemplo, “usar TypeScript” es una Rule, mientras que “realizar desde la reproducción del error hasta las pruebas de regresión” es una Skill. “Leer los cambios e informar únicamente de los defectos de seguridad” es apropiado para un Agent. Para acciones vinculadas a un evento específico, como ejecutar obligatoriamente un formateador después de editar un archivo, Hooks puede resultar más adecuado.

La configuración más estable consiste en combinar las tres funciones en lugar de considerarlas competidoras. Rule proporciona criterios comunes, Skill ejecuta procedimientos estándar y Agent separa los trabajos con un contexto amplio, como la investigación y la revisión; después, las pruebas y Hooks complementan la verificación determinista.