Aprende conmigo: Claude - Introducción a las Agent Skills

¿Te encuentras explicándole repetidamente a Claude cuáles son los estándares de código de tu equipo? ¿En cada revisión de Pull Request (PR) tienes que volver a describir cómo quieres que se estructure el feedback? ¿Tienes un bloque enorme en tu CLAUDE.md que en realidad es un procedimiento, no un hecho del proyecto? Si tu respuesta es sí, entonces necesitas conocer las Agent Skills.

En este artículo de mi serie "Aprende conmigo" vamos a sumergirnos profundamente en el mundo de las Agent Skills de Claude Code, basándonos en el curso oficial Introduction to Agent Skills de Anthropic y en la documentación oficial. Aprenderemos qué son, cómo crearlas, configurarlas con todas sus opciones avanzadas, gestionarlas, distribuirlas y, lo más importante, cómo usarlas para potenciar nuestra productividad al máximo.

1. ¿Qué son las Agent Skills?

Una Skill (o habilidad) es un archivo Markdown llamado SKILL.md dentro de su propia carpeta, que le enseña a Claude cómo hacer una tarea específica de forma automatizada. A diferencia de un comando tradicional o de un prompt largo, escribes la skill una sola vez y Claude la aplica automáticamente cada vez que identifica que es relevante para la conversación, o tú puedes invocarla directamente con /nombre-skill.

Las skills siguen el estándar abierto Agent Skills, que funciona en múltiples herramientas de IA, no solo Claude Code. Anthropic lo extiende con características propias: control de invocación, ejecución en subagents e inyección dinámica de contexto.

El truco clave es que las skills se cargan bajo demanda. Claude solo lee el nombre y la descripción inicialmente para no saturar tu ventana de contexto. Tu checklist de revisión de PRs no necesita estar en la memoria de Claude cuando estás depurando código; solo se cargará cuando la conversación lo requiera.

Skills vs. otras características de Claude Code

Claude Code ofrece varias opciones de personalización. Es crucial saber cuándo usar cada una para no generar complejidad innecesaria:

2. Anatomía y creación de tu primera skill

Una skill es básicamente un directorio que contiene un archivo llamado exactamente SKILL.md. En la parte superior de este archivo se utiliza un bloque YAML (frontmatter) para definir los metadatos, seguido del contenido Markdown con las instrucciones que Claude seguirá cuando la skill esté activa.

Vamos a crear una skill de ejemplo del curso oficial: una skill que enseña a Claude a explicar código con diagramas visuales y analogías.

Paso 1: Crear el directorio

mkdir -p ~/.claude/skills/explain-code

Paso 2: Escribir el SKILL.md

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

Paso 3: Probarla

Hay dos formas de invocar una skill:

• Automática (model-invoked): Le preguntas algo que coincide semánticamente con la description. Por ejemplo: "How does this code work?"
• Directa (user-invoked): Escribes /explain-code src/auth/login.ts y se carga inmediatamente.

3. Frontmatter completo: todos los campos

El bloque YAML soporta muchos más campos de los que la mayoría de tutoriales mencionan. Conocerlos todos te permite construir skills profesionales. Esta es la lista completa según la documentación oficial:

Ejemplo completo: skill commit con permisos preconcedidos

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Stage and commit the changes:

1. Run `git status` to see what's modified
2. Stage the relevant files
3. Write a conventional commit message
4. Create the commit

Aquí disable-model-invocation: true evita que Claude haga commits por su cuenta cuando crea que el código está listo, y allowed-tools le da permiso para correr comandos git sin pedir aprobación cada vez.

4. Jerarquía y ubicación: ¿dónde viven las skills?

Puedes crear skills en cuatro niveles. Si hay un conflicto de nombres, Claude Code respeta esta jerarquía de prioridades:

Las skills de plugin usan un namespace plugin-name:skill-name, así que no pueden colisionar con las otras. Para evitar conflictos en los demás niveles, usa nombres descriptivos como my-frontend-review en vez de code-review.

Descubrimiento automático en monorepos

Cuando trabajas con archivos en subdirectorios, Claude Code también descubre skills en directorios .claude/skills/ anidados. Si editas packages/frontend/src/Button.tsx, Claude buscará skills en packages/frontend/.claude/skills/ además de las del repositorio raíz. Perfecto para monorepos donde cada paquete tiene sus propios estándares.

5. Argumentos y substitución de strings

Las skills aceptan argumentos cuando las invocas. Esto las hace muchísimo más reutilizables. Las variables disponibles son:

Ejemplo: skill fix-issue

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
argument-hint: [issue-number]
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description with `gh issue view $ARGUMENTS`
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

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

Ejemplo: argumentos posicionales

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

Al invocar /migrate-component SearchBar React Vue, los placeholders se reemplazan: $0 → SearchBar, $1 → React, $2 → Vue.

6. Inyección dinámica de contexto

Esta es una de las características más potentes y menos conocidas: la sintaxis !`comando` ejecuta un shell command antes de que el contenido de la skill sea enviado a Claude. La salida del comando reemplaza el placeholder, así que Claude recibe datos reales, no el comando.

Ejemplo del curso oficial: skill pr-summary

---
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, highlighting:
1. What changed and why
2. Risk areas worth a closer review
3. Anything missing (tests, docs)

Cuando se invoca esta skill:

