Skills de Claude Code: cómo funciona SKILL.md y dónde se carga

Las skills de Claude Code son carpetas que contienen un archivo SKILL.md. El archivo tiene un frontmatter YAML que indica cuándo se aplica la skill y un cuerpo en Markdown con las instrucciones. Claude Code mantiene visible la descripción de cada skill, carga el cuerpo completo solo cuando se utiliza y permite ejecutar cualquier skill manualmente escribiendo /skill-name.^[1] Los comandos de barra personalizados ahora funcionan igual: .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md crean /deploy, y los archivos de comandos antiguos siguen funcionando.^[1]

El consejo de Anthropic sobre cuándo escribir una es práctico. Cree una skill cuando pegue repetidamente la misma lista de comprobación o procedimiento en el chat, o cuando una sección de CLAUDE.md se haya convertido en un procedimiento en lugar de un dato. CLAUDE.md se carga en cada sesión; el cuerpo de una skill apenas consume contexto hasta que se ejecuta.^[1]

Una skill mínima de Claude Code

Una skill necesita un directorio y un archivo. Esta redacta notas de versión a partir de commits recientes. Guárdela como ~/.claude/skills/release-notes/SKILL.md:

---
description: Drafts release notes from recent git commits. Use when the user asks for release notes, a changelog entry, or what shipped.
disable-model-invocation: true
---

## Recent commits

!`git log --oneline -30`

## Instructions

Group the commits above into Added, Changed and Fixed. Write one line per change in plain language. Skip merge commits.

El nombre del directorio se convierte en el comando, así que se ejecuta con /release-notes. La línea !`...` es una inyección dinámica de contexto: Claude Code ejecuta el comando e introduce su salida en la skill antes de que Claude la lea, de modo que las notas proceden de su historial real.^[1] disable-model-invocation: true impide que Claude inicie la skill por su cuenta, algo apropiado para lo que quiera activar manualmente.

Dónde se cargan las skills de Claude Code

La carpeta elegida determina quién tiene acceso a la skill:^[1]

Ubicación	Ruta	Quién tiene acceso
Personal	`~/.claude/skills/<name>/SKILL.md`	Usted, en todos los proyectos de esta máquina
Proyecto	`.claude/skills/<name>/SKILL.md`	Todos los que trabajan en el repositorio, una vez incluido en un commit
Anidada	`<subdir>/.claude/skills/<name>/SKILL.md`	Sesiones iniciadas en esa carpeta o en sus subcarpetas
Plugin	`<plugin>/skills/<name>/SKILL.md`	Cualquiera con el plugin activado, como `/plugin-name:skill-name`
Empresa	Directorio de configuración administrada	Todos los usuarios donde la organización la despliegue
Cuenta de claude.ai	Skills activadas en la cuenta	Sesiones con la sesión iniciada en esa cuenta

Hay dos nombres reservados. Claude Code usa ~/.claude/skills/synced/ para las skills descargadas de claude.ai y omite una skill creada con ese nombre de carpeta. Fuera de un plugin, una carpeta llamada anthropic-skills, o cuyo nombre empiece por anthropic-skills:, no se carga.^[1]

Qué controla el frontmatter

Todos los campos son opcionales, y Anthropic solo recomienda description. Claude Code ignora los nombres de campo mal escritos sin informar de ningún error, así que cópielos exactamente.^[1] Los campos que más cambian el comportamiento:

description es lo que usa Claude para decidir si utiliza la skill. Ponga primero el caso de uso principal: junto con when_to_use, se trunca a 1,536 caracteres en la lista de skills.
disable-model-invocation: true hace que la skill sea solo manual. Su descripción también sale del contexto, así que no consume nada hasta que escriba el comando.
user-invocable: false hace lo contrario: solo Claude puede cargarla y desaparece del menú /. Anthropic lo sugiere para conocimientos de fondo, como el funcionamiento de un sistema heredado.
allowed-tools aprueba previamente herramientas para el turno que ejecuta la skill. La autorización termina cuando envía su siguiente mensaje.
paths limita la carga automática a los archivos coincidentes, y context: fork ejecuta la skill en un subagente.

model y effort cambian el modelo y el nivel de razonamiento durante el resto del turno, sin guardar el cambio en su configuración.^[1]

Cuánto contexto consume una skill

Anthropic describe tres niveles. El nombre y la descripción de cada skill se cargan al inicio, unos 100 tokens por skill. El cuerpo de SKILL.md se carga cuando se activa la skill; la tabla de Anthropic sitúa ese nivel por debajo de 5,000 tokens. Los archivos incluidos no consumen contexto hasta que Claude los lee, y el código de un script nunca entra en el contexto; solo lo hace su salida.^[2]

