Skills reutilizables

Qué son las skills

Las skills son instrucciones reutilizables empaquetadas como archivos markdown que extienden las capacidades de Claude Code. Cada skill se define en un archivo SKILL.md con metadatos en frontmatter YAML y contenido en markdown que Claude sigue cuando la skill se activa.

A diferencia de los archivos CLAUDE.md, que proporcionan contexto general del proyecto y se inyectan siempre, las skills se cargan bajo demanda: Claude las utiliza cuando detecta que son relevantes para la tarea actual, o el usuario las invoca directamente con /nombre-skill.

Las skills siguen el estándar abierto Agent Skills, compatible con múltiples herramientas de IA. Claude Code amplía este estándar con control de invocación, ejecución en subagentes e inyección de contexto dinámico.

Las skills complementan a CLAUDE.md y a los hooks. CLAUDE.md define el contexto general del proyecto, los hooks automatizan acciones deterministas, y las skills proporcionan instrucciones especializadas que Claude aplica cuando la tarea lo requiere.

Crear una skill

Cada skill es un directorio que contiene al menos un archivo SKILL.md. El directorio puede incluir archivos de soporte adicionales como plantillas, ejemplos o scripts.

mi-skill/
  SKILL.md           # Instrucciones principales (obligatorio)
  template.md        # Plantilla que Claude rellena (opcional)
  examples/
    sample.md        # Ejemplo de salida esperada (opcional)
  scripts/
    validate.sh      # Script que Claude puede ejecutar (opcional)

Un SKILL.md mínimo tiene dos partes: el frontmatter YAML entre marcadores --- y el contenido markdown con las instrucciones:

---
name: code-review
description: Reviews code for quality, security, and best practices. Use when reviewing code changes or analyzing PRs.
---

When reviewing code, check for:

1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

El campo name se convierte en el comando slash que invoca la skill (/code-review). El campo description es lo que Claude lee para decidir cuándo activarla automáticamente.

Ubicación y alcance

Dónde se almacena la skill determina quién puede usarla:

| Ubicación | Ruta | Alcance | |---|---|---| | Personal | ~/.claude/skills/<nombre>/SKILL.md | Todos tus proyectos | | Proyecto | .claude/skills/<nombre>/SKILL.md | Solo el proyecto actual | | Plugin | <plugin>/skills/<nombre>/SKILL.md | Donde el plugin esté habilitado | | Enterprise | Configuración managed | Toda la organización |

Las skills de proyecto se suben al repositorio y las comparte todo el equipo. Las skills personales son privadas y están disponibles en cualquier proyecto de tu máquina.

Cuando skills con el mismo nombre existen en varias ubicaciones, la de mayor prioridad prevalece: enterprise > personal > proyecto.

# Crear una skill personal
mkdir -p ~/.claude/skills/explain-code

# Crear una skill de proyecto
mkdir -p .claude/skills/api-conventions

En monorepos, Claude Code descubre automáticamente skills en directorios .claude/skills/ anidados. Si estás editando un archivo en packages/frontend/, Claude Code también busca skills en packages/frontend/.claude/skills/.

Frontmatter y configuración

El frontmatter YAML controla el comportamiento de la skill. Todos los campos son opcionales excepto description, que se recomienda para que Claude sepa cuándo usarla:

| Campo | Descripción | |---|---| | name | Nombre de la skill (minúsculas y guiones). Si se omite, usa el nombre del directorio | | description | Qué hace la skill y cuándo usarla. Claude lo usa para decidir cuándo activarla | | disable-model-invocation | Si es true, solo el usuario puede invocarla (no Claude automáticamente) | | user-invocable | Si es false, se oculta del menú /. Solo Claude puede invocarla | | allowed-tools | Herramientas que Claude puede usar sin pedir aprobación cuando la skill está activa | | model | Modelo a usar cuando la skill está activa | | context | Si es fork, se ejecuta en un subagente aislado | | agent | Tipo de subagente cuando context: fork está configurado | | argument-hint | Pista de argumentos que se muestra en el autocompletado |

