← 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 funcionan igual. Los .claude/commands/ siguen funcionando, pero Skills suma archivos de soporte, frontmatter de invocación y carga automática.

Bundled skills (incluidos)

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

Crear tu primer skill

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

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

---
description: Resume cambios sin commitear y marca riesgos. Usalo 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 listá 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).

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

my-skill/
├── SKILL.md           # Instrucciones principales (requerido)
├── template.md        # Plantilla para Claude
├── examples/
│   └── sample.md      # Ejemplo del formato esperado
└── scripts/
    └── 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 que Claude puede usar sin pedir permiso mientras el skill está activo
`model`	Modelo a usar: alias (`sonnet`, `opus`, `haiku`), full ID, 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)

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. Usalo con disable-model-invocation: true cuando no querés 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

my-skill/
├── SKILL.md                    (requerido)
├── reference.md                (API docs detallada)
├── examples.md                 (ejemplos)
└── scripts/
    └── 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. Mové 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 da permiso para las tools listadas mientras el skill está activo, sin pedir aprobación.

---
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. Revisá 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, usá 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)

Agregá 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
---

Investigá $ARGUMENTS a fondo:
1. Encontrá archivos relevantes con Glob y Grep
2. Leé y analizá 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 agregá 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. Usalo 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

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

Skill se activa demasiado

Hacé la description más específica
Agregá disable-model-invocation: true

Descriptions cortadas

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

Cuándo usar cada uno

CLAUDE.md: reglas que aplican SIEMPRE (concisa, < 150 líneas)
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