Claude Code Skills: crea extensiones propias que se activan solas

¿Cómo se crea un skill propio para Claude Code? Crea un archivo SKILL.md en ~/.claude/skills/<name>/ (personal) o en .claude/skills/<name>/ (a nivel de proyecto), con un frontmatter YAML que contenga los campos name, description y allowed-tools, seguido del contenido markdown con tu experiencia. Claude usa razonamiento LLM sobre esa descripción para activar el skill automáticamente cuando tu tarea encaja con ella. Los skills de proyecto que se comparten vía git no requieren ninguna configuración por parte de tus compañeros.

Tres sesiones seguidas pegué la misma lista de verificación de seguridad en Claude Code. Esa lista contenía los patrones de vulnerabilidad propios de nuestro equipo: las revisiones de IDOR ligadas al diseño de nuestra API, las reglas de manejo de sesión de nuestro flujo de autenticación, las reglas de exposición de datos para nuestros campos con PII. Cada vez, Claude las aplicó a la perfección. Cada vez, tuve que acordarme de pegarlas.

El momento en que te descubres explicando otra vez el mismo contexto es el momento de crear un skill.

TL;DR

Los skills son extensiones que invoca el modelo: Claude las descubre y las aplica automáticamente según el contexto, sin que tengas que llamarlas de forma explícita ¹. La clave de un skill confiable está en el campo description: Claude decide cuándo activar cada skill mediante razonamiento LLM, no por coincidencia de palabras clave ¹. Crea skills para experiencia de dominio que se mantenga entre sesiones (patrones de seguridad, estilo de código, reglas de negocio). No crees skills para tareas puntuales: para eso están los slash commands.

Requisitos previos: conocer el sistema de extensiones de Claude Code. Para la comparación entre skills, commands y subagents, revisa la sección de Skills de la guía.

Cuándo conviene crear un skill

No todo prompt repetido merece un skill. El marco de decisión:

Los skills son conocimiento que Claude siempre tiene a mano. Los slash commands son acciones que disparas tú. Si dudas entre ambos, pregúntate: «¿Claude debería aplicar esto automáticamente, o prefiero decidir yo cuándo ejecutarlo?».

Un error común: crear un skill para algo que haces una vez por semana. Yo armé un skill git-rebase-helper que se activaba con cualquier prompt relacionado con git: rebases, merges, cherry-picks y hasta git status. La descripción era demasiado amplia, contaminaba el contexto en el 80 % de las sesiones donde no hacía falta y competía con otros skills por el presupuesto de contexto del 2 % ¹. La solución fue borrar el skill y usar un slash command en su lugar: /rebase, cuando de verdad lo necesitaba. Un skill debe codificar experiencia estable, no flujos de trabajo ocasionales.

Tutorial: crea un skill de revisión de código

Paso 1: crea el directorio

Los skills viven en cuatro ubicaciones posibles, del alcance más amplio al más estrecho ¹:

Para este tutorial vamos a crear un skill personal:

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

Paso 2: escribe SKILL.md con su frontmatter

Todo skill necesita un archivo SKILL.md con dos partes: el frontmatter YAML (entre los marcadores ---), que le dice a Claude cuándo usar el skill, y el contenido markdown con las instrucciones que Claude sigue una vez que el skill se invoca ¹.

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

Fíjate en allowed-tools: Read, Grep, Glob: eso restringe el skill a operaciones de solo lectura. El revisor de código puede examinar archivos, pero no modificarlos. Las restricciones de herramientas evitan que los skills tengan efectos secundarios no deseados.

Otros campos útiles del frontmatter, más allá de name, description y allowed-tools ¹:

Una salvedad de la documentación oficial: context: fork «solo tiene sentido para skills con instrucciones explícitas que se benefician del aislamiento» ¹. Úsalo en skills de análisis (revisión de código, auditoría de seguridad) donde quieres un contexto limpio, no en skills de conocimiento que deben integrarse en la conversación principal.

Paso 3: agrega recursos de apoyo

Un skill puede hacer referencia a otros archivos del mismo directorio ¹:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Enlázalos desde SKILL.md con rutas relativas:

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

Claude lee esos archivos bajo demanda, en cuanto el skill se activa, con las herramientas habituales de lectura de archivos ¹. Mantén SKILL.md por debajo de las 500 líneas y mueve el material de referencia detallado a archivos de apoyo ³ — los archivos de skill más cortos reducen el costo de inyección de contexto y mantienen a Claude enfocado en la tarea actual.

Paso 4: prueba la activación