Control de invocación

Por defecto, tanto el usuario como Claude pueden invocar cualquier skill. Dos campos del frontmatter permiten restringir este comportamiento:

Solo invocación manual (disable-model-invocation: true): impide que Claude la active automáticamente. Es la opción adecuada para workflows con efectos secundarios como despliegues, commits o envío de mensajes.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Solo invocación por Claude (user-invocable: false): oculta la skill del menú /. Es adecuada para conocimiento de fondo que Claude debe aplicar cuando sea relevante, pero que no tiene sentido como comando manual.

---
name: legacy-system-context
description: Context about the legacy billing system
user-invocable: false
---

The legacy billing system uses a custom ORM layer...

En sesiones normales, las descripciones de las skills se cargan en el contexto para que Claude sepa qué tiene disponible, pero el contenido completo solo se carga cuando la skill se invoca. Esto mantiene el consumo de contexto bajo hasta que realmente se necesita.

Argumentos y sustituciones

Las skills aceptan argumentos que se pasan tras el nombre del comando. El placeholder $ARGUMENTS se sustituye por el texto que el usuario proporciona:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

Al ejecutar /fix-issue 123, Claude recibe "Fix GitHub issue 123 following our coding standards..."

Para acceder a argumentos individuales por posición, se usa $ARGUMENTS[N] o la forma abreviada $N:

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Ejecutar /migrate-component SearchBar React Vue sustituye $0 por SearchBar, $1 por React y $2 por Vue.

Skills bundled

Claude Code incluye varias skills preinstaladas disponibles en todas las sesiones:

• /debug [descripción]: analiza el log de depuración de la sesión actual para diagnosticar problemas. Opcionalmente, se describe el problema para enfocar el análisis.

• /batch <descripción>: orquesta cambios a gran escala en paralelo. Investiga el codebase, descompone el trabajo en unidades independientes, y lanza un agente en background por cada unidad, cada uno en un worktree de Git aislado. Cada agente implementa su unidad, ejecuta tests y abre un pull request.

• /simplify: revisa los archivos modificados recientemente buscando oportunidades de reutilización, calidad y eficiencia. Lanza tres agentes de revisión en paralelo y aplica las correcciones.

Inyección de contexto dinámico

La sintaxis !`comando` ejecuta comandos shell antes de que el contenido de la skill llegue a Claude. La salida del comando reemplaza al placeholder, de forma que Claude recibe datos reales en lugar del comando:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

Cuando se ejecuta esta skill, cada !`comando` se resuelve inmediatamente y Claude recibe la salida real del PR como contexto.

Ejecución en subagente

El campo context: fork permite ejecutar una skill en un subagente aislado con su propia ventana de contexto, sin acceso al historial de la conversación principal:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

El campo agent especifica qué tipo de subagente usar. Las opciones incluyen agentes built-in (Explore, Plan, general-purpose) o cualquier agente custom definido en .claude/agents/.

context: fork tiene sentido para skills con instrucciones de tarea explicitas. Si la skill contiene directrices generales sin una tarea concreta, el subagente recibe las directrices pero no tiene un prompt accionable, y termina sin producir resultado útil.

Restringir herramientas

El campo allowed-tools limita qué herramientas puede usar Claude cuando la skill está activa. Esto permite crear modos de solo lectura o restringir el acceso a operaciones seguras:

---
name: safe-reader
description: Read files without making changes
allowed-tools: Read, Grep, Glob
---

Explore the codebase and answer questions about the code.
Do not make any modifications.

Compartir skills

Las skills se distribuyen según el alcance deseado:

• Proyecto: subir .claude/skills/ al control de versiones para que todo el equipo tenga acceso
• Plugins: empaquetar skills dentro de un plugin para distribución a través de marketplaces
• Enterprise: desplegar skills a nivel de organización mediante configuración managed

Las skills de proyecto son la forma más directa de estandarizar workflows dentro de un equipo: un commit que añade una skill a .claude/skills/ la hace disponible para todos los miembros del proyecto.