Skills en Claude Code: cómo mantener capacidades sin sobrecargar el contexto

Cómo afectan los skills a la ventana inicial de la sesión

En Claude Code, los skills son directorios estructurados con documentos Markdown (principalmente SKILL.md) que el agente inspecciona para ampliar sus capacidades. Al iniciar una sesión de trabajo, el agente lee los nombres y las descripciones breves de los skills disponibles para saber qué operaciones especializadas puede invocar.

El costo de un skill en el contexto se divide en tres niveles:

1. Anuncio en el sistema (descripción y trigger): el bloque YAML description y el nombre en SKILL.md. Permanece en la memoria activa para que el modelo relacione el mensaje del usuario con la herramienta adecuada.
2. Cuerpo de la instrucción: directivas detalladas, pasos secuenciales y ejemplos. El modelo solo carga este contenido cuando se activa el skill correspondiente.
3. Scripts y recursos auxiliares: ejecutables en el directorio scripts/ o guías en references/, invocados de forma determinista mediante comandos en la terminal.

Un error frecuente consiste en colocar guías extensas o manuales completos de API dentro de la description o en el archivo raíz CLAUDE.md. Esto añade tokens innecesarios a cada interacción.

Al configurar conexiones a API externas mediante plataformas como BetterToken, el panel de control (Dashboard) registra el uso de input, output y cache tokens en cada llamada. Sin embargo, la monitorización del servidor solo mide el tráfico transmitido; no sustituye la auditoría interna de los archivos locales de configuración. Los parámetros de integración y endpoints compatibles pueden consultarse en BetterToken Docs.

Inventario de skills según la frecuencia de uso

Para organizar su espacio de trabajo, elabore una lista de todos los skills activos en el repositorio y en la configuración global (~/.claude/skills/).

Clasifíquelos según su frecuencia real de uso:

Como criterio general, si una instrucción solo se necesita una vez cada diez sesiones, no debe ocupar espacio continuo en el contexto.

Separación de directivas principales y recursos bajo demanda

Para optimizar el uso de tokens, estructure cada skill con un punto de entrada ligero respaldado por scripts ejecutables.

1. Optimización del frontmatter YAML

El campo description debe indicar con claridad cuándo activar la herramienta:

---
name: db-migrator
description: >-
  Utilice este skill para validar y aplicar migraciones de base de datos con Prisma al modificar esquemas.
---

Evite incluir fragmentos extensos de código en la cabecera. Mueva las tablas y referencias al directorio references/.

2. Delegación de lógica a scripts deterministas

En lugar de pedir al modelo que construya comandos complejos de validación a partir de explicaciones largas, encapsule la lógica en un script:

<!-- Dentro de SKILL.md -->
Para validar la integridad del esquema ejecute:
```bash
python3 scripts/validate_schema.py --strict

Esto reduce la extensión de `SKILL.md` y asegura resultados consistentes. Nunca desactive linters de seguridad o validaciones de tipos solo para ahorrar tokens; los controles deterministas deben mantenerse activos.

Verificación de detección y ejecución

Una vez estructurados los skills, compruebe que el modelo sigue reconociendo las instrucciones en el momento oportuno.

Paso 1: Comprobar sintaxis y rutas relativas

Asegúrese de que los archivos SKILL.md contienen YAML válido y que las rutas internas a los scripts existen:

# Comprobación de archivos y permisos del script
test -f .claude/skills/db-migrator/SKILL.md && echo "SKILL.md OK"
test -x .claude/skills/db-migrator/scripts/validate_schema.py && echo "Script executable OK"

Paso 2: Probar la activación en una sesión limpia

Inicie una nueva sesión y realice una consulta con términos propios de la tarea sin mencionar el nombre del skill:

«Necesito actualizar el modelo de usuario en Prisma y revisar la migración».

El agente debe:

1. Identificar la tarea a partir de la descripción en db-migrator.
2. Cargar el contenido de SKILL.md.
3. Sugerir la ejecución del script de validación correspondiente.

Paso 3: Evaluar el contexto inicial

Examine el comportamiento de la sesión. El objetivo es eliminar ruido y conservar espacio para el historial de trabajo, sin buscar un porcentaje teórico de ahorro. Mantenga activos únicamente los skills necesarios para el ciclo de desarrollo en curso.