El skill se activa la próxima vez que inicies una sesión de Claude Code. Para probarlo:

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

Hay dos maneras de verificar que el skill se cargó ¹:

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

Si el skill no se activa, el problema casi siempre está en el campo description. Mira el paso 5.

Paso 5: el paso decisivo — escribir la descripción

El campo description es la línea más importante de tu skill. Esto es lo que ocurre por debajo: al iniciar la sesión, Claude Code extrae el name y la description de cada skill y los inyecta en el contexto de Claude. Cuando envías un mensaje, Claude decide si algún skill es relevante mediante razonamiento del modelo de lenguaje: no con regex, ni con coincidencia de palabras clave, ni con similitud de embeddings. La documentación oficial lo dice así: «Claude compara tu tarea con las descripciones de los skills para decidir cuáles son relevantes. Si las descripciones son vagas o se solapan, puede que Claude cargue el skill equivocado, o que pase por alto uno que habría ayudado» ¹.

Un análisis independiente del código fuente de Claude Code confirma el mecanismo: las descripciones de los skills se inyectan en una sección available_skills del prompt del sistema, y el modelo elige los skills relevantes en el momento de la invocación con comprensión del lenguaje corriente ⁴. Este matching por LLM tiene consecuencias importantes para la forma de escribir las descripciones.

Descripción mala:

description: Helps with code

Claude no tiene idea de cuándo activar esto. «Helps with code» encaja con todo y con nada, y como el matching se basa en razonamiento LLM, las descripciones vagas producen activaciones impredecibles.

Descripción algo mejor:

description: Review code for bugs and issues

Demasiado vaga. ¿Qué tipo de bugs? ¿Qué tipo de problemas? ¿Cuándo debería Claude usar esto en lugar de su análisis integrado?

Descripción efectiva:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

Esta descripción funciona porque incluye: - Qué hace: revisar código en busca de tipos concretos de problemas - Cuándo usarla: al examinar cambios, PR y análisis de calidad - Frases disparadoras: review, audit, check, las palabras que el usuario escribe de forma natural

Una restricción que conviene conocer: todas las descripciones de skills comparten un presupuesto de contexto que «escala dinámicamente al 2 % de la ventana de contexto, con un valor de reserva de 16.000 caracteres» ¹. Si tienes muchos skills, mantén cada descripción concisa: una descripción verbosa le quita espacio a las demás. Puedes cambiar el presupuesto con la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET ², pero la mejor solución son descripciones más cortas y precisas.

Prueba descripciones distintas. Abre una sesión nueva, pídele a Claude que revise código y fíjate si el skill se activa. Si no, agrega más frases disparadoras. Si se activa cuando no debería, haz la descripción más específica.

Paso 6: itera según el uso

Después de una semana de uso vas a descubrir: - Patrones que el skill debería revisar y no revisa: agrégalos a SKILL.md - Activaciones falsas en tareas ajenas: ajusta la descripción, o agrega disable-model-invocation: true y exige la invocación explícita /code-reviewer - Contexto que falta: agrega archivos de recursos de apoyo - Restricciones de herramientas demasiado estrictas o demasiado laxas: ajusta allowed-tools

Los skills son documentos vivos. La primera versión nunca es la definitiva.

Nivel avanzado: skills como biblioteca de prompts

Más allá de los skills de un solo propósito, esta estructura de directorios funciona como una biblioteca de prompts ordenada:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Cada skill codifica una faceta distinta de la experiencia de tu equipo. Juntos forman una base de conocimiento de la que Claude se nutre automáticamente según el contexto. Un desarrollador junior recibe orientación de nivel senior sin tener que pedirla.

Una nota sobre la cantidad de skills: más skills significan más descripciones compitiendo por el presupuesto de contexto ¹. Si notas que algunos skills no se activan, ejecuta /context para ver si alguno quedó excluido. Prioriza pocos skills bien descritos frente a muchos skills vagos.

Cómo compartir skills con tu equipo

Los skills personales (~/.claude/skills/) son solo tuyos. Úsalos para preferencias personales, patrones experimentales o experiencia propia de tu forma de trabajar.

Los skills de proyecto (.claude/skills/ en la raíz del repositorio) se comparten vía git ¹:

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

En cuanto tus compañeros hacen pull, obtienen el skill automáticamente. Sin instalación y sin configuración. La distribución por git es la manera más efectiva de estandarizar la experiencia dentro de un equipo.

Pautas para skills compartidos: - Mantén los skills de proyecto centrados en la experiencia de dominio (reglas de negocio, patrones de arquitectura) - Reserva los skills personales para preferencias de flujo de trabajo (formato, estilo de commit) - Documenta por qué existe el skill en un comentario al inicio de SKILL.md - Revisa los cambios de skills en los PR como cualquier otro código

Conclusiones clave

• Crea un skill en cuanto te descubras explicando otra vez el mismo contexto. Si pegas la misma lista de verificación tres veces, debería ser un skill.
• El campo description lo determina todo. Claude usa razonamiento LLM para hacer coincidir tus pedidos con las descripciones ¹. Dedícale más tiempo a la descripción que al contenido del skill.
• Usa allowed-tools para limitar los efectos secundarios. Los skills de solo lectura deberían restringirse a Read, Grep, Glob.
• Comparte los skills de proyecto vía git. Distribución de conocimiento en el equipo sin ninguna configuración ¹.
• No abstraigas de más. Un skill para cada micropatrón genera carga de mantenimiento y compite por el presupuesto de contexto. Crea skills para experiencia estable, reutilizable y lo bastante valiosa como para mantenerla.

Preguntas frecuentes

¿Qué son los skills de Claude Code?

Los skills son extensiones que invoca el modelo, guardadas como archivos markdown, que Claude descubre y aplica automáticamente según el contexto. A diferencia de los slash commands, que disparas de forma explícita, un skill se activa cuando el razonamiento LLM de Claude determina que tu tarea actual encaja con su descripción. Codifican experiencia de dominio —patrones de seguridad, reglas de estilo de código, lógica de negocio— que persiste entre sesiones sin que tengas que volver a explicar el contexto cada vez.

¿Cómo creo un skill propio para Claude Code?

Crea un directorio en ~/.claude/skills/<name>/ para skills personales o en .claude/skills/<name>/ para skills de proyecto. Dentro, crea un archivo SKILL.md con frontmatter YAML (que contenga name, description y, de forma opcional, allowed-tools) seguido del contenido markdown con la experiencia que Claude debe aplicar. El campo description es crítico: Claude aplica razonamiento LLM sobre él para decidir cuándo activar el skill. Revisa el tutorial completo de arriba para ver el recorrido paso a paso.

¿Cuál es la diferencia entre los skills de Claude Code y los slash commands?

Los skills se activan solos según el contexto: Claude decide cuándo son relevantes con razonamiento LLM sobre la descripción del skill. Los slash commands son acciones que invoca el usuario y que disparas de forma explícita escribiendo /command-name. Crea un skill cuando Claude deba tener siempre disponible ese conocimiento (experiencia de dominio, estándares de calidad). Crea un slash command cuando quieras decidir tú cuándo se ejecuta la acción (scripts de despliegue, flujos puntuales).

¿Los skills de Claude Code pueden llamar a otras herramientas?

Sí, pero tú controlas cuáles mediante el campo allowed-tools del frontmatter. Un skill de solo lectura, como un revisor de código, debería restringirse a Read, Grep, Glob para evitar efectos secundarios no deseados. Si omites allowed-tools, el skill puede usar cualquier herramienta a la que Claude tenga acceso. Los skills también pueden definir sus propios hooks en el frontmatter, que se activan solo mientras el skill se ejecuta.

¿Por qué no se activa mi skill de Claude Code?

La causa más común es un campo description vago o demasiado amplio. Claude usa razonamiento LLM, no coincidencia de palabras clave, para decidir si un skill es relevante para tu tarea actual. Si la descripción dice «helps with code», Claude no puede distinguir cuándo activarlo frente a cualquier otra tarea de programación. Haz la descripción específica: nombra los tipos de problema exactos, los escenarios que la disparan y los verbos de acción que los usuarios escriben de forma natural. Revisa también /context en una sesión para ver si tu skill quedó excluido por el límite del 2 % del presupuesto de contexto. Si muchos skills compiten por el espacio, algunos se caen.

¿Dónde se guardan los skills de Claude Code y cómo se comparten?

Los skills viven en cuatro ubicaciones de alcance creciente: personal (~/.claude/skills/<name>/SKILL.md), proyecto (.claude/skills/<name>/SKILL.md), plugin y empresa (configuración administrada). Los skills personales se aplican a todos tus proyectos. Los skills de proyecto se comparten vía git: en cuanto tus compañeros hacen pull, obtienen el skill automáticamente y sin ninguna configuración. Todas las descripciones de skills comparten un presupuesto de contexto del 2 % de la ventana de contexto, así que mantenlas concisas si tienes muchos skills.

Referencias