Referencia a fondo · Skills

Skills

Carpetas con instrucciones, scripts y referencias que Claude carga solo cuando las necesita. Son la forma de enseñarle a Claude un procedimiento una vez y reutilizarlo siempre, en tu equipo y en otras herramientas compatibles.

SKILLS · 1

Qué es una skill, en simple

En simpleUna skill es una receta en una tarjeta. En la cocina hay un fichero con cientos de recetas, pero el chef solo ve los títulos. Cuando alguien pide "lasaña", saca esa tarjeta y la lee entera. Claude hace lo mismo: ve el nombre y la descripción de todas tus skills, y solo carga el contenido completo de la que necesita.

Técnicamente es una carpeta con un archivo SKILL.md: frontmatter YAML que dice cuándo usarla y un cuerpo en Markdown que dice cómo. Claude la carga sola cuando la descripción coincide con lo que pides, o la ejecutas tú con /nombre-de-la-skill.

Carga progresiva: por qué no gastan contexto

Tres capas de cargabarra = contexto que ocupa
1 · Listadosiempre en contexto

Nombre + descripción de cada skill (máx. 1.536 caracteres por skill). Así Claude sabe qué existe.

2 · Cuerpo de SKILL.mdsolo al invocarla

Las instrucciones completas entran cuando Claude o tú la invocan. Recomendado: menos de 500 líneas.

3 · Archivos de apoyobajo demanda

reference.md, examples.md, plantillas: Claude los lee solo si el SKILL.md lo dirige ahí. Los scripts se ejecutan sin cargarse al contexto.

