Cómo Crear Skills Personalizados para Claude Code: Un Tutorial Completo

En tres sesiones consecutivas, pegué la misma lista de verificación de seguridad en Claude Code. La lista contenía los patrones de vulnerabilidad específicos de nuestro equipo: las verificaciones de IDOR únicas de nuestro diseño de API, las reglas de manejo de sesiones de nuestro flujo de autenticación, las reglas de exposición de datos para nuestros campos de PII. Cada vez, Claude las aplicó a la perfección. Cada vez, tuve que recordar pegarlas.

El momento en que se descubre repitiendo el mismo contexto es el momento en que debería construir un skill.

TL;DR

Los skills son extensiones invocadas por el modelo: Claude los descubre y aplica automáticamente según el contexto, sin que usted los llame explícitamente ¹. La clave para skills confiables es el campo description: Claude utiliza razonamiento LLM (no coincidencia de palabras clave) para decidir cuándo activar cada skill ¹. Construya skills para conocimiento de dominio que se aplique entre sesiones (patrones de seguridad, estilo de código, reglas de negocio). No construya skills para tareas puntuales; use comandos slash en su lugar.

Requisitos previos: Familiaridad con el sistema de extensiones de Claude Code. Para la comparación entre skills, comandos y subagentes, consulte la sección de Skills de la guía.

Cuándo Construir un Skill

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

Los skills son para conocimiento que Claude siempre tiene disponible. Los comandos slash son para acciones que usted dispara explícitamente. Si está decidiendo entre los dos, pregúntese: “¿Debería Claude aplicar esto automáticamente, o debería yo decidir cuándo ejecutarlo?”

Un error común: construir un skill para algo que hace una vez por semana. Construí un skill git-rebase-helper que se activaba en cualquier prompt relacionado con git: rebases, merges, cherry-picks, incluso git status. La descripción era demasiado amplia, contaminaba el contexto en el 80% de las sesiones donde no era necesario, y competía con otros skills por el presupuesto de contexto del 2% ¹. La solución fue eliminar el skill y usar un comando slash en su lugar: /rebase cuando realmente lo necesitaba. Los skills deberían codificar conocimiento de dominio estable, no flujos de trabajo ocasionales.

Tutorial: Construir un Skill de Revisión de Código

Paso 1: Crear el directorio

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

Para este tutorial, crearemos un skill personal:

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

Paso 2: Escribir SKILL.md con frontmatter

Cada skill necesita un archivo SKILL.md con dos partes: frontmatter YAML (entre marcadores ---) que le indica a Claude cuándo usar el skill, y contenido markdown con instrucciones que Claude sigue cuando 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

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

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

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

Paso 3: Agregar recursos de apoyo

Los skills pueden hacer referencia a archivos adicionales en el 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

Haga referencia a ellos desde SKILL.md con enlaces relativos:

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

Claude lee estos archivos bajo demanda cuando el skill se activa, utilizando herramientas estándar de lectura de archivos ¹. Mantenga SKILL.md por debajo de 500 líneas y mueva el material de referencia detallado a archivos de apoyo ³; los archivos de skill más cortos reducen la sobrecarga de inyección de contexto y mantienen a Claude enfocado en la tarea actual.

Paso 4: Probar la activación

El skill se activa la próxima vez que inicie una sesión de Claude Code. Pruébelo:

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

Verifique que el skill se cargó usando uno de dos métodos ¹:

# 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. Consulte el Paso 5.

Paso 5: El paso crítico — escribir la descripción

El campo description es la línea más importante de todo su skill. Esto es lo que sucede internamente: al inicio de la sesión, Claude Code extrae el name y la description de cada skill y los inyecta en el contexto de Claude. Cuando usted envía un mensaje, Claude usa razonamiento de modelo de lenguaje — no regex, no coincidencia de palabras clave, no similitud de embeddings — para decidir si algún skill es relevante. La documentación oficial establece: “Claude compara su tarea con las descripciones de los skills para decidir cuáles son relevantes. Si las descripciones son vagas o se superponen, Claude puede cargar el skill incorrecto o pasar por alto uno que habría sido útil” ¹.

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 utiliza comprensión de lenguaje estándar para seleccionar los skills relevantes en el momento de la invocación ⁴. La coincidencia basada en LLM tiene implicaciones importantes para cómo escribir las descripciones.

