Por qué los repositorios más virales de GitHub son archivos Markdown
Markdown se está convirtiendo en el formato de paquete para el comportamiento de los agentes de IA.
Hace unos años, el repo más popular de la semana en GitHub solía ser algo que podías ejecutar.
Un framework. Una base de datos. Un package manager. Una CLI. Un runtime de modelos.
Ahora, uno de los artefactos más virales para developers puede ser un archivo markdown.
No un paquete con un README en markdown.
El markdown es lo único que hay en el paquete.
Suena absurdo hasta que recuerdas qué hacen los agentes de IA para coding antes de tocar tu codebase.
Leen instrucciones.
Por eso importan las AI agent skills. Las AI agent skills son paquetes reutilizables de instrucciones que enseñan a un agente de IA cómo ejecutar un workflow específico. Pueden incluir instrucciones en markdown, ejemplos, scripts, referencias y otros recursos que el agente carga cuando la tarea los necesita.
Identifica dónde y cómo aplicar IA desde hoy con el GPT Arquitecto IA completamente gratis.
Lo recibes en el primer email que te mando al suscribirte
Una librería le da nueva funcionalidad al software.
Una skill le da mejor comportamiento a un agente.
Esa diferencia explica por qué los archivos markdown se están convirtiendo en artefactos serios de ingeniería. No reemplazan los tests, CI, la arquitectura ni las code reviews. Están aguas arriba de todo eso. Influyen en el código que escribe el agente, los tests que decide añadir, los riesgos que comprueba y las preguntas que hace antes de tocar el repo.
Markdown se está convirtiendo en el formato de paquete para el comportamiento de los agentes.
En este artículo aprenderás
Qué son las AI agent skills y cómo ayudan a los agentes de coding a ejecutar workflows repetibles.
En qué se diferencian las agent skills de
CLAUDE.md,AGENTS.md,SKILL.mdy MCP.Cómo escribir un archivo
SKILL.mdpráctico con instrucciones, ejemplos, scripts y recursos.Cuándo no usar agent skills, y cuándo son mejores los tests, CI, linters, instrucciones de repo o MCP.
Por qué los repositorios markdown se están convirtiendo en artefactos open source valiosos para equipos de software.
¿Qué son las AI Agent Skills?
Las AI agent skills son carpetas o archivos reutilizables que empaquetan instrucciones, ejemplos, scripts y recursos para un workflow específico.
OpenAI describe las Agent Skills como carpetas de instrucciones, scripts y recursos que los agentes pueden descubrir y usar para tareas concretas. Thoughtworks usa una definición parecida en su Technology Radar: las skills modularizan el contexto empaquetando instrucciones, scripts ejecutables y recursos asociados, y los agentes las cargan solo cuando las necesitan.
Esa parte de “solo cuando las necesitan” importa.
Un archivo gigante de instrucciones siempre activas acaba metiendo ruido. Eso ya fue un problema cuando MCP salió por primera vez. El agente ve reglas que no aplican a la tarea actual. Las restricciones importantes compiten con detalles aleatorios.
Una skill es diferente. Es memoria de workflow just-in-time.
Por ejemplo:
Una skill de code review que revisa PRs buscando regresiones de comportamiento, riesgos de seguridad, pérdida de datos, tests ausentes y abstracciones peligrosas.
Una skill de release notes que sigue el estilo del changelog de la empresa.
Una skill de crítica de design docs que comprueba supuestos, modos de fallo, planes de despliegue y riesgo operativo.
Lo importante no es que el archivo sea markdown.
Lo importante es que el agente puede cargar una forma repetible de pensar justo en el momento del trabajo.
Por qué los agentes de IA para coding necesitan skills
He visto a ingenieros competentes juzgar agentes de IA antes de configurar el entorno en el que operan esos agentes.
La queja suele ser una versión de esto:
“La IA no es mejor que yo.”
Vale. Pero la pregunta que falta es:
“¿Qué le he enseñado sobre cómo trabajo?”
No preguntes si la IA es buena. Pregunta cómo hacer que la IA trabaje para ti.
La mayoría de los agentes de coding son generalistas por defecto. No conocen los estándares de review de tu equipo. No conocen la profundidad de testing que prefieres. No saben qué archivos son peligrosos de tocar. No conocen la diferencia entre “haz que funcione” y “haz el cambio seguro más pequeño”.
Así que improvisan.
Y cuando un agente improvisa dentro de un codebase, tú lo pagas en comentarios de code review.
Repites el mismo feedback. “Deja de tocar archivos no relacionados”. “Añade tests antes de dar la tarea por terminada”. “No crees abstracciones nuevas”.
El agente no siempre es el problema.
El problema son las instrucciones operativas que faltan.
Aquí fue donde me ayudó el modelo mental de “factory defaults”. Nunca esperaría que una persona nueva entrara en un equipo y supiera al instante nuestro riesgo de deploy, cultura de testing, patrones de nombres, ownership del código y nivel de exigencia en review. Le daría contexto. Le apuntaría a los docs.
Después observaría cómo trabaja y refinaría la guía.
Eso es lo que tenemos que hacer también con los agentes.
Para profundizar en cómo la context engineering ayuda a los ingenieros de software a obtener mejores resultados con herramientas de IA para coding, lee:
Skills vs CLAUDE.md vs AGENTS.md vs MCP
El error es preguntar qué archivo es mejor.
La pregunta útil es qué tipo de instrucción, memoria o capacidad estás intentando codificar.
Usa un idea file cuando quieras compartir un patrón reutilizable de producto, sistema o arquitectura que un agente pueda adaptar al contexto de una persona. El archivo debería explicar la idea de alto nivel, la arquitectura base, las operaciones, los tradeoffs y las restricciones importantes.
Usa CLAUDE.md cuando necesites guía a nivel de repo para Claude Code. Buenos ejemplos son la arquitectura del proyecto, comandos de test, convenciones de código, operaciones prohibidas, notas de deploy y trampas de desarrollo local.
Usa AGENTS.md cuando necesites guía a nivel de repo para cualquier herramienta. Buenos ejemplos son la arquitectura del proyecto, comandos de test, convenciones de código, operaciones prohibidas, notas de deploy y trampas de desarrollo local. El proyecto agentsmd/agents.md lo describe como un README para agentes: un lugar predecible donde dar contexto e instrucciones de proyecto a los agentes de coding.
GitHub Copilot también soporta archivos AGENTS.md en cualquier parte de un repositorio, donde el archivo más cercano en el árbol tiene prioridad.
Solo si trabajas con un agente que no soporta AGENTS.md, usa su archivo específico, como CLAUDE.md.
Usa skills cuando el workflow sea reutilizable entre proyectos, solo sea relevante a veces y tenga pasos, ejemplos y expectativas de output.
Usa MCP cuando el agente necesite acceso en vivo a herramientas, bases de datos, APIs, calendarios, documentos o sistemas internos. El problema no es “piensa de esta manera”. El problema es “llama a este sistema de forma segura y devuelve datos estructurados”. Muchas veces puedes sustituir MCP por una CLI local, pero entonces debes dar instrucciones en una skill sobre cómo instalarla si no está disponible y cómo autenticarse.
Cuando empecé a verlo así, la arquitectura se volvió menos confusa.
Si el agente sigue olvidando cómo funciona el repo, escribe memoria de repo. Más archivos markdown. Si el agente sigue haciendo mal un workflow recurrente, escribe una skill. Más archivos markdown. Si el agente necesita llamar a un sistema real, dale una herramienta MCP o una CLI. Y puedes envolver “cómo usarla” en una skill, así que más markdown.
Por qué los repositorios markdown están ganando en GitHub
El open source tradicional distribuía funcionalidad.
Una librería te daba código que llamar. Un framework te daba estructura sobre la que construir.
Los repositorios markdown para agentes distribuyen comportamiento.
Le dicen a un agente de IA cómo revisar, planificar, editar, testear, escribir o evitar dañar tu sistema. Es un tipo diferente de artefacto. Se parece menos a importar un paquete y más a dar a una persona nueva las normas del equipo antes de que abra su primer pull request.
Estos repos ya existían antes de la IA. Por ejemplo, Google publicó en GitHub sus guías internas de estilo para muchos lenguajes de programación. La diferencia principal es el volumen: un ingeniero las consultaría cuando tuviera dudas. Los agentes de IA pueden consultar archivos markdown en cada ejecución.
Con humanos, un archivo markdown era documentación.
Con agentes, un archivo markdown puede cambiar el trabajo futuro.
Sé que “influir en el output de agentes de IA” suena menos impactante que “llamar a una función en una librería”. Pero en realidad es más útil porque es agnóstico al agente de IA y funciona con cualquier lenguaje de programación. Cambia el siguiente código que escribe el agente. Cambia los comentarios de review que deja. Cambia los supuestos que acepta.
Por eso las stars y los forks significan algo diferente ahora.
Una star ya no es solo aplauso por código. Es una señal de que más gente se está beneficiando de ese comportamiento. Un fork puede significar: “quiero personalizar esto para mi caso de uso”. Y es más fácil personalizar markdown que personalizar código, al menos antes de la IA.
No me malinterpretes: sigue habiendo muchísimo espacio para software open source. Pero para utilidades simples que resuelven casos estrechos, la IA puede hacerlas de una pasada, así que un archivo markdown puede ser más útil.
Las instrucciones legibles por agentes son los artefactos open source de 2026.
Ese es el cambio.
Un buen siguiente paso es este desglose de cómo el AI harness convierte a los agentes en compañeros de equipo más fiables:
https://newsletter.arquitecturasoftware.com/p/harness-engineering-ia
El momento CLAUDE.md de Karpathy
El repo forrestchang/andrej-karpathy-skills se convirtió en el ejemplo público más limpio de este patrón.
La última vez que miré GitHub, el repo tenía aproximadamente 104k stars y 10.2k forks.
El número exacto no es lo importante.
Lo absurdo es lo importante.
El artefacto central era minúsculo: un archivo CLAUDE.md de 2.3 KB con cuatro principios y sin código. Son muchas stars de GitHub por byte subido.
Eso suena extraño si todavía piensas que el valor open source solo significa código. Los principios correctos para dirigir mis agentes de IA en todo su trabajo pueden ser más útiles que una librería que solo conectar para un caso de uso.
Qué hacen diferente las buenas agent skills
Las buenas agent skills no son comunes.
Una skill debería hacer un tipo de trabajo. Code review. Planificación de migraciones. Generación de tests. Generación de release notes.
Si la skill intenta ser todo el proceso de ingeniería, se convierte en otro archivo de instrucciones hinchado. El agente no puede enrutarla limpiamente. Los humanos no pueden mantenerla. Y los equipos dejan de confiar en ella.
Las buenas agent skills también son activables.
La descripción es lógica de routing, no decoración.
Si escribes “usa esto para trabajo de ingeniería”, el agente no ha aprendido casi nada. Si escribes “usa esto al revisar código antes de merge, especialmente cuando el cambio toca persistencia, auth o billing”, el agente tiene muchas más probabilidades de cargarla en el momento correcto.
Las buenas skills son procedimentales.
Esto es lo que el LLM recibirá como prompt.
Sin una skill:
Review this PR.
Con una skill:
Review this PR for behavioral regressions, data loss, security risk, missing tests, and unnecessary abstractions. Read the surrounding files before commenting. Return only findings that would block or materially improve the change...
Esa diferencia cambia el output del agente de IA.
Las buenas skills también incluyen restricciones negativas. Dile al agente qué no debe hacer antes de que dañe el codebase. “No reescribas archivos no relacionados”. “No inventes abstracciones sin una petición explícita del usuario”. “No asumas lógica de negocio en silencio”. “No te saltes tests cuando toques comportamiento compartido”.
Normalmente escribirás esas restricciones negativas después de usar la skill y encontrar malos outputs.
La parte valiosa es el juicio codificado.
Un ejemplo mínimo de SKILL.md
Una skill práctica no necesita ser larga.
Necesita ser lo bastante específica para que el agente sepa cuándo cargarla, qué inspeccionar, qué evitar y cómo devolver el resultado.
Puedes usar IA para crear tus propias skills. Solo tienes que revisar meta-skills como esta.
Puedes empezar con un solo archivo markdown, pero el formato más amplio de una skill puede ir más allá. Una carpeta real de skill podría verse así:
code-review/
SKILL.md
scripts/
references/
examples/
SKILL.mdcontiene el routing y el workflow.scripts/contiene helpers ejecutables opcionales.references/contiene los docs que el agente debería consultar.examples/muestra outputs esperados.
Por eso decir que “las skills son solo prompts” se queda corto. Un prompt suele ser una instrucción. Una skill es un paquete reutilizable de capacidad. Mis mejores resultados han venido de tener scripts estrechos que resuelven un problema de forma determinista, envueltos en una skill que deja al agente decidir cuándo ejecutar cada uno.
Para entender por qué prompt engineering vs spec engineering cambia cómo los ingenieros senior usan herramientas de IA para coding, lee:
Cuándo no usar agent skills
No uses una skill cuando necesitas enforcement determinista
Usa CI, tests, linters, sistemas de tipos, policy engines y code owners. Una skill puede recordar a un agente que añada tests. No puede probar correctness. Puede que el agente ni siquiera la cargue.
La clave es que puedes usar skills para indicarle al agente que ejecute ciertos comandos. Eso te da lo mejor de ambos mundos: el determinismo de los comandos y la fiabilidad de la IA interpretando qué hacer con el output de esos comandos.
No uses una skill cuando el agente necesita acceso en vivo a sistemas externos
Usa MCP, una CLI local u otra interfaz controlada de herramientas. Las skills son buenas para memoria de workflow. Las herramientas son mejores para datos vivos y acciones reales.
No uses una skill para hechos del repo que siempre deberían cargarse
Usa AGENTS.md, CLAUDE.md, GEMINI.md, custom instructions del repositorio u otro archivo de memoria de repo. Si el agente siempre necesita saber cómo se ejecutan los tests o qué package manager usa el repo, eso es contexto del proyecto, no una skill específica de tarea.
No copies skills de terceros a ciegas
Esta es la parte que creo que los ingenieros deben tomarse en serio. Thoughtworks advierte explícitamente contra reutilizar skills de terceros sin revisarlas porque pueden introducir riesgo de seguridad en la supply chain.
Ya hemos visto muchos ataques de supply chain en dependencias que incorporas a tus proyectos de software. Trata las skills como una dependencia: debes tener cuidado con qué versión añades, verificar que viene de una fuente de confianza, etc.
Una skill puede decirle a un agente qué inspeccionar, qué ejecutar, qué ignorar y qué devolver. Si incluye scripts, comandos de shell, credenciales, pasos de deploy, operaciones de archivos o servicios externos, trátala como infraestructura cercana al código.
Todo este artículo trata sobre lo impactantes que son las skills. Eso también las hace peligrosas.
Cómo las agent skills crean leverage de equipo
Un workflow individual fuerte con IA es útil.
Un paquete de capacidad compartido es leverage.
Un ingeniero que se hace más rápido a sí mismo es útil. Un ingeniero que hace al equipo más rápido tiene leverage.
Las agent skills son una forma de convertir juicio privado en una contribución visible para el equipo.
Los ejemplos no son abstractos:
Una skill de code review puede elevar el nivel de review del equipo.
Una skill de release notes puede codificar el estilo de comunicación de producto.
Copiar un CLAUDE.md famoso es un inicio. Pero un equipo obtiene valor real cuando los ingenieros adaptan las instrucciones a su codebase real, sus riesgos de producto y sus estándares de review.
La diferencia está entre usar la plantilla de otra persona y codificar el juicio de tu equipo.
Esto es relevante para tu promoción porque convierte productividad personal en leverage organizacional.
Para ver cómo automaticé completamente un workflow que escribe más de 100 PRs al mes en Amazon, lee:
Qué predicen las agent skills para el open source
Creo que la mayoría de repos virales seguirán siendo archivos markdown.
Eso no significa que el código importe menos.
Pero el comportamiento de los agentes ahora está aguas arriba de más trabajo de software.
Si los agentes escriben más código, revisan más diffs, crean más planes y redactan más diseños, entonces las instrucciones que moldean esos agentes se convierten en parte del sistema de ingeniería.
Estos repositorios markdown no son documentación al lado de proyectos de código.
Son parte del sistema.
El blast radius de mal contexto alimentado a una IA puede ser ahora mayor que el blast radius de mal código.
Y la velocidad a la que ganan stars en GitHub significa que la gente puede usarlos más rápido y más fácilmente que un proyecto de código.
El inglés se está convirtiendo en una superficie de control para el trabajo de software.
Por eso merece la pena tomarse esta tendencia en serio.
Conclusión: las AI Agent Skills son la capa intermedia que faltaba
Esto no va de “mira estos repositorios markdown virales”.
Las AI agent skills son la capa intermedia que faltaba entre las instrucciones del repo y las herramientas ejecutables.
Si eres ingeniero de software, lo más barato y con mayor leverage que puedes hacer esta semana es estandarizar el software development lifecycle de tu equipo en skills para agentes de IA.
Empieza con un archivo markdown que haga al agente mejor en una tarea. Úsalo en trabajo real. Compártelo con tu equipo. Mejóralo cada vez que el agente cometa un error.
Sigue iterando.
Recapitulación del artículo
¿Qué son las AI agent skills?
Las AI agent skills son paquetes reutilizables de instrucciones que enseñan a un agente de IA cómo ejecutar un workflow específico. A menudo incluyen un archivo SKILL.md más scripts, referencias y ejemplos opcionales que el agente puede cargar cuando los necesita.
¿Cuál es la diferencia entre CLAUDE.md y las agent skills?
CLAUDE.md suele ser guía a nivel de repo para Claude Code. Las agent skills son playbooks de workflow más estrechos que se cargan solo cuando son relevantes, como code review, generación de tests, planificación de migraciones, release notes o resúmenes de incidentes.
¿Para qué sirve AGENTS.md?
AGENTS.md es un archivo de instrucciones agnóstico a la herramienta para agentes de coding. Da a los agentes un lugar predecible donde encontrar contexto del proyecto, instrucciones de setup, comandos de test y reglas del equipo.
¿Cuándo debería usar MCP en vez de una agent skill?
Usa MCP cuando el agente necesite interactuar con herramientas, APIs, bases de datos, archivos, calendarios, documentos o sistemas internos en vivo. Usa una agent skill cuando el agente necesite sobre todo juicio repetible, pasos de workflow, ejemplos y restricciones.
¿Cómo escribo un buen archivo SKILL.md?
Empieza con un workflow recurrente y escribe los pasos reales que sigues cuando lo haces bien. Añade una descripción clara de activación, inputs necesarios, proceso ordenado, formato de output y checks que el agente debe verificar antes de terminar.
Aquí tienes algunos ejemplos de repos populares con skills:
Si has llegado hasta aquí, te recomiendo leer: