Configuración y skills multiarchivo

Configuración y skills multiarchivo

Puntos clave

• Todos los campos del frontmatter son opcionales en Claude Code, y solo se recomienda description. allowed-tools y model son dos de las adiciones más útiles
• Una buena descripción responde dos preguntas: ¿Qué hace el skill? ¿Cuándo debería Claude usarlo?
• allowed-tools preaprueba las herramientas listadas mientras el skill está activo, así Claude puede usarlas sin preguntar, y no limita a Claude a esas herramientas
• Divulgación progresiva: mantén SKILL.md por debajo de 500 líneas y enlaza a archivos de soporte (referencias, scripts, assets) que Claude lee solo cuando es necesario
• Los scripts se ejecutan sin cargar su contenido en el contexto — solo la salida consume tokens, manteniendo el contexto eficiente

Un skill básico funciona con solo un nombre y una descripción, pero hay varias técnicas avanzadas que pueden hacer tus skills mucho más efectivos en Claude Code. Repasemos los campos clave, las mejores prácticas para las descripciones, los permisos de herramientas y cómo estructurar skills más grandes.

Campos de metadatos del skill

El estándar abierto de agent skills define los campos principales en el frontmatter de SKILL.md, y Claude Code añade muchos propios, como model. En Claude Code, todos los campos son opcionales, y solo se recomienda description. Estos cuatro son un buen punto de partida (la referencia de frontmatter lista el resto):

• name (opcional) — Identifica tu skill. Por defecto toma el nombre del directorio. Si subes el skill a Claude.ai o a la Claude API, es obligatorio y está limitado a letras minúsculas, números y guiones, hasta 64 caracteres.
• description (recomendado) — Le indica a Claude cuándo usar el skill. Si subes el skill a Claude.ai o a la Claude API, es obligatorio y tiene un límite de 1,024 caracteres. Este es el campo más importante porque Claude lo usa para hacer coincidencias.
• allowed-tools (opcional) — Preaprueba las herramientas listadas, así Claude puede usarlas sin pedir permiso mientras el skill está activo.
• model (opcional) — Especifica qué modelo de Claude usar para el skill.

Cómo escribir descripciones efectivas

Sé explícito con tus instrucciones. Si alguien te dijera "tu trabajo es ayudar con la documentación", no sabrías qué hacer — y Claude piensa de la misma manera.

Una buena descripción responde dos preguntas:

1. ¿Qué hace el skill?
2. ¿Cuándo debería Claude usarlo?

Si tu skill no se activa cuando esperas que lo haga, intenta añadir más palabras clave que coincidan con cómo realmente formulas tus solicitudes. La descripción es lo que Claude usa para decidir si un skill es relevante, así que el lenguaje importa.

Preaprobar herramientas con allowed-tools

A veces un skill depende del mismo puñado de herramientas cada vez que se ejecuta, y no quieres aprobar cada llamada manualmente. El campo allowed-tools preaprueba las herramientas que listes, así Claude puede usarlas sin un aviso de permiso durante el resto del turno que invocó el skill. La concesión se borra cuando envías tu siguiente mensaje.



En este ejemplo, el campo allowed-tools está configurado como Read, Grep, Glob, Bash. Cuando este skill está activo, Claude puede usar esas cuatro herramientas sin pedir permiso. No pierde acceso a nada más: si las instrucciones del skill llevan a Claude a editar o escribir un archivo, eso pasa por tu configuración de permisos normal como cualquier otra llamada a herramienta. Una advertencia: listar Bash por sí solo preaprueba comandos de shell en general, así que reserva eso para skills en los que confíes, o limítalo a un patrón como Bash(git status *).

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Si omites allowed-tools por completo, no se preaprueba nada y Claude usa su modelo de permisos normal para cada herramienta. Para hacer lo contrario y quitarle herramientas a Claude mientras un skill está activo, usa un campo separado del frontmatter de Claude Code, disallowed-tools, que elimina las herramientas que listes del conjunto que Claude puede usar.

Divulgación progresiva

Los skills comparten la ventana de contexto de Claude con tu conversación. Cuando Claude activa un skill, carga el contenido de ese SKILL.md en el contexto. Pero a veces necesitas referencias, ejemplos o scripts de utilidad de los que depende el skill.

Meter todo en un solo archivo de 2,000 líneas tiene dos problemas: ocupa mucho espacio de la ventana de contexto, y no es agradable de mantener.

La divulgación progresiva resuelve esto. Mantén las instrucciones esenciales en SKILL.md y pon el material de referencia detallado en archivos separados que Claude lee solo cuando es necesario.

El estándar abierto sugiere organizar el directorio de tu skill con:

• scripts/ — Código ejecutable
• references/ — Documentación adicional
• assets/ — Imágenes, plantillas u otros archivos de datos

Luego, en SKILL.md, enlaza a los archivos de soporte con instrucciones claras sobre cuándo cargarlos:



En este ejemplo, Claude lee architecture-guide.md solo cuando alguien pregunta sobre el diseño del sistema. Si están preguntando dónde agregar un componente, nunca carga ese archivo. Es como tener una tabla de contenidos en la ventana de contexto en lugar de todo el documento.

Una buena regla general: mantén SKILL.md por debajo de 500 líneas. Si estás superando eso, considera si el contenido debería dividirse en archivos de referencia separados.

Usar scripts de manera eficiente

Los scripts en el directorio de tu skill pueden ejecutarse sin cargar su contenido en el contexto. El script se ejecuta y solo la salida consume tokens. La instrucción clave que debes incluir en tu SKILL.md es decirle a Claude que ejecute el script, no que lo lea.

Esto es particularmente útil para:

• Validación de entornos
• Transformaciones de datos que necesitan ser consistentes
• Operaciones que son más confiables como código probado que como código generado

Reflexión de la lección

• Piensa en un skill que te gustaría construir que involucre múltiples archivos. ¿Cómo estructurarías el SKILL.md frente a los archivos de referencia de soporte?
• Para un skill que tu equipo comparte, ¿qué herramientas preaprobarías con allowed-tools, y sobre cuáles preferirías que Claude siguiera preguntando?

Qué sigue

En la próxima lección, compararemos los skills con las otras formas en que puedes personalizar Claude Code — CLAUDE.md, subagentes, hooks y servidores MCP — para que puedas elegir la herramienta correcta para cada situación.