Guía práctica / Desarrollo y agentes
AGENTS.md y Skills: cómo documentar un proyecto para agentes de IA
Un agente trabaja mejor cuando encuentra cómo construir el proyecto, qué comprobar y qué límites respetar. Esa información necesita un lugar claro y mantenimiento.
Un repositorio puede tener buen código y ser difícil de modificar porque sus instrucciones están repartidas entre conversaciones y hábitos del equipo. AGENTS.md ofrece un lugar reconocible para documentar el contexto que necesita un agente de programación.
Su utilidad se mide al realizar una tarea: encontrar el comando correcto, respetar una decisión del proyecto y comprobar el resultado.
Qué es AGENTS.md
Es un formato abierto de instrucciones en Markdown. El sitio oficial propone incluir información como preparación del entorno, pruebas y convenciones.
La forma de descubrir archivos y resolver instrucciones depende de la herramienta. Comprueba su documentación: no todos los agentes admiten los mismos nombres, ubicaciones o reglas de prioridad.
Qué escribir en el archivo principal
Empieza por lo que evita errores reales:
| Contenido | Ejemplo del tipo de información |
|---|---|
| Estructura | Dónde están fuentes y archivos generados |
| Preparación | Qué dependencias y comandos necesita el proyecto |
| Validación | Qué comprobaciones corresponden a cada cambio |
| Convenciones | Reglas que no se deducen claramente del código |
| Límites | Qué acciones requieren revisión o autorización |
Escribe comandos que hayas probado. Si un archivo se genera desde otro, explica cuál es la fuente editable. Esa indicación evita arreglos que desaparecen en la siguiente construcción.
No incluyas credenciales. Enlaza la documentación de acceso y deja los secretos en el mecanismo previsto para gestionarlos.
Qué conviene separar en una Skill
Las Skills agrupan instrucciones, recursos y, cuando procede, scripts para tareas específicas. La propuesta de Anthropic utiliza carga progresiva para no introducir todo el procedimiento en cada tarea.
Un flujo de publicación, una preparación de assets o una revisión de documentos puede tener suficiente detalle para separarse. La descripción debe permitir reconocer cuándo usarlo y el procedimiento debe indicar qué resultado comprobar.
No conviertas una preferencia general del equipo en diez Skills que repiten la misma regla.
Cómo comprobar si las instrucciones ayudan
Haz una tarea pequeña y representativa. Observa qué archivo se leyó, si los comandos funcionaron y si la validación detectó el problema esperado.
Después elimina instrucciones obsoletas y resuelve contradicciones. Versiona los cambios y revisa las aportaciones de terceros: un archivo de instrucciones no debe ampliar por sí mismo los permisos de ejecución.
Para definir el trabajo antes de ejecutarlo, consulta la guía sobre desarrollo guiado por especificaciones.
Una entrega que pueda continuar otro equipo
Documenta lo suficiente para que otra persona también entienda el proyecto. Los comandos, las fuentes editables y los criterios de aceptación sirven tanto a un agente como al siguiente desarrollador.
Si necesitas ordenar esa documentación, cuéntanos qué tareas resultan difíciles de repetir.
Fuentes
Revisadas el 20 de septiembre de 2026.
- Sitio oficial de AGENTS.md.
- Anthropic: Agent Skills.
Comprobado el 20 de septiembre de 2026