← Volver al listado de tecnologías ← Índice de Claude Code

Cap 4: Skills

2 de marzo de 2026 Por: Artiko

claude-codeskillscustomizationworkflows

Qué son los Skills

Los skills extienden lo que Claude puede hacer. Creás un archivo SKILL.md con instrucciones y Claude lo añade a su toolkit. Claude lo invoca automáticamente cuando es relevante, o vos lo invocás directamente con /nombre-skill.

A diferencia de CLAUDE.md (siempre cargado), el cuerpo de un skill se carga solo cuando se usa, así que material de referencia largo cuesta casi nada hasta que lo necesitás.

Los skills siguen el estándar abierto Agent Skills. Claude Code extiende el estándar con invocación controlada, ejecución en subagente e inyección de contexto dinámico.

Custom commands fusionados con Skills: un archivo .claude/commands/deploy.md y un skill .claude/skills/deploy/SKILL.md ambos crean /deploy, y comparten literalmente el mismo frontmatter. La documentación de slash commands (/docs/en/slash-commands) sirve hoy la página «Extend Claude with skills». Los .claude/commands/ siguen funcionando, pero Skills suma archivos de soporte, frontmatter de invocación y carga automática. Ante colisión de nombre, gana el skill.

Regla de enrutamiento oficial: CLAUDE.md solo para lo que aplica SIEMPRE; skills para conocimiento de dominio o flujos ocasionales, que cargan bajo demanda «without bloating every conversation».

Bundled skills (incluidos)

Claude Code trae skills empaquetados disponibles en cada sesión: /simplify, /batch, /debug, /loop, /claude-api, /fewer-permission-prompts, /code-review. Son prompt-based: dan instrucciones a Claude para orquestar el trabajo.

/code-review es el que la guía de best practices cita para la revisión adversarial del diff: correrlo en contexto fresco antes de dar por terminado un cambio, porque un revisor sin sesgo hacia el código recién escrito encuentra lo que el autor no ve. Advertencia de la misma guía: un revisor al que se le pide encontrar huecos casi siempre reporta alguno, aun cuando el trabajo esté bien; conviene indicarle que solo marque gaps que afecten corrección o requisitos declarados.

Crear tu primer skill

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

~/.claude/skills/summarize-changes/SKILL.md:

---
description: Resume cambios sin commitear y marca riesgos. Úsalo cuando el usuario pregunta qué cambió, quiere un mensaje de commit, o pide revisar su diff.
---

## Cambios actuales

!`git diff HEAD`

## Instrucciones

Resumí los cambios en 2-3 bullets, luego lista riesgos como falta de manejo de errores, valores hardcodeados o tests que necesitan actualizarse. Si el diff está vacío, decí que no hay cambios sin commitear.

Probalo automáticamente: “¿Qué cambié?” o directo con /summarize-changes.

La línea !`git diff HEAD` usa inyección de contexto dinámica: el comando se ejecuta y su salida reemplaza el placeholder antes de que Claude vea el contenido.

Dónde viven los skills

Ubicación	Path	Aplica a
Enterprise	Managed settings	Toda la organización
Personal	`~/.claude/skills/<name>/SKILL.md`	Todos tus proyectos
Proyecto	`.claude/skills/<name>/SKILL.md`	Este proyecto
Plugin	`<plugin>/skills/<name>/SKILL.md`	Donde el plugin esté habilitado

Precedencia: enterprise > personal > proyecto. Plugin skills usan namespace plugin-name:skill-name (no hay conflictos). Si hay skill y command con el mismo nombre, el skill gana.

Detección de cambios en vivo

Claude Code observa los directorios. Agregar, editar o quitar un skill toma efecto en la sesión actual sin reiniciar. Crear el directorio top-level por primera vez sí requiere reiniciar.

Descubrimiento desde padres y subcarpetas

Los skills de proyecto se cargan desde .claude/skills/ en el directorio inicial y en cada directorio padre hasta la raíz del repo. Además, cuando trabajás con archivos en subcarpetas, Claude Code descubre skills en .claude/skills/ anidados (ideal para monorepos).

Desde v2.1.203 esas skills anidadas se exponen con prefijo de directorio: un apps/web/.claude/skills/deploy/SKILL.md se invoca como apps/web:deploy. Cuando existen variantes scoped y no-scoped del mismo nombre, se elige la más específica según el directorio en el que estás trabajando; si ninguna coincide, gana la no-scoped.

Skills desde directorios adicionales

--add-dir da acceso a archivos pero no carga otra configuración. Excepción: los .claude/skills/ dentro de un directorio agregado sí se cargan.

Estructura de un skill

flowchart TD
    S["my-skill/"]
    S --> A["SKILL.md — instrucciones principales (requerido)"]
    S --> B["template.md — plantilla para Claude"]
    S --> C["examples/"]
    C --> C1["sample.md — ejemplo del formato esperado"]
    S --> D["scripts/"]
    D --> D1["validate.sh — script ejecutable"]