Presiona "Simular un pedido".
Skills y comandos son lo mismo ahoraLos antiguos .claude/commands/*.md siguen funcionando, pero una skill puede hacer más: archivos de apoyo, invocación automática, ejecución en subagente. Si una skill y un comando tienen el mismo nombre, gana la skill.
SKILLS · 2

Anatomía de un SKILL.md

Toca cada línea para ver qué hace. Este ejemplo es una skill real que podrías commitear hoy.

.claude/skills/release-notes/SKILL.md
Toca una línea

Cada parte del archivo tiene un rol distinto.

SKILLS · 3

Dónde viven y quién las ve

NivelRutaAlcance
EmpresaDirectorio de managed settingsTodos en la organización
Personal~/.claude/skills/<nombre>/SKILL.mdTodos tus proyectos
Proyecto.claude/skills/<nombre>/SKILL.mdEste repo (commitéala para compartir)
Anidada<subdir>/.claude/skills/…Sesiones en ese subdirectorio o debajo (útil en monorepos)
Plugin<plugin>/skills/<nombre>/SKILL.mdDonde el plugin esté activo, como /plugin:skill
  • Si dos niveles tienen una skill con el mismo nombre, gana el de mayor prioridad: empresa, luego personal, luego proyecto. Las de plugins llevan prefijo y no chocan.
  • Los cambios a un SKILL.md aplican en la sesión actual. Para skills nuevas en carpetas nuevas usa /reload-skills.
  • En algunas sesiones, Claude Code sincroniza también las skills de tu cuenta de claude.ai (syncClaudeAiSkills lo controla).
SKILLS · 4

Quién puede invocarla

Dos campos del frontmatter deciden si la usas tú, Claude, o ambos. Cambia los interruptores:

Control de invocación

Regla prácticaTodo lo que tenga efectos secundarios (deploy, publicar, enviar mensajes, migrar la base de datos) lleva disable-model-invocation: true. No quieres que Claude decida desplegar porque "el código parece listo".
SKILLS · 5

Referencia completa del frontmatter

Todos los campos son opcionales; description es el recomendado. Los booleanos aceptan true/false, yes/no, on/off y 1/0.

Campos
CampoQué haceEjemplo
Fuera de Claude CodeEn claude.ai, la Skills API o al empaquetar, solo se permiten name, description, license, compatibility, metadata y allowed-tools. Otras claves dan error al subirla. Si quieres portabilidad, quédate con esas.
SKILLS · 6

Argumentos y sustituciones

Lo que escribes después del nombre de la skill llega como argumentos. Edita la plantilla o la invocación y mira cómo se expande en tiempo real:

Playground de sustituciones
VariableSe expande a
$ARGUMENTSTodos los argumentos tal como los escribiste
$ARGUMENTS[N] o $NEl argumento en la posición N (desde 0). Cita los valores con espacios: "hola mundo"
$nombreArgumento con nombre, declarado en arguments (por posición)
${CLAUDE_SKILL_DIR}Carpeta que contiene el SKILL.md: para llamar scripts incluidos
${CLAUDE_SESSION_ID}, ${CLAUDE_PROJECT_DIR}, ${CLAUDE_EFFORT}Sesión, raíz del proyecto y nivel de esfuerzo actual
${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}Solo en skills de plugins

Si ningún placeholder recibe los argumentos, Claude Code agrega ARGUMENTS: <valor> al final. Un $nombre sin argumento queda vacío; un $N sin argumento queda como texto literal. Para un signo peso literal escribe \$1.00.

SKILLS · 7

Contexto dinámico: !`comando`

Una línea !`comando` se ejecuta antes de que Claude vea la skill, y su salida reemplaza la línea. Claude recibe datos reales y frescos, no una instrucción de ir a buscarlos.

Preprocesamiento
SKILL.md en disco
⟶
Lo que lee Claude
  • Para varias líneas usa un bloque con tres comillas invertidas seguido de !.
  • Los comandos pasan por el sistema de permisos. Puedes pre-aprobarlos con allowed-tools en el frontmatter.
  • Una organización puede desactivarlo para todos con disableSkillShellExecution.
SKILLS · 8

Archivos de apoyo y context: fork

Organiza la carpeta

.claude/skills/pdf-forms/ ├── SKILL.md ← instrucciones (<500 líneas) ├── reference.md ← detalle, se lee si hace falta ├── examples.md ← ejemplos de entrada/salida ├── templates/ │ └── informe.md └── scripts/ └── fill_form.py ← se ejecuta, no se carga

En el SKILL.md enlaza cada archivo diciendo cuándo leerlo: "Para campos de firma, lee reference.md".

Ejecutar en un subagente

Con context: fork la skill corre en un subagente aislado: lee mucho y te devuelve solo el resultado. agent elige el tipo (por defecto general-purpose; Explore para solo lectura). Con background: false esperas el resultado en el mismo turno.

SKILL.md
---
name: investigar
description: Investiga a fondo un tema del código
context: fork
agent: Explore
---
Investiga $ARGUMENTS a fondo:
1. Encuentra los archivos relevantes con Glob y Grep
2. Lee y analiza el código
3. Resume hallazgos con referencias archivo:línea
OjoEl subagente no ve tu conversación. Las instrucciones deben bastarse solas: una skill de "guías" sin tarea concreta no produce nada útil en fork.
SKILLS · 9

Qué pasa con la skill dentro del contexto

  • Una vez invocada, el contenido renderizado se queda en la conversación los turnos siguientes. Claude Code no relee el archivo: escribe las reglas como instrucciones permanentes, no como pasos de una sola vez.
  • Invocarla otra vez con el mismo contenido agrega solo una nota "ya cargada", no una segunda copia.
  • Al compactar, Claude Code vuelve a adjuntar la invocación más reciente de cada skill, con sus primeros 5.000 tokens. Todas comparten un presupuesto de 25.000 tokens, llenado desde la más reciente: si invocaste muchas, las más antiguas pueden quedar fuera.
  • allowed-tools y disallowed-tools se limpian cuando envías tu siguiente mensaje.
Presupuesto tras compactar

Números separados por comas o espacios. Presiona Enter para calcular, o prueba un ejemplo:

SKILLS · 10

Skills que ya vienen incluidas

Claude Code trae skills listas. Se apagan todas con "disableBundledSkills": true.

SKILLS · 11

Controlar el acceso y depurar

Quieres…Usa
Que Claude no use ninguna skillRegla deny Skill
Permitir o negar una en particularSkill(commit), Skill(deploy *) en allow/deny
Ocultar una skill que no puedes editar (de un repo compartido)skillOverrides: "on", "name-only", "user-invocable-only" u "off"
Cambiar visibilidad rápido/skills → Espacio sobre la skill
Ver cuánto cuesta cada una en contexto/skill-doctor (o t en /skills para ordenar por tokens)
.claude/settings.local.json
{
  "skillOverrides": {
    "legacy-deploy": "off",
    "style-guide": "name-only"
  }
}

Problemas comunes

No se activa solaRevisa que la descripción incluya las palabras que usarías al pedirlo, que el YAML parsee, y que no tenga disable-model-invocation. Pruébala invocándola con /nombre.
Se activa cuando no debeHaz la descripción más específica o pon disable-model-invocation: true.
Claude deja de seguirlaTras compactar puede quedar fuera del presupuesto. Re-invócala o acorta el SKILL.md.
Descripción cortadaDescripción + when_to_use se truncan a 1.536 caracteres: pon el caso de uso principal primero.
Que se active no significa que funcioneVerla disparar solo prueba que Claude la encontró. El plugin skill-creator escribe casos de prueba y compara corridas con y sin la skill.
SKILLS · 12

Constructor de skills

Generador de SKILL.md

SKILLS · 13

¿Skill, CLAUDE.md, hook, subagente o MCP?

La pregunta más frecuente de la comunidad. Elige una situación:

¿Qué uso?
Se cargaGarantíaIdeal para
CLAUDE.mdSiempre, al inicioSugerenciaHechos y convenciones que aplican en cada sesión
Regla .claude/rulesSiempre, o al tocar rutas con pathsSugerenciaConvenciones de una parte del código
SkillSolo la descripción; el cuerpo al usarlaSugerenciaProcedimientos y conocimiento ocasional
SubagenteEn su propio contexto aisladoSugerenciaTareas que leen mucho; devolver solo el resumen
HookNo usa contexto (corre fuera del modelo)DeterministaLo que debe pasar siempre, sin excepción
MCPDefiniciones de herramientas (diferidas con tool search)—Conectar con sistemas externos: Jira, Sentry, bases de datos
SKILLS · 14

Un estándar abierto y portable

Las Agent Skills nacieron en Claude, pero el formato SKILL.md es un estándar abierto: la misma carpeta funciona en Claude Code, claude.ai, la API y en otros agentes y herramientas compatibles. En octubre de 2026 Anthropic donó el estándar a la Agentic AI Foundation, bajo la Linux Foundation.

  • Para que una skill sea portable, usa solo los campos estándar y pon la lógica en el cuerpo y en scripts.
  • Los campos propios de Claude Code (context, hooks, paths, model…) se ignoran o fallan fuera de él.
  • Distribuye skills a tu equipo commiteándolas en el repo o empaquetándolas en un plugin con un marketplace.
QUIZ

Quiz · Skills