12 de abril de 2026 # Agent Skills: Guía completa  > [!tip]- De dónde viene esto y por qué lo publico > > Agent Skills es un estándar abierto -desarrollado originalmente por Anthropic, ahora liberado al ecosistema- para dar capacidades específicas a agentes de IA. La idea es simple: una carpeta con instrucciones y scripts que el agente descubre, activa cuando la tarea lo requiere, y ejecuta. Sin desarrollo custom. Sin reentrenar modelos. > > Lo que me parece relevante no es la tecnología en sí, sino lo que implica: los agentes están dejando de ser herramientas genéricas para convertirse en sistemas configurables por quien los usa. La ventaja ya no está solo en elegir el mejor modelo - está en saber empaquetarle el conocimiento adecuado. > > Esta guía viene de [agentskills.io](https://agentskills.io/). La publico porque cubre bien la parte que normalmente se omite: no solo qué son las skills, sino cómo escribirlas bien, cómo testearlas, y cómo implementar el soporte si construyes tu propio agente. Material denso, con criterio, que va al grano y sin relleno. > > Exactamente lo que busca este canal. ## 1. Qué son las Agent Skills Una **skill** es una carpeta con instrucciones, scripts y recursos que un agente de IA puede descubrir y usar bajo demanda. El archivo central es `SKILL.md`. ``` mi-skill/ ├── SKILL.md # Obligatorio: instrucciones + metadatos ├── scripts/ # Opcional: código ejecutable ├── references/ # Opcional: documentación adicional └── assets/ # Opcional: plantillas, recursos ``` **Idea clave**: los agentes son cada vez más capaces, pero les falta contexto específico para hacer trabajo real de forma fiable. Las skills les dan acceso a conocimiento procedimental y contexto de empresa/equipo/usuario que pueden cargar según la tarea. **Tres públicos, tres beneficios:** - **Creadores de skills**: construyes una vez, funciona en múltiples agentes compatibles. - **Agentes compatibles**: soportar skills permite que los usuarios amplíen capacidades sin desarrollo custom. - **Equipos y empresas**: capturan conocimiento organizacional en paquetes portables y versionables. **Qué pueden hacer:** - Empaquetar expertise de dominio (revisión legal, pipelines de datos, etc.) - Dar capacidades nuevas (crear presentaciones, analizar datasets, construir servidores MCP) - Convertir tareas multi-paso en workflows repetibles y auditables - Reutilizar la misma skill en diferentes productos compatibles --- ## 2. Cómo funcionan: Progressive Disclosure Las skills usan **revelación progresiva** para gestionar contexto eficientemente: |Nivel|Qué se carga|Cuándo|Coste en tokens| |---|---|---|---| |1. Catálogo|Nombre + descripción|Al iniciar sesión|~50-100 tokens/skill| |2. Instrucciones|Cuerpo completo de SKILL.md|Cuando la skill se activa|<5.000 tokens (recomendado)| |3. Recursos|Scripts, referencias, assets|Cuando las instrucciones los referencian|Variable| **El flujo:** 1. **Descubrimiento** → el agente escanea directorios y carga solo `name` + `description` de cada skill. 2. **Activación** → cuando la tarea del usuario encaja con una descripción, el agente lee el `SKILL.md` completo. 3. **Ejecución** → el agente sigue las instrucciones, cargando archivos referenciados o ejecutando scripts según necesite. Un agente con 20 skills instaladas NO paga el coste de 20 sets de instrucciones completos: solo de las que realmente usa. --- ## 3. El archivo SKILL.md: Especificación ### 3.1 Estructura Frontmatter YAML + cuerpo en Markdown: ```yaml --- name: pdf-processing description: Extract PDF text, fill forms, merge files. Use when handling PDFs. license: Apache-2.0 compatibility: Requires Python 3.14+ and uv metadata: author: example-org version: "1.0" allowed-tools: Bash(git:*) Bash(jq:*) Read --- # Instrucciones en Markdown aquí... ``` ### 3.2 Campos del frontmatter |Campo|Obligatorio|Restricciones| |---|---|---| |`name`|Sí|Máx. 64 chars. Solo minúsculas, números y guiones. Debe coincidir con el nombre del directorio padre.| |`description`|Sí|Máx. 1.024 chars. Describe qué hace y cuándo usarla.| |`license`|No|Nombre de licencia o referencia a archivo.| |`compatibility`|No|Máx. 500 chars. Requisitos de entorno.| |`metadata`|No|Map clave-valor arbitrario.| |`allowed-tools`|No|Herramientas pre-aprobadas (experimental).| ### 3.3 Reglas del name - Solo `a-z`, `0-9` y `-` - No empieza ni termina con `-` - No admite `--` consecutivos - Debe coincidir con el nombre de la carpeta ### 3.4 Cómo escribir una buena description ```yaml # ❌ Pobre description: Helps with PDFs. # ✅ Buena description: > Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. ``` ### 3.5 Directorios opcionales - **`scripts/`** → Código ejecutable. Autocontenido, con mensajes de error claros. - **`references/`** → Documentación adicional que el agente carga bajo demanda. Archivos enfocados y pequeños. - **`assets/`** → Plantillas, imágenes, tablas, esquemas. ### 3.6 Referencias a archivos Siempre rutas relativas desde la raíz de la skill. Evitar cadenas de referencias profundamente anidadas. Mantener `SKILL.md` por debajo de 500 líneas. ### 3.7 Validación ```bash skills-ref validate ./mi-skill ``` --- ## 4. Quickstart: Tu primera skill en 5 minutos **Ejemplo**: skill que lanza dados con un generador aleatorio. **Paso 1** — Crea `.agents/skills/roll-dice/SKILL.md`: ````yaml --- name: roll-dice description: > Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll. --- Para lanzar un dado, usa este comando que genera un número aleatorio de 1 al número de caras dado: ```bash echo $((RANDOM % <sides> + 1)) ```` Reemplaza `<sides>` con el número de caras (6 para dado estándar, 20 para d20). **Paso 2** — Abre VS Code con Copilot en modo Agent. Escribe `/skills` para confirmar que aparece. Pide "Roll a d20". **Lo que pasa por debajo:** 1. El agente escaneó y encontró la skill (solo leyó `name` + `description`). 2. Al pedirle dados, matcheó con la description y cargó el SKILL.md completo. 3. Siguió las instrucciones, adaptando el comando al número de caras. **Compatibilidad**: funciona en VS Code + Copilot, Claude Code, OpenAI Codex y cualquier agente compatible. --- ## 5. Mejores prácticas para crear skills ### 5.1 Parte de expertise real **No le pidas a un LLM que genere una skill sin contexto de dominio.** El resultado será genérico e inútil. **Dos caminos para crear skills de calidad:** - **Extrae de una tarea real**: completa una tarea con un agente, corrigiéndolo por el camino. Luego extrae el patrón reutilizable. Fíjate en: pasos que funcionaron, correcciones que hiciste, formatos de entrada/salida, contexto que tuviste que dar. - **Sintetiza desde artefactos del proyecto**: documentación interna, runbooks, specs de API, comentarios de code review, historial de commits (especialmente parches), casos de fallo reales. ### 5.2 Itera con ejecución real El primer borrador siempre necesita refinamiento. Ejecuta la skill contra tareas reales. Lee las trazas de ejecución del agente, no solo los resultados finales. Si el agente pierde tiempo en pasos improductivos, las causas comunes son: instrucciones demasiado vagas, instrucciones que no aplican a la tarea, o demasiadas opciones sin default claro. ### 5.3 Gasta contexto sabiamente Cada token de tu skill compite por la atención del agente con todo lo demás en la ventana de contexto. **Regla de oro**: añade lo que el agente NO sabría sin tu skill. Omite lo que ya sabe. ```markdown <!-- ❌ Demasiado verboso — el agente ya sabe qué es un PDF --> PDF (Portable Document Format) files are a common file format... <!-- ✅ Mejor — va directo a lo que el agente no sabe --> Use pdfplumber for text extraction. For scanned documents, fall back to pdf2image with pytesseract. ```` **Pregúntate** de cada pieza: "¿El agente haría esto mal sin esta instrucción?" Si no, elimínala. **Diseña unidades coherentes**: ni tan estrechas que necesites cargar varias para una tarea, ni tan amplias que sea difícil activarlas con precisión. **Apunta a detalle moderado**: instrucciones concisas y paso a paso con un ejemplo funcionando superan a documentación exhaustiva. ### 5.4 Calibra el nivel de control - **Da libertad** cuando múltiples enfoques son válidos. Explica el _porqué_ en vez de dar directivas rígidas. - **Sé prescriptivo** cuando las operaciones son frágiles, la consistencia importa, o hay una secuencia específica que seguir. **Da defaults, no menús:** ```markdown <!-- ❌ Demasiadas opciones --> You can use pypdf, pdfplumber, PyMuPDF, or pdf2image... <!-- ✅ Default claro con alternativa --> Use pdfplumber for text extraction. For scanned PDFs requiring OCR, use pdf2image with pytesseract instead. ``` **Favorece procedimientos sobre declaraciones**: enseña _cómo abordar_ una clase de problemas, no _qué producir_ para una instancia concreta. ### 5.5 Patrones para instrucciones efectivas **Secciones de Gotchas** — el contenido de mayor valor en muchas skills: ```markdown ## Gotchas - La tabla `users` usa soft deletes. Las queries deben incluir `WHERE deleted_at IS NULL`. - El user ID es `user_id` en la BD, `uid` en auth, y `accountId` en billing. Los tres son el mismo valor. ``` **Plantillas de formato de salida** — más fiables que describir el formato en prosa: ```markdown ## Estructura del informe # [Título del Análisis] ## Resumen ejecutivo [Un párrafo con hallazgos clave] ## Hallazgos principales - Hallazgo 1 con datos ## Recomendaciones 1. Recomendación accionable específica ``` **Checklists para workflows multi-paso:** ```markdown ## Workflow de procesamiento - [ ] Paso 1: Analizar el formulario (`scripts/analyze_form.py`) - [ ] Paso 2: Crear mapeo de campos (`fields.json`) - [ ] Paso 3: Validar mapeo (`scripts/validate_fields.py`) - [ ] Paso 4: Rellenar formulario (`scripts/fill_form.py`) - [ ] Paso 5: Verificar output (`scripts/verify_output.py`) ``` **Bucles de validación**: haz el trabajo → ejecuta validador → corrige → repite hasta que pase. **Plan-valida-ejecuta**: para operaciones destructivas o en lote, crea un plan intermedio en formato estructurado, valídalo contra fuente de verdad, y solo entonces ejecuta. --- ## 6. Optimizar las descriptions (triggering) La `description` lleva **todo el peso del triggering**. Si no transmite cuándo la skill es útil, el agente no la activará. ### 6.1 Principios para buenas descriptions - **Formulación imperativa**: "Use this skill when…" en vez de "This skill does…" - **Enfócate en la intención del usuario**, no en la implementación interna. - **Sé agresivo**: lista explícitamente contextos donde aplica, incluyendo cuando el usuario no nombre el dominio directamente. - **Conciso**: unas pocas frases. Máximo 1.024 caracteres. ### 6.2 Testeo sistemático con eval queries Crea ~20 queries realistas: 8-10 que deberían activar la skill y 8-10 que no. ```json [ { "query": "I've got a spreadsheet in ~/data/q4_results.xlsx...", "should_trigger": true }, { "query": "whats the quickest way to convert this json to yaml", "should_trigger": false } ] ``` **Para queries positivas**, varía: formalidad, explicitud, nivel de detalle, complejidad. Las más útiles son las que la skill ayudaría pero la conexión no es obvia. **Para queries negativas**, usa **near-misses** — queries que comparten keywords pero necesitan algo diferente. Ejemplos débiles: "Write a fibonacci function". Ejemplos fuertes: "write a python script that reads a csv and uploads each row to postgres" (involucra CSV, pero la tarea es ETL, no análisis). **Haz queries realistas**: incluye rutas de archivo, contexto personal, lenguaje casual, typos. ### 6.3 Ejecución y medición Ejecuta cada query varias veces (mínimo 3) por el no-determinismo del modelo. Calcula un **trigger rate** (fracción de ejecuciones donde se activó la skill). ### 6.4 Evitar overfitting con train/validation split - **Train (~60%)**: queries que usas para identificar fallos y guiar mejoras. - **Validation (~40%)**: queries reservadas para comprobar si las mejoras generalizan. ### 6.5 El bucle de optimización 1. **Evalúa** la description actual en train y validation. 2. **Identifica fallos** en el train set. 3. **Revisa la description**: si las positivas fallan → demasiado estrecha. Si las negativas se activan → demasiado amplia. No añadas keywords específicas de queries fallidas (eso es overfitting). Busca la categoría general. 4. **Repite** hasta que todas las queries del train pasen. 5. **Selecciona la mejor iteración** por su tasa de acierto en validation. 5 iteraciones suelen bastar. Antes y después: ```yaml # Antes description: Process CSV files. # Después description: > Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use this skill when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they don't explicitly mention "CSV" or "analysis." ``` --- ## 7. Evaluar la calidad del output de una skill ### 7.1 Diseñar test cases Cada test case tiene: **prompt** (realista), **expected output** (qué es éxito), **input files** (opcional). ```json { "skill_name": "csv-analyzer", "evals": [ { "id": 1, "prompt": "I have a CSV of monthly sales data...", "expected_output": "A bar chart image showing the top 3 months...", "files": ["evals/files/sales_2025.csv"] } ] } ``` Empieza con 2-3 test cases. No sobre-inviertas antes de ver resultados. ### 7.2 Ejecutar evals: con skill vs. sin skill Ejecuta cada test case dos veces: **con la skill** y **sin ella** (o con versión anterior). Esto te da un baseline para comparar. Cada ejecución debe empezar con contexto limpio. Captura tokens y duración para comparar coste. ### 7.3 Escribir assertions Añádelas **después** de ver los primeros outputs: ``` ✅ "The output file is valid JSON" — verificable programáticamente ✅ "The bar chart has labeled axes" — específico y observable ❌ "The output is good" — demasiado vago ❌ "The output uses exactly the phrase 'Total Revenue: $X'" — demasiado frágil ``` ### 7.4 Calificar (grading) Evalúa cada assertion contra los outputs reales. Registra PASS/FAIL con evidencia concreta. Para comparar dos versiones, usa **comparación ciega**: presenta ambos outputs a un LLM juez sin revelar cuál es cuál. ### 7.5 Agregar resultados ```json { "with_skill": { "pass_rate": 0.83, "tokens": 3800 }, "without_skill": { "pass_rate": 0.33, "tokens": 2100 }, "delta": { "pass_rate": 0.50, "tokens": 1700 } } ``` El delta te dice qué cuesta la skill (más tokens) y qué te compra (mayor tasa de acierto). ### 7.6 Analizar patrones - Elimina assertions que siempre pasan en ambas configuraciones (no aportan info). - Investiga las que siempre fallan en ambas (la assertion puede estar rota). - Estudia las que pasan CON skill pero fallan SIN ella (ahí la skill aporta valor). - Si hay alta varianza entre runs, las instrucciones probablemente son ambiguas. ### 7.7 El bucle de iteración 1. Da las señales de eval + el SKILL.md actual a un LLM → propone mejoras. 2. Revisa y aplica los cambios. 3. Re-ejecuta todos los test cases en un nuevo directorio `iteration-N+1/`. 4. Califica y agrega. 5. Revisa con humano. Repite. Para cuando estés satisfecho, el feedback esté consistentemente vacío, o no haya mejora significativa entre iteraciones. --- ## 8. Usar scripts en skills ### 8.1 Comandos one-off Si un paquete existente hace lo que necesitas, referéncialo directamente sin crear un directorio `scripts/`: |Herramienta|Ecosistema|Ejemplo| |---|---|---| |`uvx`|Python|`uvx [email protected] check .`| |`npx`|Node.js|`npx eslint@9 --fix .`| |`bunx`|Bun|`bunx create-vite@6 my-app`| |`deno run`|Deno|`deno run npm:create-vite@6 my-app`| |`go run`|Go|`go run golang.org/x/tools/cmd/[email protected] .`| |`pipx`|Python|`pipx run 'black==24.10.0' .`| Fija siempre versiones. Declara prerequisitos en el SKILL.md. Cuando un comando se complica, muévelo a un script testeado. ### 8.2 Referenciar scripts desde SKILL.md Rutas relativas desde la raíz del directorio de la skill: ```markdown ## Scripts disponibles - **`scripts/validate.sh`** — Valida archivos de configuración - **`scripts/process.py`** — Procesa datos de entrada ## Workflow 1. Ejecuta validación: ```bash bash scripts/validate.sh "$INPUT_FILE" ``` ### 8.3 Scripts autocontenidos con dependencias inline Varios lenguajes soportan declaración de dependencias dentro del propio script: **Python (PEP 723):** ```python # /// script # dependencies = ["beautifulsoup4"] # /// from bs4 import BeautifulSoup # ... ```` Ejecutar con: `uv run scripts/extract.py` **Deno** (imports npm:/jsr: nativos), **Bun** (auto-install), **Ruby** (bundler/inline) — todos funcionan de forma similar. ### 8.4 Diseñar scripts para uso agéntico **Reglas esenciales:** - **Sin prompts interactivos** — los agentes ejecutan en shells no interactivos. Acepta todo vía flags, variables de entorno o stdin. - **Documenta con `--help`** — es la forma principal en que el agente aprende la interfaz del script. Incluye descripción, flags y ejemplos. - **Mensajes de error útiles** — di qué falló, qué se esperaba, y qué intentar. - **Output estructurado** — JSON/CSV/TSV sobre texto libre. Datos a stdout, diagnósticos a stderr. **Consideraciones adicionales:** - **Idempotencia**: "crear si no existe" es más seguro que "crear y fallar si duplicado". - **Soporte dry-run**: para operaciones destructivas. - **Códigos de salida significativos**: distintos para distintos tipos de fallo. - **Defaults seguros**: operaciones destructivas deben requerir flags explícitos (`--confirm`, `--force`). - **Output de tamaño predecible**: muchos agentes truncan output largo (10-30K chars). Ofrece resumen por defecto y flags como `--offset` para paginación. --- ## 9. Implementar soporte de skills en tu agente (para implementadores) ### 9.1 Paso 1: Descubrir skills **Dónde escanear** (agente local): |Scope|Ruta|Propósito| |---|---|---| |Proyecto|`<project>/.<tu-cliente>/skills/`|Ubicación nativa de tu cliente| |Proyecto|`<project>/.agents/skills/`|Interoperabilidad cross-client| |Usuario|`~/.<tu-cliente>/skills/`|Ubicación nativa de tu cliente| |Usuario|`~/.agents/skills/`|Interoperabilidad cross-client| **Qué escanear**: subdirectorios que contengan un archivo llamado exactamente `SKILL.md`. Saltar `.git/`, `node_modules/`. Limitar profundidad (4-6 niveles) y directorios (máx ~2000). **Colisiones de nombre**: skills de proyecto tienen prioridad sobre las de usuario. Loguea un warning cuando una skill sea sobreescrita. **Confianza**: considera gatear la carga de skills de proyecto a un check de confianza (prevenir que repos untrusted inyecten instrucciones). **Agentes cloud/sandbox**: las skills de proyecto viajan con el código clonado. Las de usuario necesitan provisionarse externamente (clonar repo de config, URLs de skills, upload via UI). ### 9.2 Paso 2: Parsear SKILL.md 1. Encontrar los delimitadores `---`. 2. Parsear el bloque YAML. Extraer `name` y `description`. 3. Todo después del segundo `---` es el cuerpo. **Manejo de YAML malformado**: la causa más común es valores sin comillas con dos puntos. Implementa un fallback que los envuelva en comillas. **Validación leniente**: warn en problemas cosméticos, carga la skill igual. Solo salta la skill si falta la description o el YAML es completamente imparseable. ### 9.3 Paso 3: Mostrar el catálogo al modelo Incluye `name`, `description` y `location` en formato estructurado (XML, JSON, lista) en el system prompt o en la descripción de una tool de activación. Añade instrucciones breves sobre cómo y cuándo usar skills. Si no hay skills disponibles, omite el catálogo entero. ### 9.4 Paso 4: Activar skills **Activación por el modelo:** - **File-read**: el modelo usa su herramienta de lectura de archivos con la ruta del SKILL.md. La más simple. - **Tool dedicada**: registra una tool `activate_skill` que toma un nombre y devuelve el contenido. Más control. **Activación por el usuario:** comando slash o sintaxis de mención (`/skill-name`). **Wrapping estructurado** (recomendado para tool dedicada): ```xml <skill_content name="pdf-processing"> [cuerpo del SKILL.md] Skill directory: /home/user/.agents/skills/pdf-processing <skill_resources> <file>scripts/extract.py</file> <file>references/pdf-spec-summary.md</file> </skill_resources> </skill_content> ``` **Permisos**: allowlistea los directorios de skills para que el modelo pueda leer recursos sin diálogos de permiso. ### 9.5 Paso 5: Gestionar contexto a lo largo del tiempo - **Protege el contenido de skills del context compaction**: exime las skill tool outputs del pruning. Perder instrucciones mid-conversation degrada silenciosamente el rendimiento. - **Deduplica activaciones**: trackea qué skills ya están en contexto para no inyectar las mismas instrucciones dos veces. - **Delegación a subagentes** (avanzado, opcional): ejecuta la skill en una sesión de subagente separada que devuelve un resumen al contexto principal. --- ## 10. Clientes compatibles Agent Skills es soportado por herramientas líderes de desarrollo con IA, incluyendo Claude Code, VS Code + GitHub Copilot, y OpenAI Codex, entre otros. El estándar es abierto a contribuciones del ecosistema. **Recursos:** - GitHub: [github.com/agentskills/agentskills](https://github.com/agentskills/agentskills) - Discord: [discord.gg/MKPE9g8aUy](https://discord.gg/MKPE9g8aUy) - Librería de referencia: [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) (validación + generación de XML para prompts) - Skills de ejemplo: [github.com/anthropics/skills](https://github.com/anthropics/skills) --- _Fuente: [agentskills.io](https://agentskills.io/home) — contenido adaptado y sintetizado con fines formativos._ --- Publicado el 12 de abril de 2026, [LinkedIn](https://www.linkedin.com/posts/davidhurtadotoran_mentesinquietas-share-7448990433646489602-Td_h?utm_source=share&utm_medium=member_desktop&rcm=ACoAAAAT5UsBH3ISG9LTxrgEnB7glCf9CerKWno), [Substack](https://substack.com/@davidhurtado/note/c-242080449?r=4uyjfg&utm_source=notes-share-action&utm_medium=web), [X](https://x.com/dhtoran/status/2043224979940999271?s=20)