La Verdad Incómoda Sobre las Habilidades de Agentes

En diciembre de 2025, Anthropic publicó Agent Skills como un estándar abierto. Microsoft, Cursor y otros lo adoptaron. Ahora hay una especificación en agentskills.io, una estructura de directorios, requisitos de frontmatter YAML y todo un ecosistema.

Pero antes de sumergirnos en marcos de trabajo y especificaciones, entendamos qué son realmente las habilidades.

Lo que Anthropic Dice que Son las Habilidades

De acuerdo a la documentación oficial:

Las Agent Skills son capacidades modulares que extienden la funcionalidad de Claude. Cada Habilidad empaqueta instrucciones, metadatos y recursos opcionales (scripts, plantillas) que Claude utiliza automáticamente cuando son relevantes.

La idea clave del blog de ingeniería de Anthropic: las habilidades son recursos reutilizables basados en el sistema de archivos que dan a Claude experiencia específica del dominio. En lugar de explicar lo mismo en cada conversación, lo escribes una vez como una habilidad.

El Problema que Resuelven las Habilidades

Sin habilidades:

• Tienes que re-explicar procedimientos en cada sesión
• El contexto se llena de instrucciones repetidas
• No hay consistencia entre conversaciones

Con habilidades:

• Escribes instrucciones una vez
• Se cargan solo cuando son relevantes
• Comportamiento consistente entre sesiones

Esa es la propuesta. Y tiene sentido.

La Estructura Oficial

La especificación de Anthropic requiere una estructura específica:

.claude/skills/youtube-transcribe/
├── SKILL.md              # Required
├── scripts/
│   └── transcript.sh     # Optional
└── references/
    └── api-docs.md       # Optional

El archivo SKILL.md necesita frontmatter YAML:

---
name: youtube-transcribe
description: Transcribe YouTube videos to text. Use when user wants to extract transcript from a YouTube URL.
---

# YouTube Transcription

To transcribe a video:
1. Run: `scripts/transcript.sh "<youtube-url>"`
2. Output saves to: `transcripts/<video-id>.txt`

Divulgación Progresiva

Anthropic diseñó las habilidades alrededor de tres niveles de carga:

La idea: carga solo lo que necesitas, cuando lo necesitas. No vuelques todo en cada conversación.

Esta es una arquitectura genuinamente ingeniosa para la gestión de contexto.

Ahora, La Verdad Incómoda

Aquí está lo que la especificación no enfatiza:

Las habilidades son solo texto.

¿El frontmatter YAML? Se analiza como texto para el prompt. ¿La estructura de directorios? Una convención para la organización. ¿La "divulgación progresiva"? Claude leyendo archivos del disco.

Si eliminas el marco, una habilidad es:

• Una descripción (para que Claude sepa cuándo usarla)
• Instrucciones (cómo hacer la cosa)
• Tal vez un script (para ejecutar)

Eso es todo.

Qué Significa Esto en la Práctica

Considera estos dos enfoques:

Enfoque A: Habilidad Formal

.claude/skills/youtube-transcribe/SKILL.md

---
name: youtube-transcribe
description: Transcribe YouTube videos to text files
---

# YouTube Transcription
Run: bun scripts/youtube-transcript.sh "<url>"

Enfoque B: Guía Simple

guides/how-to-transcribe-youtube.md

# How to Transcribe YouTube Videos
Run: bun scripts/youtube-transcript.sh "<url>"

Para Claude, estos son casi idénticos. Ambos son archivos de texto con instrucciones. Ambos se pueden encontrar buscando. Ambos le dicen a Claude qué hacer.

La diferencia:

• Enfoque A: El frontmatter se precarga al iniciar (~100 tokens)
• Enfoque B: Claude busca cuando necesita la información

¿Vale la pena precargar la descripción de la sobrecarga de estructura? A veces sí, a veces no.

Cuándo la Estructura Ayuda

La estructura de Anthropic realmente ayuda cuando:

Tienes muchas habilidades y necesitas detectabilidad

Si tienes 50 capacidades, precargar descripciones le permite a Claude saber que existen sin leer los 50 archivos. Los metadatos actúan como un índice.

Quieres invocación de comandos de barra

Las habilidades se convierten en comandos /youtube-transcribe. Los usuarios pueden invocarlas directamente. Ese es un beneficio UX real.

Necesitas restricciones de herramientas

El campo allowed-tools restringe lo que puede hacer una habilidad. Beneficio de seguridad para operaciones sensibles.

Estás distribuyendo habilidades a otros

El estándar abierto significa que las habilidades funcionan en Claude Code, Cursor, VS Code. La portabilidad importa.

Cuándo las Guías Simples Ganan

Pero a menudo, las guías de markdown simple funcionan igual de bien:

Procedimientos únicos

# Deploy to Production
1. Run tests: `bun test`
2. Build: `bun run build`
3. Deploy: `./deploy.sh production`

¿Necesita esto ser una habilidad formal? Probablemente no. Es una guía. Claude la encuentra cuando es relevante.

Conocimiento específico del proyecto

# Our Brand Voice
- Professional but approachable
- No jargon unless explained
- Examples over abstractions

Esto es contexto, no una capacidad. Un archivo markdown en docs/ está bien.

Referencias rápidas

# API Credentials
- Google Analytics: Property 478766521
- Mailgun: Check .env for MAILGUN_API_KEY
- Sentry: Project teamday-cc

