Si siempre pegas las mismas instrucciones en Claude Code, una skill puede guardarlas por ti. Esta guía explica qué es una agent skill, dónde van los archivos y cómo escribir y probar una pequeña. También cubre cómo instalar skills desde marketplaces de plugins y los errores que impiden que una skill cargue.
Todo lo que sigue se comprobó con la documentación oficial de Anthropic en noviembre de 2026. Claude Code cambia a menudo, así que la documentación enlazada tiene la última palabra.
Qué es una agent skill
Una skill es una carpeta con un archivo llamado SKILL.md dentro. El archivo tiene dos partes. Arriba va el frontmatter YAML entre marcadores ---, con un name y una description. Debajo van instrucciones en Markdown normal que Claude sigue cuando se ejecuta la skill.
Una carpeta de skill también puede incluir archivos extra, como notas de referencia, plantillas o scripts.
Las skills se cargan por etapas, lo que Anthropic llama divulgación progresiva (progressive disclosure). Al arrancar, Claude solo carga el nombre y la descripción de cada skill. Las instrucciones completas se cargan cuando se activa la skill, y los archivos incluidos solo si Claude los abre. Así puedes instalar muchas skills sin llenar la ventana de contexto.
Qué necesitas
- Claude Code instalado y con la sesión iniciada
- Una terminal y un editor de texto
- Un proyecto git para hacer pruebas (la skill de ejemplo escribe mensajes de commit)
Paso 1: elige dónde vive la skill
El lugar donde guardas una skill decide qué sesiones pueden verla. Las dos ubicaciones que más usarás son:
- Personal:
~/.claude/skills/<skill-name>/SKILL.md. Disponible en todos tus proyectos en este equipo. - De proyecto:
.claude/skills/<skill-name>/SKILL.mddentro de un repositorio. Disponible en las sesiones de ese repo. Haz commit y tu equipo también la tendrá.
También existen ubicaciones empresariales, anidadas y de plugins. Si una skill personal y una de proyecto comparten nombre, gana la personal.
Un detalle: las sesiones en la nube y Cowork no leen las skills personales de ~/.claude/skills/. Para esos casos, la documentación indica activar la skill en tu cuenta de claude.ai o hacer commit en el repositorio.
Paso 2: crea la carpeta
Vamos a crear una skill personal llamada commit-message.
mkdir -p ~/.claude/skills/commit-message
Resultado esperado: el comando no imprime nada. La carpeta vacía ya existe.
Paso 3: escribe SKILL.md
Crea ~/.claude/skills/commit-message/SKILL.md y pega esto. El nombre del archivo debe ser exactamente SKILL.md.
---
name: commit-message
description: Writes a clear git commit message from the staged changes. Use when the user asks for a commit message, wants to commit their work, or asks how to describe their changes.
---
# Commit message writer
1. Run `git diff --staged` to see what is staged.
2. If nothing is staged, say so and stop.
3. Write a subject line in the imperative mood, under 72 characters.
4. Leave one blank line, then add a short body that explains why the change was made.
5. Show the message in a code block. Do not run `git commit` unless the user asks.
Algunas notas sobre el frontmatter:
namese convierte en el comando que escribes. Si lo omites, Claude Code usa el nombre de la carpeta.descriptiones lo que Claude lee para decidir si usa la skill. Di primero qué hace la skill y después cuándo usarla.- El
---de apertura debe ser la primera línea del archivo. Si no, Claude Code trata todo el archivo como contenido normal.
Claude Code acepta más campos, como disable-model-invocation y allowed-tools. Pero las subidas a claude.ai y la Skills API solo aceptan seis: name, description, license, compatibility, metadata y allowed-tools. Si te limitas a name y description, tu skill será portable.
Paso 4: pruébala
Prepara (stage) un cambio pequeño en cualquier proyecto git y luego inicia Claude Code.
git add .
claude
Puedes activar la skill de dos formas. Primero, pídelo con palabras normales y deja que Claude la detecte por la descripción:
Can you write a commit message for what I've staged?
O llámala directamente por su nombre:
/commit-message
Resultado esperado: Claude ejecuta git diff --staged y responde con una línea de asunto y un cuerpo breve en un bloque de código.
No hace falta reiniciar después de editar. Claude Code vigila ~/.claude/skills/ y la carpeta .claude/skills/ del proyecto, y aplica los cambios en la sesión actual.
Paso 5: añade archivos de apoyo (opcional)
Cuando una skill crece, saca los detalles de SKILL.md. La documentación sugiere mantenerlo por debajo de 500 líneas. Una estructura podría ser así:
commit-message/
├── SKILL.md
├── examples.md
└── scripts/
└── check-length.sh
Enlaza los archivos extra desde SKILL.md para que Claude sepa cuándo abrirlos. Los scripts se ejecutan, no se cargan en el contexto.
Paso 6: instala skills desde un marketplace de plugins
No tienes que escribir todas las skills tú mismo. En Claude Code, las skills pueden venir dentro de plugins, y los plugins vienen de marketplaces. El marketplace oficial de Anthropic, claude-plugins-official, se añade automáticamente la primera vez que inicias una sesión interactiva.
El repositorio público de skills de Anthropic en GitHub también se puede añadir como marketplace. Su README indica estos comandos:
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
Dentro de una sesión, /plugin install abre el panel de plugins para que revises el plugin y elijas un alcance antes de instalarlo. Las skills de plugins tienen espacio de nombres, así que una skill llamada review en un plugin llamado my-plugin se ejecuta como /my-plugin:review.
Skills vs servidores MCP vs CLAUDE.md
CLAUDE.md guarda datos y reglas fijas que se cargan en cada sesión, como «usa pnpm» o «los tests están en tests/«. Mantenlo corto, porque siempre está en el contexto.
Las skills guardan procedimientos y material de referencia que solo importan a veces. Anthropic aconseja crear una skill cuando una sección de CLAUDE.md se ha convertido en un procedimiento, o cuando pegas una y otra vez la misma lista de comprobación en el chat.
Los servidores MCP conectan Claude con herramientas y datos externos, como una base de datos, un gestor de incidencias o una app de diseño. Una skill puede explicarle a Claude cómo usar bien esas herramientas, pero no proporciona la conexión.
Skills fuera de Claude Code
El mismo formato funciona en todos los productos de Claude. Según la descripción general de Anthropic, las skills personalizadas se pueden crear en Claude Code, subir mediante la Claude API o añadir en los ajustes de claude.ai. Las skills subidas a claude.ai deben subirse por separado a la API.
Una nota sobre seguridad
Una skill no es solo texto. Puede incluir scripts y llevar a Claude a ejecutar comandos y llamar a herramientas. Anthropic recomienda usar solo skills de fuentes de confianza, es decir, las que escribiste tú o las que vienen de Anthropic. Si pruebas una de otro origen, lee antes todos los archivos, incluidos los scripts, y busca llamadas de red o accesos a archivos inesperados.
Errores comunes y soluciones
Claude nunca usa la skill por su cuenta
La causa habitual es una descripción vaga. «Helps with git» (ayuda con git) le da a Claude muy poco con qué coincidir. Escribe qué hace la skill y las frases que la gente diría de verdad. También puedes preguntarle a Claude «What skills are available?» (¿qué skills hay disponibles?) para comprobar que se cargó, y usar /skill-name para ejecutarla directamente.
La skill no aparece en absoluto
Revisa la ruta y las mayúsculas. Debe ser ~/.claude/skills/<skill-name>/SKILL.md, con el archivo dentro de su propia carpeta, no suelto en skills/. La documentación también enumera caracteres que un nombre no puede tener, como <, > o un espacio al principio o al final.
El frontmatter está roto
Si el YAML no se puede analizar, Claude Code carga igualmente el cuerpo, pero con metadatos vacíos. /skill-name sigue funcionando, pero Claude no puede emparejar tu descripción. Inicia Claude Code con claude --debug para ver el error, o ejecuta claude plugin validate ~/.claude/skills para encontrar archivos defectuosos.
Reglas de formato del nombre
Para claude.ai y la API, name solo puede usar letras minúsculas, números y guiones, tener 64 caracteres o menos y no contener las palabras anthropic ni claude. La description puede tener hasta 1.024 caracteres. Evita también llamar a una carpeta synced, nombre que Claude Code reserva para las skills descargadas de claude.ai.
Los cambios no se aplican
Los cambios en skills existentes se cargan sin reiniciar. Pero si creaste un directorio de skills de primer nivel que no existía cuando empezó la sesión, ejecuta /reload-skills. Para plugins nuevos, ejecuta /reload-plugins o reinicia Claude Code.
La skill se activa demasiado
Haz la descripción más específica. Si solo quieres ejecutarla a mano, añade disable-model-invocation: true al frontmatter.
Para terminar
Una skill es una carpeta, un archivo SKILL.md y una buena descripción. Empieza con una tarea que repitas cada semana, escribe los pasos y pruébala con una petición normal y con /skill-name. Revisa todo lo que instales antes de confiar en ello.
Más sobre Claude: consulta todas nuestras guías de Claude y Anthropic, agrupadas por tarea.
Fuentes y documentación oficial
Enlaces revisados por última vez el 15 de noviembre de 2026.





Escribe una respuesta