Claude Code sabe programar, buscar en tu código y ejecutar comandos. Lo que no sabe es que tú tienes una herramienta de notas con su propia CLI, un blog que se publica por API o un sistema de documentación casero. Cada vez que se lo explicas en un prompt, estás repitiendo trabajo. Los skills resuelven exactamente eso: son ficheros de instrucciones que Claude carga automáticamente cuando la tarea encaja, y que le enseñan a usar tus herramientas como si las conociera de siempre.
En este artículo desmonto la anatomía de un skill real —el que uso para consultar y crear documentos en documentador, mi sistema de documentación personal— y el patrón de credenciales que me permite replicarlo en cualquier máquina sin filtrar un solo secreto.
¿Qué es un skill?
Un skill es un fichero Markdown (SKILL.md) con dos partes: un frontmatter YAML que describe cuándo debe activarse, y un cuerpo con las instrucciones que Claude sigue una vez activado. No hay código, no hay plugins, no hay build: es texto que el agente lee en el momento justo.
La clave del diseño es que Claude no carga todos los skills siempre. Ve solo la description de cada uno y decide invocarlo cuando tu petición encaja con ella. El cuerpo completo solo entra en contexto al activarse.
Dónde vive
| Ámbito | Ruta | Cuándo usarlo |
|---|---|---|
| Proyecto | <repo>/.claude/skills/<nombre>/SKILL.md |
Solo en sesiones dentro de ese repo; viaja con el código |
| Usuario | ~/.claude/skills/<nombre>/SKILL.md |
En todas las sesiones de esa máquina |
Regla práctica: si el skill enseña a usar una herramienta del propio repo, va en el proyecto. Si enseña algo tuyo que usas desde cualquier sitio (tu blog, tus notas), va a nivel de usuario.
Anatomía de un SKILL.md
Este es el esqueleto del skill de mi sistema de documentación, con los valores sensibles genericizados:
---
name: notas
description: >
Consulta y crea documentación del usuario almacenada en su sistema
de notas. Usar cuando pregunte por su documentación, pida
buscar/leer/crear documentos, o mencione "notas". Triggers:
"busca en mis notas", "documenta esto", "qué tengo apuntado sobre...".
---
# Instrucciones
1. LOCAL: usar la CLI `notas` con salida JSON:
search -j / show -j / list -j / tags -j.
Antes de crear un documento, buscar si ya existe y proponer editarlo.
2. REMOTO: cargar credenciales con
`source ~/.config/notas/remote.env` y usar la API:
curl -H "Authorization: Bearer $NOTAS_TOKEN" \
"$NOTAS_URL/api/search?q=..."
3. Si la API devuelve 401: token revocado; pedir uno nuevo al usuario.
4. Documentos en Markdown, tags en minúsculas; citar id y slug al responder.
Fíjate en que las instrucciones no son documentación exhaustiva: son órdenes operativas. Qué comando ejecutar, qué hacer antes de crear (buscar duplicados), cómo reaccionar a un error concreto (el 401). Un skill bueno se parece más a un runbook que a un manual.
La descripción es el trigger
El error más común al escribir un skill es tratar la description como un resumen. No lo es: es el mecanismo de activación. Claude la compara con lo que le pides, así que debe contener las frases que tú usas de verdad, en el idioma en que hablas con el agente. Si le dices «busca en mis notas», esas palabras exactas deben estar ahí. Mi truco es terminar la descripción con una lista literal de triggers entre comillas.
El patrón de credenciales
Aquí está la parte donde más se falla. Un skill que habla con una API necesita un token, y la tentación es escribirlo en el propio SKILL.md. Nunca. El skill acaba en repos, en backups, en documentación… y el token con él.
El patrón correcto: las credenciales viven en un fichero de entorno fuera de todo repo, y el skill solo sabe dónde está y cómo cargarlo:
mkdir -p ~/.config/notas
cat > ~/.config/notas/remote.env <<'EOF'
export NOTAS_URL="https://notas.example.com"
export NOTAS_TOKEN="tok_pega-aqui-tu-token"
EOF
chmod 600 ~/.config/notas/remote.env
Y en el skill, la instrucción es simplemente source ~/.config/notas/remote.env antes de llamar a la API. Tres reglas que completan el patrón:
- Un token por máquina (portátil, servidor, agente de CI). Si una máquina se ve comprometida, revocas su token sin tocar el resto.
- El servidor solo guarda el hash del token, y el texto plano se muestra una única vez al crearlo. Un token perdido no se recupera: se genera otro.
- El skill sabe reaccionar al 401: no reintenta a ciegas, le dice al usuario que el token fue revocado y pide uno nuevo. Los modos de fallo previsibles se escriben en las instrucciones.
Local y remoto en el mismo skill
Mi skill tiene dos modos: si el binario de la CLI está en la máquina, usa la CLI con salida --json; si no, ataca la API remota con el token. Esto convierte el skill en portable: la misma carpeta funciona en el portátil donde desarrollo (modo local) y en un servidor donde solo hay acceso HTTP (modo remoto). Si tu herramienta tiene ambas interfaces, documenta las dos y deja que el agente elija según lo que encuentre.
El truco final: guarda el skill donde puedas recuperarlo
Un skill instalado a nivel de usuario no vive en ningún repo, así que cuando estrenas máquina no está. Mi solución: guardo una copia autocontenida del skill —con sus instrucciones de instalación— dentro del propio sistema de documentación al que da acceso. Montar una máquina nueva se reduce a pedirle a Claude «bájate el skill de mis notas e instálalo a nivel de usuario»: él lo busca, lo copia a ~/.claude/skills/, crea el fichero de credenciales con los permisos correctos y prueba la conexión. El skill se instala a sí mismo.
Checklist para tu primer skill
- Frontmatter con
namey unadescriptionque incluya tus frases reales como triggers. - Instrucciones operativas, no documentación: comandos exactos, comprobaciones previas, reacción a errores.
- Credenciales en un fichero de entorno con
chmod 600, jamás en el skill ni en un repo. - Un token por máquina, revocable de forma independiente.
- Una copia del skill en un sitio recuperable, para reconstruir el setup en minutos.
Publicado el 18 de julio de 2026.