Descripción mala:

description: Helps with code

Claude no tiene idea de cuándo activar esto. “Helps with code” coincide con todo y con nada, y dado que la coincidencia es razonamiento LLM, las descripciones vagas crean activación impredecible.

Descripción mejor:

description: Review code for bugs and issues

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

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.

La descripción efectiva funciona porque incluye: - Qué hace: Revisar código para tipos de problemas específicos - Cuándo usarlo: Al examinar cambios, PRs, análisis de calidad - Frases disparadoras: review, audit, check — palabras que el usuario escribe naturalmente

Una restricción a conocer: todas las descripciones de skills comparten un presupuesto de contexto que “escala dinámicamente al 2% de la ventana de contexto, con un respaldo de 16.000 caracteres” ¹. Si tiene muchos skills, mantenga cada descripción concisa: una descripción verbosa compite con otros skills por espacio limitado. Puede sobrescribir el presupuesto mediante la variable de entorno SLASH_COMMAND_TOOL_CHAR_BUDGET ², pero la mejor solución son descripciones más cortas y precisas.

Pruebe diferentes descripciones. Inicie una sesión nueva, pida a Claude que revise código y verifique si el skill se activa. Si no, agregue más frases disparadoras. Si se activa cuando no debería, haga la descripción más específica.

Paso 6: Iterar según el uso

Después de una semana de uso, descubrirá: - Patrones que el skill debería verificar pero no lo hace — agréguelos a SKILL.md - Activaciones falsas en tareas no relacionadas — ajuste la descripción, o agregue disable-model-invocation: true y requiera la invocación explícita /code-reviewer - Contexto faltante — agregue archivos de recursos de apoyo - Restricciones de herramientas demasiado estrictas o demasiado permisivas — ajuste allowed-tools

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

Avanzado: Skills como Biblioteca de Prompts

Más allá de skills de propósito único, la estructura de directorios funciona como una biblioteca de prompts organizada:

~/.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 diferente de la experiencia de su equipo. Juntos, forman una base de conocimiento de la que Claude extrae automáticamente según el contexto. Un desarrollador junior obtiene orientación de nivel senior sin pedirla.

Una nota sobre la cantidad de skills: más skills significa más descripciones compitiendo por el presupuesto de contexto ¹. Si nota que los skills no se activan, ejecute /context para verificar si alguno está siendo excluido. Priorice menos skills bien descritos sobre muchos vagos.

Compartir Skills con su Equipo

Los skills personales (~/.claude/skills/) son solo suyos. Úselos para preferencias personales, patrones experimentales o experiencia específica de su flujo de trabajo.

Los skills de proyecto (.claude/skills/ en la raíz del repositorio) se comparten mediante 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

Cuando los compañeros de equipo hacen pull, obtienen el skill automáticamente. Sin instalación, sin configuración. La distribución por git es la forma más efectiva de estandarizar la experiencia en un equipo.

Lineamientos para skills compartidos: - Mantenga los skills de proyecto enfocados en conocimiento de dominio (reglas de negocio, patrones de arquitectura) - Mantenga los skills personales para preferencias de flujo de trabajo (formato, estilo de commits) - Documente por qué existe el skill en un comentario al inicio de SKILL.md - Revise los cambios en skills mediante PRs como cualquier otro código

Conclusiones Clave

• Construya un skill cuando se descubra repitiendo contexto. Si pega la misma lista de verificación tres veces, debería ser un skill.
• El campo de descripción lo determina todo. Claude usa razonamiento LLM para hacer coincidir sus solicitudes con las descripciones ¹. Invierta más tiempo en la descripción que en el contenido del skill.
• Use allowed-tools para restringir efectos secundarios. Los skills de solo lectura deberían estar restringidos a Read, Grep, Glob.
• Comparta skills de proyecto mediante git. Distribución de conocimiento del equipo sin configuración alguna ¹.
• No abstraiga en exceso. Un skill para cada micropatrón crea carga de mantenimiento y compite por el presupuesto de contexto. Construya skills para experiencia que sea estable, reutilizable y lo suficientemente valiosa para mantener.

Referencias