Solo SKILL.md es requerido. Referencia los archivos de soporte desde SKILL.md para que Claude sepa cuándo cargarlos.

Frontmatter completo

---
name: my-skill
description: Qué hace este skill
disable-model-invocation: true
allowed-tools: Read Grep
---

Todos los campos son opcionales. Solo description es recomendado.

Campo	Descripción
`name`	Nombre del skill. Si se omite, usa el nombre del directorio. Minúsculas, números y guiones (max 64)
`description`	Qué hace y cuándo usarlo. Combinado con `when_to_use` se trunca a 1536 caracteres
`when_to_use`	Contexto adicional para que Claude decida cuándo invocarlo. Se anexa a `description`
`argument-hint`	Hint mostrado en autocomplete. Ej: `[issue-number]` o `[filename] [format]`
`arguments`	Lista de argumentos posicionales nombrados para substitución `$name`
`disable-model-invocation`	`true` impide que Claude lo cargue automáticamente. Solo el usuario lo invoca
`user-invocable`	`false` lo oculta del menú `/`. Solo Claude lo invoca. Default `true`
`allowed-tools`	Tools pre-aprobadas: Claude las usa sin pedir permiso durante el turno que invoca el skill. No restringe nada
`disallowed-tools`	Tools que Claude NO puede usar durante el skill. Es el campo para restringir (a diferencia de `allowed-tools`, que solo pre-aprueba)
`model`	Modelo a usar: alias (`sonnet`, `opus`, `haiku`, `fable`), ID completo sin sufijo de fecha (`claude-opus-4-8`, `claude-sonnet-5`, `claude-fable-5`), o `inherit`
`effort`	Effort level: `low`, `medium`, `high`, `xhigh`, `max`
`context`	`fork` para ejecutar en subagente forked
`agent`	Tipo de subagente cuando `context: fork` (built-in o custom)
`hooks`	Hooks scoped al ciclo de vida del skill
`paths`	Glob patterns que limitan cuándo se activa (auto-invocación basada en archivos abiertos)
`shell`	`bash` (default) o `powershell` para los bloques !`...`

Substituciones de string

Variable	Descripción
`$ARGUMENTS`	Todos los argumentos pasados. Si no está, se anexa como `ARGUMENTS: <value>`
`$ARGUMENTS[N]`	Argumento por índice 0-based
`$N`	Atajo de `$ARGUMENTS[N]`. Ej: `$0`, `$1`
`$name`	Argumento nombrado declarado en `arguments` frontmatter
`${CLAUDE_SESSION_ID}`	ID de la sesión actual
`${CLAUDE_EFFORT}`	Nivel de effort actual
`${CLAUDE_SKILL_DIR}`	Directorio del SKILL.md (clave para referenciar scripts del skill)
`${CLAUDE_PROJECT_DIR}`	Raíz del proyecto. Útil para rutas absolutas en scripts

Argumentos indexados usan quoting estilo shell: /my-skill "hello world" second → $0=hello world, $1=second.

Tipos de contenido de skill

Reference content (conocimiento aplicado inline)

Convenciones, patrones, style guides. Se ejecuta inline junto al contexto de la conversación.

---
name: api-conventions
description: Patrones de diseño de API para este codebase
---

Cuando escribas endpoints:
- Naming RESTful
- Formato de error consistente
- Validación de request incluida

Task content (instrucciones paso a paso)

Acciones específicas: deploys, commits, generación de código. Úsalo con disable-model-invocation: true cuando no quieres que Claude decida cuándo ejecutarlo.

---
name: deploy
description: Deploy a producción
context: fork
disable-model-invocation: true
---

Deploy de la aplicación:
1. Correr suite de tests
2. Build de la aplicación
3. Push al target de deploy

Control de invocación

Frontmatter	Vos invocás	Claude invoca	Contexto
(default)	Sí	Sí	Description siempre en contexto, skill carga al invocar
`disable-model-invocation: true`	Sí	No	Description no en contexto, carga al invocar
`user-invocable: false`	No	Sí	Description siempre en contexto, carga al invocar

Archivos de soporte

flowchart TD
    S["my-skill/"]
    S --> A["SKILL.md (requerido)"]
    S --> B["reference.md (API docs detallada)"]
    S --> C["examples.md (ejemplos)"]
    S --> D["scripts/"]
    D --> D1["helper.py (script ejecutable)"]

Referencia desde SKILL.md:

## Recursos adicionales

- Para detalles completos de la API, ver [reference.md](reference.md)
- Para ejemplos de uso, ver [examples.md](examples.md)

Mantené SKILL.md bajo 500 líneas. Mueve el material extenso a archivos separados.

Lifecycle del contenido del skill

Cuando se invoca un skill, el SKILL.md renderizado entra a la conversación como un mensaje y se queda por el resto de la sesión. Claude Code no re-lee el archivo en turnos posteriores.

Auto-compactación: cuando la conversación se resume, Claude Code re-adjunta la invocación más reciente de cada skill después del resumen, guardando los primeros 5000 tokens de cada uno (budget combinado de 25000 tokens).

Pre-aprobar tools