Información de índice. No necesita divulgación progresiva.

El Espectro

Las habilidades existen en un espectro desde trivial hasta comprensivo:

Frases de Una Línea (tal vez no necesiten habilidades formales)

Email notifications: bun scripts/mailgun.send.js --to="x" --subject="y"

Referencias Rápidas (fronterizo)

# Google Analytics
Use the mcp__google-analytics tools.
Property ID: 478766521
Common queries: pageviews, sessions, top pages

Guías Paso a Paso (la habilidad formal tiene sentido)

# Add YouTube Video to Newsfeed

1. Fetch transcript
2. Extract metadata with curl (not WebFetch!)
3. Create feed post
4. Update embeddings
5. Extract entities
6. Trigger translations

Flujos de Trabajo Comprensivos (definitivamente una habilidad)

Procedimientos de múltiples pasos con scripts, validación, manejo de errores. La habilidad de newsfeed que usamos tiene 250+ líneas con subdocumentos para tareas específicas.

Cuanto más compleja sea la capacidad, más se amortiza la estructura formal.

El Sistema de Archivos Es Tu Amigo

Aquí está lo que el blog de ingeniería de Anthropic enfatiza y que a menudo se pasa por alto:

Claude tiene acceso al sistema de archivos. Los scripts se ejecutan a través de bash. Los archivos de referencia existen en el disco. Puedes agrupar efectivamente materiales de referencia ilimitados.

Claude puede:

• Buscar archivos: grep -r "transcribe" docs/
• Leer lo que encuentra: Read: docs/how-to-transcribe.md
• Ejecutar scripts: bash scripts/transcribe.sh

El descubrimiento progresivo no requiere el marco de habilidades. Requiere una buena organización de archivos y una IA que sepa cómo buscar.

El marco de habilidades formaliza esto con metadatos. Pero el mecanismo subyacente es solo navegación del sistema de archivos.

El Contexto Es Todo

La idea real del diseño de Anthropic: las ventanas de contexto son limitadas.

Se dice que el system prompt de Claude Code es de 72kb. Eso es ~18,000 tokens antes de que siquiera comiences a trabajar. Cada descripción de habilidad se suma a esto.

El diseño de divulgación progresiva aborda esto:

• Solo metadatos al iniciar (pequeño)
• Instrucciones completas cuando se dispara (medio)
• Scripts/referencias cuando sea necesario (ilimitado, no en contexto)

Pero obtienes el mismo beneficio de:

• System prompt mínimo
• Claude busca docs cuando es necesario
• Lee solo lo que es relevante

El principio importa más que la implementación.

Lo que Realmente Importa

Después de construir docenas de flujos de trabajo de IA, aquí está lo que hemos aprendido:

1. Las Instrucciones Claras Superan la Estructura Ingeniosa

# Generate Blog Cover

We use FAL AI. Images save to public/images/.

Run:
bun scripts/generate-image.ts "prompt" name.webp

Good prompts:
- Include style ("minimalist illustration")
- Include subject ("AI agents collaborating")
- Include mood ("professional, tech-forward")

Claude sigue esto ya sea una habilidad formal o un archivo de documentación.

2. La Detectabilidad es Real

Si Claude no puede encontrar tus instrucciones, la estructura no importa. Ya sea a través de descripciones de habilidades o buenos nombres de archivo, haz que las cosas sean encontrables.

• ✅ guides/how-to-transcribe-youtube.md
• ✅ Habilidad con descripción clara
• ❌ notes/misc/stuff-v2-final.md

3. Los Scripts Resuelven la Complejidad

Cuando las instrucciones se vuelven complejas, escribe un script:

# Instead of 20 lines of instructions:
bun scripts/add-video-to-newsfeed.ts "<youtube-url>"

El script encapsula la complejidad. La habilidad simplemente documenta cómo invocarlo.

4. Itera Basado en Fallos

Cuando Claude hace algo mal:

• ¿Instrucción poco clara? → Mejora el texto
• ¿Información faltante? → Agrégala
• ¿No puedes encontrarla? → Mejor nombre o agregar al índice de habilidades

No agregues reglas defensivas. Arregla el problema real.

La Conclusión

Anthropic construyó un sistema reflexivo para organizar capacidades de IA. La divulgación progresiva es ingeniosa. El estándar abierto permite portabilidad. Los comandos de barra mejoran la UX.

Pero aquí está la verdad incómoda:

Las habilidades son solo instrucciones de texto que Claude lee de archivos.

El marco agrega:

• Descripciones precargadas (índice)
• Invocación de comandos de barra
• Restricciones de herramientas
• Portabilidad multiplataforma

Estos son beneficios reales para configuraciones complejas con muchas capacidades.

Pero para el trabajo diario:

• Un archivo markdown bien nombrado funciona
• Claude puede buscar y encontrar cosas
• Las instrucciones claras importan más que la estructura
• El sistema de archivos ya es un sistema de descubrimiento

No sobrecompliques. Comienza con guías simples. Agrega estructura de habilidad formal cuando los beneficios justifiquen la sobrecarga.

Escribe claramente. Organiza razonablemente. Deja que Claude haga su trabajo.

Usamos ambos enfoques en TeamDay. Habilidades formales para flujos de trabajo complejos como la gestión de newsfeed. Guías simples para procedimientos únicos. La clave es hacer coincidir la herramienta con la tarea.