Cada nueva sesión con un agente arranca de cero. Pegás el mismo checklist de deploy, la misma rúbrica de code review, el mismo protocolo de debugging — y cada compañero pega una versión apenas distinta. Después de rescatar suficientes proyectos con IA, te digo dónde muere la consistencia: acá.
En este deep-dive te muestro la solución en la que el ecosistema convergió en 2026: Agent Skills. El estándar abierto detrás de un repo comunitario de 275k estrellas, la librería oficial de Anthropic y un pack científico de 160+ skills — más un tutorial paso a paso para crear, instalar y verificar tu primer skill hoy.
1. El Problema: Cada Sesión del Agente Arranca de Cero
Los coding agents son amnésicos con superpoderes. Claude Code, Cursor, Codex, OpenCode — todos despiertan en una sesión nueva sin saber cómo shipea tu equipo: qué checks corren antes de un merge, cómo escriben migraciones, qué significa “listo” en tu repo. Y los devs compensan con tres malos hábitos.
El mega-prompt
Pegar un bloque de 2.000 palabras al inicio de cada sesión. Come contexto, diverge entre compañeros y se pudre en silencio.
El CLAUDE.md inflado
Meter todos los workflows en un archivo que carga completo en cada request — incluyendo el 90% irrelevante para la tarea actual.
Conocimiento tribal
Los seniors llevan el proceso real en la cabeza. Los juniors reciben respuestas distintas del agente y el code review se vuelve lotería.
El Error Más Común
Tratar el system prompt del agente como documentación. Los prompts no se versionan, no se testean y no se comparten. En el momento en que dos devs usan dos versiones distintas, tu “proceso estándar” es ficción. Los skills lo resuelven llevando los workflows repetibles a archivos que viven en git.
Es un patrón de project-rescue que veo todo el tiempo: el agente no es el problema, el sistema operativo que falta alrededor sí. Agent Skills son ese sistema operativo — paquetes de workflow chicos, versionados y auto-cargables que hacen que cada sesión se comporte igual.
2. Conceptos Mínimos (5 Minutos)
Un skill es una carpeta con un archivo SKILL.md adentro: frontmatter YAML (name + description) más instrucciones en Markdown. El agente lee la descripción, la matchea contra tu pedido y carga el cuerpo solo cuando aplica. Ese mecanismo de “cargar solo cuando aplica” se llama progressive disclosure, y es todo el punto.
SKILL.md
Frontmatter (~100 palabras: name en kebab-case, description como gatillo de cuándo usar) + cuerpo con el procedimiento real. Mantené el cuerpo bajo ~500 líneas.
Auto-trigger
La descripción es el gatillo. Si matchea la tarea, el agente carga el skill solo — sin slash command. La invocación explícita (“usá el skill de pdf…”) es el fallback.
Progressive disclosure
Metadata siempre visible, cuerpo bajo demanda, scripts y referencias solo cuando el cuerpo los pide. Los skills grandes cuestan cero contexto hasta usarse.
Skills vs vecinos
CLAUDE.md = memoria siempre activa. Subagents = quién hace el trabajo. MCP = cómo el agente toca herramientas. Skills = cómo se hace el trabajo. (Este mapa sale del curso de Claude Academy sobre skills.)
Dónde viven los skills (verificado, Sep 2026)
Scope personal aplica a todos los proyectos; scope de proyecto se commitea en git y lo comparte el equipo. Ante la duda, instalá a nivel proyecto.
Claude Code → ~/.claude/skills/ (personal) o .claude/skills/ (proyecto)Cursor → .cursor/skills/ (proyecto)Codex → ~/.codex/skills/ o ~/.agents/skills/ (universal)Claude.ai (pago) → Settings → Features → Custom Skills → Upload zip
3. Tutorial: Tu Primer Skill en 20 Minutos
Vamos a crear un skill de deploy-checklist desde cero, instalarlo a nivel proyecto, sumar un pack comunitario probado en batalla y verificar el gatillo. Cada comando fue verificado contra docs y repos actuales en septiembre 2026.
- Paso 1: Creá la carpeta y escribí el SKILL.md. La descripción debe decir cuándo aplica el skill — nunca resumir el procedimiento (esa trampa la vemos en la sección 4).
- Paso 2: Guardalo a nivel proyecto (.claude/skills/deploy-checklist/SKILL.md) para que todo el equipo lo reciba vía git. Los estándares personales van en ~/.claude/skills/.
- Paso 3: Mantené el cuerpo bajo ~500 líneas. Lo que sobre se parte en archivos de references/ o scripts/ que el agente corre bajo demanda.
- Paso 4: Instalá un pack comunitario probado para ver el patrón bien hecho: los skills oficiales de Anthropic, obra/superpowers o los científicos de K-Dense.
- Paso 5: Verificá el gatillo: pedile al agente una tarea que cubra el skill y confirmá que lo anuncia y lo sigue. Si se queda mudo, la descripción necesita mejores trigger words.
- Paso 6: Versioná todo. Los skills son carpetas vendorizadas — actualizás con git pull o reinstalando, y pineás a un commit conocido cuando un cambio upstream rompe tu flujo.
Template mínimo de SKILL.md
--- name: deploy-checklist description: Run before any production deploy or release PR. Use when the user asks to deploy, release, ship, or merge to main. --- # Deploy Checklist 1. Confirm the target branch is green in CI before anything else. 2. Run the migration dry-run and attach its output to the PR. 3. Verify rollback steps exist and name the person on call. 4. If any step fails, stop and report — never skip silently.
Instalar packs comunitarios (comandos verificados)
# Skills oficiales de Anthropic (~150k estrellas) — dentro de Claude Code: /plugin marketplace add anthropics/skills /plugin install document-skills@anthropic-agent-skills # obra/superpowers (~275k estrellas, 14 skills incl. TDD + debugging): npx skills add obra/superpowers # Skills científicos de K-Dense (~37k estrellas, 163 skills validados): npx skills add K-Dense-AI/scientific-agent-skills
Fuentes de este tutorial
- Estándar abierto Agent Skills — agentskills.io (vía spec/ de anthropics/skills) ↗
- anthropics/skills — librería oficial (document skills, skill-creator, frontend-design) ↗
- obra/superpowers — metodología SDLC de 14 skills por Jesse Vincent ↗
- K-Dense-AI/scientific-agent-skills — 163 skills científicos validados ↗
- Anthropic: Lessons from building Claude Code — how we use skills ↗
- Claude Academy: Introduction to Agent Skills (curso gratis) ↗
4. Errores Comunes (y Cómo Evitarlos)
La mayoría de los skills fallan por razones aburridas y arreglables. El equipo de Anthropic catalogó cientos de skills internos y encontró los mismos anti-patrones — y los mantenedores de obra/superpowers hasta reescribieron todas sus descripciones en diciembre 2025 tras descubrir uno a la fuerza.
La trampa de la descripción
Resumir el workflow dentro de la descripción hace que el agente siga el resumen y saltee el cuerpo del skill. Las descripciones solo deben decir cuándo usar el skill. A superpowers le costó una reescritura completa.
El mega-skill de 2.000 líneas
Un skill que cubre testing, deploy y code review en un archivo confunde el matcheo e inunda el contexto. Un skill, un trabajo; el resto va a references/ o a skills separados.
Scope equivocado
Preferencias personales instaladas a nivel proyecto molestan al equipo; estándares del equipo guardados en ~/.claude/skills/ nunca llegan al equipo. Regla: si un compañero lo necesita, vive en el repo.
Instalar sin auditar
Los skills pueden traer scripts ejecutables. Antes de instalar, leé el SKILL.md y cada archivo en scripts/: qué corre, qué toca, si llama a la red. ¿Skill no confiable? Scope de proyecto, nunca personal.
Shipear sin evals
Un skill sin testear es un rumor. Aplica el loop de skill-creator de Anthropic: draftealo, probalo contra prompts de test, compará outputs, iterá. Si no mergearías código sin tests, no shipees un skill sin tests.
Regla de oro
Enseñá una vez, reutilizá en todos lados: si te ves pegando las mismas instrucciones dos veces, ese texto es un skill esperando nacer. Archivos chicos con gatillo en git le ganan a prompts brillantes en el historial del chat — siempre.
Conclusión
Agent Skills convierten el babysitting de agentes en ingeniería: archivos de workflow versionados con gatillos claros, progressive disclosure para cuidar el contexto, y un ecosistema — packs oficiales de Anthropic, disciplina SDLC de superpowers, librería científica de K-Dense — que podés instalar en vez de reinventar.
Empezá esta semana: convertí tu checklist más pegado en un skill a nivel proyecto, instalá superpowers al lado y mirá cómo el code review deja de ser lotería. Si los agentes de tu equipo se comportan todos distinto, esa inconsistencia es justo lo que resuelvo en trabajo de project-rescue — escribime por la página de contacto.
Qué recordar
Estándar
- • Carpeta + SKILL.md
- • name + descripción gatillo
- • Spec en agentskills.io
Instalación
- • Scope proyecto en git
- • Plugin anthropics/skills
- • npx skills add <repo>
Mantenimiento
- • Auditar scripts/ primero
- • Evaluar antes de confiar
- • Pinear versiones sanas