allowed-tools pre-aprueba las tools listadas: Claude las usa sin pedir aprobación durante el turno que invoca el skill, y la pre-aprobación caduca con el siguiente mensaje del usuario. No es una whitelist: no limita qué puede usar Claude, solo evita los prompts de permiso de lo que enumeraste.

Para restringir se usa disallowed-tools, que sí bloquea las tools listadas mientras el skill corre.

Contraste con subagentes: en .claude/agents/*.md el campo tools sí es whitelist (recorta el set de herramientas disponibles), y disallowedTools quita herramientas del set. En skills la semántica es distinta: allowed-tools pre-aprueba, disallowed-tools restringe.

---
name: commit
description: Stage y commit de los cambios actuales
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Para project skills, esto toma efecto después de aceptar el workspace trust dialog. Revisa los project skills antes de confiar en un repo, porque un skill puede otorgarse amplio acceso.

Inyección de contexto dinámica

La sintaxis !`<comando>` ejecuta comandos shell antes de que el contenido se envíe a Claude. La salida reemplaza el placeholder.

---
name: pr-summary
description: Resume cambios en un PR
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Contexto del PR
- Diff: !`gh pr diff`
- Comentarios: !`gh pr view --comments`
- Archivos modificados: !`gh pr diff --name-only`

## Tu tarea
Resumí este PR...

Para comandos multi-línea, usa un fenced block con ```!:

## Environment
```!
node --version
npm --version
git status --short
```

Para deshabilitar globalmente, configurá "disableSkillShellExecution": true en settings.

Para razonamiento más profundo en un skill, incluí ultrathink en cualquier parte del contenido.

Skills en un subagente (context: fork)

Agrega context: fork para correr el skill en aislamiento. El contenido del skill se convierte en el prompt que maneja al subagente.

---
name: deep-research
description: Investiga un tópico a fondo
context: fork
agent: Explore
---

Investiga $ARGUMENTS a fondo:
1. Encontrá archivos relevantes con Glob y Grep
2. Lee y analiza el código
3. Resumí los hallazgos con referencias específicas

El campo agent define el ambiente de ejecución (modelo, tools, permisos). Opciones: Explore, Plan, general-purpose o cualquier subagente custom de .claude/agents/.

⚠️ context: fork solo tiene sentido para skills con instrucciones explícitas. Skills de solo guidelines sin tarea devolverán resultado vacío.

Restringir el acceso de Claude a skills

Deshabilitar todos los skills

En /permissions agrega deny rule: Skill

Permitir/denegar skills específicos

# Permitir solo
Skill(commit)
Skill(review-pr *)

# Denegar
Skill(deploy *)

Sintaxis: Skill(name) para match exacto, Skill(name *) para prefix con argumentos.

Ocultar skills individuales

Agregar disable-model-invocation: true al frontmatter.

Override visibility con skillOverrides

El setting skillOverrides controla visibilidad desde settings sin tocar el SKILL.md. El menú /skills lo escribe por vos (presioná Space para ciclar estados, Enter para guardar).

Valor	Listado a Claude	En `/` menu
`"on"`	Nombre y description	Sí
`"name-only"`	Solo nombre	Sí
`"user-invocable-only"`	Oculto	Sí
`"off"`	Oculto	Oculto

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Generar output visual

Los skills pueden empaquetar y correr scripts en cualquier lenguaje. Patrón potente: generar HTML interactivo que abre en el browser.

---
name: codebase-visualizer
description: Genera visualización interactiva del codebase. Úsalo al explorar repos nuevos.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Correr el script desde la raíz del proyecto:

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

El uso de ${CLAUDE_SKILL_DIR} resuelve correctamente sea que el skill esté personal, project, o plugin.

Distribución

Project skills: commit .claude/skills/ a version control
Plugins: directorio skills/ dentro del plugin
Managed: deploy organization-wide via managed settings

Troubleshooting

Skill no se activa

Verifica que la description incluye keywords naturales del usuario
Verifica que aparece en What skills are available?
Reformulá tu request para matchear la description
Invocá directo con /skill-name

Skill se activa demasiado

Haz la description más específica
Agrega disable-model-invocation: true

Descriptions cortadas

Si tienes muchos skills, las descriptions se acortan para caber en el budget de contexto (1% del context window). Sube el budget con skillListingBudgetFraction (ej 0.02 = 2%) o SLASH_COMMAND_TOOL_CHAR_BUDGET. Cada description está capped a 1536 caracteres (configurable con maxSkillDescriptionChars). Ejecuta /doctor para ver si está overflowing.

Cuándo usar cada uno

CLAUDE.md: reglas que aplican SIEMPRE (concisa, objetivo de < 200 líneas por archivo). Criterio de poda oficial línea por línea: «Would removing this cause Claude to make mistakes?»
Skills: conocimiento o tareas que aplican A VECES (carga on-demand)
Subagents: tareas que requieren CONTEXTO AISLADO con su propio system prompt
Hooks: comportamiento DETERMINISTA en eventos

Siguiente: Hooks