1. Cada !`comando` se ejecuta primero (antes de que Claude vea nada).
2. La salida reemplaza al placeholder en el contenido.
3. Claude recibe el prompt ya renderizado con datos reales del PR.

Para comandos multilínea, usa un bloque cercado abierto con ` ```! `:

## Environment
```!
node --version
npm --version
git status --short
```

7. Ejecución en subagent (context: fork)

Cuando añades context: fork al frontmatter, la skill se ejecuta en un contexto aislado. El contenido del SKILL.md se convierte en el prompt que dirige al subagent. No tendrá acceso a tu historial de conversación.

Ejemplo: skill de investigación con el agente Explore

---
name: deep-research
description: Research a topic thoroughly across the codebase
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
4. Note any inconsistencies or technical debt found

Al ejecutarse, se crea un contexto aislado, el subagent Explore recibe el contenido de la skill como su tarea, usa sus herramientas optimizadas para exploración (read-only) y devuelve el resumen al chat principal sin contaminarlo con todos los archivos leídos.

8. Progressive disclosure y multi-file

Una buena práctica es mantener tu archivo SKILL.md por debajo de las 500 líneas. Si necesitas más, debes usar progressive disclosure: el SKILL.md hace de índice y mantiene el contenido esencial, mientras que los archivos de soporte se cargan solo cuando se necesitan.

Estructura recomendada:

my-skill/
├── SKILL.md              # Punto de entrada (requerido)
├── reference.md          # Documentación detallada (se carga bajo demanda)
├── examples.md           # Ejemplos de uso (se carga bajo demanda)
├── assets/               # Plantillas, imágenes, datos
│   └── template.html
└── scripts/              # Código ejecutable
    └── helper.py         # Se ejecuta, no se carga al contexto

Dentro del SKILL.md referencias estos archivos así:

## Recursos adicionales

- Para detalles completos del API, lee [reference.md](reference.md)
- Para ejemplos de uso, lee [examples.md](examples.md)
- Para validar el output, ejecuta `python ${CLAUDE_SKILL_DIR}/scripts/helper.py`

El uso de ${CLAUDE_SKILL_DIR} es importante: te asegura que la ruta al script funciona sin importar el directorio actual de trabajo.

9. Bundled skills: las que ya vienen incluidas

Claude Code incluye un set de skills predefinidas que están disponibles en cada sesión. A diferencia de los comandos built-in que ejecutan lógica fija, estas son prompt-based: dan a Claude un playbook detallado y dejan que orqueste el trabajo con sus herramientas.

• /simplify — Revisa el código modificado en busca de oportunidades de reuso, calidad y eficiencia.
• /debug — Ayuda a depurar issues con un enfoque sistemático.
• /loop — Ejecuta un prompt o slash-command en intervalos recurrentes.
• /claude-api — Construye, depura y optimiza apps con la API de Claude / SDK de Anthropic.
• /batch — Procesa múltiples ítems en lote.
• /init, /review, /security-review — Inicialización, revisión de PR, revisión de seguridad.

Puedes inspeccionarlas con What skills are available? en cualquier momento dentro de Claude Code.

10. Compartir skills

Las skills multiplican su valor cuando se comparten. Tienes tres métodos principales:

1. Repositorios (Git): Commitea .claude/skills/ al control de versiones. Quien clona obtiene las skills automáticamente.
2. Plugins: Crea un directorio skills/ en tu plugin y distribúyelo a través de marketplaces comunitarios.
3. Enterprise (Managed Settings): Despliegue a nivel de organización para mandatos de cumplimiento y estándares obligatorios.

Anthropic mantiene un repositorio público de skills oficiales y de ejemplo en github.com/anthropics/skills que puedes usar como punto de partida o referencia.

11. Troubleshooting

Si tu skill no funciona, generalmente cae en uno de estos escenarios. Tu checklist de depuración:

La skill no se dispara

• El problema casi siempre es la description. Claude usa coincidencia semántica.
• Agrega "frases gatillo" (trigger phrases) que coincidan con cómo pides las cosas: "Use when reviewing PRs, doing code review, or when the user asks to check changes."
• Verifica que la skill aparece preguntando "What skills are available?"
• Inténtala invocar directamente con /nombre-skill para descartar problemas de carga.

Las descripciones se truncan

Las descripciones se cargan en contexto para que Claude sepa qué hay disponible. Si tienes muchas skills, las descripciones se acortan para caber en el budget (1% del context window, fallback de 8.000 caracteres). Esto puede eliminar las palabras clave que Claude necesita para hacer match.

Soluciones:

• Pon la frase clave al principio de la description — el cap por entrada es de 1.536 caracteres.
• Sube el límite con la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET.

Se dispara la skill equivocada

Tus descripciones son muy similares entre sí. Hazlas más distintivas, o añade disable-model-invocation: true a la que solo quieres invocar manualmente.

Errores de archivo / carga

• Verifica que el archivo se llame exactamente SKILL.md (mayúsculas).
• Debe estar dentro de una carpeta cuyo nombre coincide con la skill.
• El frontmatter YAML debe estar entre --- al inicio del archivo.

Errores de runtime

• Verifica permisos de ejecución en scripts (chmod +x).
• Usa siempre forward slashes (/) en rutas, incluso en Windows.
• Referencia scripts con ${CLAUDE_SKILL_DIR}/scripts/..., nunca con rutas relativas frágiles.