Skills de Claude, de lo básico a crear la tuya

Le explicás a Claude Code, en cada sesión nueva, cómo escribís los mensajes de commit en tu equipo. O cómo tiene que sonar un resumen de PR. O el esquema de tu base de datos, otra vez. Cada conversación empieza en cero, así que esa explicación se repite.

Una skill es la forma de no repetirla: una carpeta con instrucciones que Claude lee por su cuenta, solo cuando la tarea la necesita, sin que ocupe lugar en el contexto mientras tanto. La escribís una vez y queda disponible en todas las sesiones siguientes.

Usar una que ya existe

Claude Code trae algunas de fábrica —/run, /code-review, /doctor, /loop, entre otras— y las podés ver todas con:

/skills

Se usan de dos formas. Escribiendo el pedido en lenguaje normal, para que Claude decida solo si aplica:

¿Qué cambié en este archivo?

O invocándola directo, con el nombre como comando:

/summarize-changes

Las dos formas terminan haciendo lo mismo si la skill está bien escrita: la diferencia es si decidís vos o decide Claude que hace falta.

Cómo decide Claude cuándo usar una

Acá está el motivo por el que instalar muchas skills no vuelve lenta ni cara una conversación: no se cargan todas enteras de entrada. Se cargan en tres niveles, cada uno más caro que el anterior, y solo se sube de nivel si hace falta.

El campo que decide todo es la descripción: es lo único que Claude compara contra tu pedido para elegir qué skill activar, así que tiene que decir dos cosas —qué hace y cuándo usarla—, no solo el nombre. Esta es buena, tomada de la documentación oficial:

description: Extract text and tables from PDF files, fill forms, merge
  documents. Use when working with PDF files or when the user mentions
  PDFs, forms, or document extraction.

Y estas son malas, por vagas —Claude no tiene con qué decidir si aplican a tu pedido o no—:

description: Helps with documents
description: Processes data
description: Does stuff with files

Crear tu primera skill, paso a paso

Vamos a armar una que resuma los cambios sin commitear, para no tener que pedirlo a mano cada vez. Primero, la carpeta:

mkdir -p ~/.claude/skills/summarize-changes

~/.claude/skills/ es la carpeta personal: lo que pongas ahí está disponible en todos tus proyectos, en esta máquina. Si en cambio la querés disponible solo para quien clone este repositorio, va en .claude/skills/ dentro del propio proyecto, y se sube al control de versiones.

Adentro, un solo archivo, SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted
changes.

La línea que empieza con ! no es texto: es un comando que se ejecuta antes de que Claude vea nada, y el resultado —el diff real de tu proyecto en ese momento— reemplaza esa línea. Si el comando falla, toda la skill se cancela ahí, así que conviene que sea algo confiable.

Se prueba de las dos formas que ya vimos: parado en un repositorio con algún cambio sin commitear, escribís “¿qué cambié?” y debería activarse sola, o escribís /summarize-changes para forzarla.

El frontmatter, de lo esencial a lo avanzado

Los únicos dos campos obligatorios son name y description. name acepta solo minúsculas, números y guiones, hasta 64 caracteres, y no puede usar las palabras “claude” ni “anthropic”. description no puede estar vacío y tiene un máximo de 1024 caracteres.

El resto es opcional, y cada uno resuelve algo puntual:

Campo	Para qué sirve
disable-model-invocation: true	Solo se activa a mano, con /nombre — Claude nunca la elige sola
user-invocable: false	Lo contrario: solo Claude la usa, no aparece en el menú /
allowed-tools: Bash(git add *)	Aprueba herramientas puntuales de antemano, sin preguntar cada vez
context: fork	La corre en un subagente aparte, sin el historial de la conversación
argument-hint: [issue-number]	El texto de ayuda que aparece al autocompletar en el menú /

Por ejemplo, una skill de despliegue tiene sentido con invocación manual únicamente —no querés que Claude decida solo cuándo desplegar— y con las herramientas de shell ya aprobadas, porque son siempre las mismas:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm run build) Bash(npm run test) Bash(git *)
---

Avanzado: una skill con su propio script

Cuando la tarea es siempre igual, conviene que la resuelva un script y no que Claude escriba código nuevo cada vez: es más confiable, y el código del script nunca entra al contexto —solo lo que imprime—. Esta es la estructura de una skill que arma un mapa visual de un repositorio:

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

SKILL.md no explica cómo funciona el script: le dice a Claude que lo ejecute, y qué hace con el resultado.

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure.

## Usage

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in
your browser.

${CLAUDE_SKILL_DIR} es una variable que Claude resuelve sola, con la carpeta exacta de esa skill —así el script se encuentra sin importar en qué proyecto estés parado cuando la usás.

Cómo escribir una buena descripción

Ya vimos el ejemplo bueno y los malos. Dos reglas más, tomadas también de la guía oficial:

Escribila en tercera persona. La descripción se inserta tal cual en las instrucciones del sistema, así que si está en primera persona (“puedo ayudarte con…”) suena raro ahí adentro y confunde más de lo que ayuda.

Nombrá el disparador, no solo la acción. “Analiza datos” no dice cuándo usarla. “Analiza hojas de cálculo, arma tablas dinámicas y gráficos. Usala con archivos Excel, planillas o datos en formato .xlsx” sí: le da a Claude palabras concretas para comparar contra el pedido.

Un cuidado antes de instalar la de otra persona

Una skill le da a Claude instrucciones y, si las tiene habilitadas, herramientas para ejecutarlas. Una mal intencionada puede hacer que Claude llame herramientas o corra código de formas que no tienen nada que ver con lo que la skill dice hacer.

La recomendación oficial es simple: usar solo skills propias o de Anthropic, y si hace falta una de otra fuente, auditarla entera antes —SKILL.md, cualquier script, cualquier imagen— buscando llamadas de red, accesos a archivos, o algo que no coincida con lo que dice que hace.

En el artículo sobre Archify de este blog instalamos una skill de verdad, de un repositorio público, y antes de correr nada leímos el SKILL.md completo para entender exactamente qué esperaba de nosotros. Es el mismo paso, aplicado.

Dónde vive cada skill

Además de personal y de proyecto, hay un par de lugares más, y cuando dos skills se llaman igual, gana la que esté más arriba en esta lista:

Ubicación	Ruta	Alcance
Enterprise	configuración centralizada de la organización	todos los usuarios
Personal	~/.claude/skills/<nombre>/	vos, en cualquier proyecto de esta máquina
Proyecto	.claude/skills/<nombre>/	quien clone este repositorio
Anidada	<subcarpeta>/.claude/skills/<nombre>/	sesiones dentro de esa subcarpeta, con /subcarpeta:nombre
Plugin	<plugin>/skills/<nombre>/	donde el plugin esté habilitado

Para confirmar que el YAML de una skill está bien formado antes de compartirla, claude plugin validate la revisa sin necesidad de invocarla:

claude plugin validate ~/.claude/skills/mi-skill