Una vez que se ejecuta una skill, su contenido permanece en la conversación como un mensaje y Claude Code no vuelve a leer el archivo en turnos posteriores. Tras la compactación automática, Claude Code vuelve a adjuntar la ejecución más reciente de cada skill, conservando los primeros 5,000 tokens de cada una dentro de un presupuesto compartido de 25,000 tokens, empezando por las más recientes. Si ha utilizado muchas skills en una sesión larga, las más antiguas pueden quedar fuera.^[1] Escriba las reglas que deban mantenerse durante toda la tarea como instrucciones permanentes cerca del principio del archivo.

Skills de Claude fuera de Claude Code

El mismo formato funciona en otros entornos de Claude, con reglas diferentes en cada uno:^[2]

claude.ai tiene las skills predefinidas de Anthropic para archivos de PowerPoint, Excel, Word y PDF, activas sin configuración. Las skills personalizadas se suben como archivos zip en Settings > Features en los planes Pro, Max, Ultra, Team y Enterprise con la ejecución de código activada. Cada carga es privada para un usuario.
La API de Claude recibe un skill_id en el parámetro container junto con la herramienta de ejecución de código. Los identificadores predefinidos son pptx, xlsx, docx y pdf; las skills personalizadas pasan por los endpoints /v1/skills y se comparten en todo el espacio de trabajo.
Claude Code admite skills personalizadas, pero no las skills predefinidas para documentos.

La documentación de Anthropic se contradice sobre la sincronización. La descripción general de Agent Skills dice que las skills personalizadas no se sincronizan entre entornos y que las skills de Claude Code son independientes tanto de claude.ai como de la API.^[2] La página más reciente de Claude Code incluye las skills activadas en una cuenta de claude.ai como ubicación de carga para las sesiones de terminal con la sesión iniciada en esa cuenta, descargadas a ~/.claude/skills/synced/.^[1] Si depende de esa sincronización, compruebe que la skill aparece en el menú / antes de construir un flujo de trabajo en torno a ella.

Trasladar una skill de Claude Code a claude.ai o a la Skills API requiere cuidado. Esas vías solo aceptan seis campos de frontmatter del estándar abierto Agent Skills: name, description, license, compatibility, metadata y allowed-tools. Cualquier otro campo, como disable-model-invocation o argument-hint, hace que la carga falle con el error «Unexpected key(s)» en lugar de ignorarse, y las funciones exclusivas de Claude Code, como la inyección !`command`, no se ejecutan allí.^[1]^[3] En el ejemplo anterior de notas de versión habría que eliminar ambos elementos.

Instalar skills escritas por otras personas

Una skill puede indicar a Claude que ejecute comandos y llame a herramientas, por lo que Anthropic aconseja usar únicamente skills de fuentes de confianza y tratar su instalación como la de un programa. Lea todos los archivos de la carpeta, no solo SKILL.md: los scripts, las imágenes y los archivos de referencia pueden contener instrucciones. Las skills que obtienen contenido de URL externas conllevan un riesgo adicional, porque la página obtenida puede cambiar después de revisarla.^[2]

FAQ

¿Las skills de Claude Code son lo mismo que los comandos de barra?

Se han unificado. Un archivo de comandos en .claude/commands/ y una carpeta de skill con el mismo nombre crean el mismo comando /name. Las skills añaden archivos de apoyo, carga automática y control de invocación.^[1]

¿Puede Claude Code usar las skills de PowerPoint y Excel?

No. Las skills predefinidas de Anthropic para documentos funcionan en claude.ai y en la API, pero no están disponibles en Claude Code. Claude Code incluye sus propias skills, como /code-review, /debug y /claude-api.^[1]^[2]

¿Por qué Claude ignora mi skill?

Revise primero la descripción: junto con when_to_use, es todo lo que ve Claude antes de decidir. Después compruebe que el --- de apertura es la primera línea del archivo: de lo contrario, Claude Code trata el frontmatter como texto sin formato, y un error de YAML hace que la skill se cargue sin ningún campo definido.^[1]

Ejecutar skills de Claude Code con su propio acceso a modelos

Las skills personales y de proyecto son archivos de su máquina que lee el cliente de Claude Code. Si dirige Claude Code a una pasarela en lugar de usar una suscripción de Claude, la guía de Claude Code de reAPI explica la URL base, el tipo de clave y los identificadores de modelos Claude que acepta, y la página de Claude Sonnet 5.5 muestra las tarifas actuales. Las skills sincronizadas desde claude.ai dependen de iniciar sesión con esa cuenta, así que mantenga carpetas personales o de proyecto para las skills de Claude Code que necesite en todas partes.

Referencias

Anthropic. Extend Claude with skills (Claude Code documentation). Consultado el 4 de noviembre de 2026 en code.claude.com/docs/en/skills
Anthropic. Agent Skills overview. Consultado el 4 de noviembre de 2026 en platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Agent Skills. Agent Skills open standard. Consultado el 4 de noviembre de 2026 en agentskills.io