Agents Md

name: agents-md description: > Skill especializada en crear archivos AGENTS.md (y CLAUDE.md / GEMINI.md) para proporcionar instrucciones de flujo de trabajo al Copilot coding agent y otros agentes de IA. Úsala cuando el usuario quiera definir cómo debe comportarse el agente al crear PRs, ejecutar CI, explorar el código, o manejar situaciones específicas del flujo de desarrollo. Activa esta skill ante frases como "AGENTS.md", "instrucciones para el agente", "coding agent", "instrucciones de flujo", "instrucciones para PR", "que el agente sepa cómo trabajar", "CLAUDE.md", "GEMINI.md", o cualquier petición de personalizar el comportamiento del coding agent de Copilot, Claude o Gemini. Para instrucciones globales del repositorio usa la skill github-copilot-instructions. Para instrucciones por tipo de archivo usa la skill path-specific-instructions.

AGENTS.md — Instrucciones para agentes de IA

Los archivos AGENTS.md (y sus equivalentes CLAUDE.md / GEMINI.md) contienen instrucciones de flujo de trabajo dirigidas específicamente al coding agent. A diferencia de copilot-instructions.md, que está enfocado en estándares de código, AGENTS.md le indica al agente cómo debe actuar mientras trabaja: cómo explorar el repo, cómo ejecutar CI, cómo crear pull requests, qué validaciones hacer antes de finalizar.

Fuente oficial: docs.github.com — Creating custom instructions (Agent instructions) Especificación AGENTS.md: github.com/openai/agents.md

Diferencia con copilot-instructions.md

Usa AGENTS.md para instrucciones de comportamiento del agente que no tienen sentido en una conversación de chat normal. Si la información es relevante tanto para el chat como para el agente, ponla en copilot-instructions.md.

Archivos soportados

Puedes tener los tres archivos a la vez si usas múltiples agentes. Para Copilot, usa AGENTS.md.

Placement: precedencia por proximidad

Los archivos AGENTS.md se pueden colocar en cualquier directorio del repositorio. El agente usa el archivo más cercano al contexto en el que está trabajando:

repo-root/
├── AGENTS.md                  ← instrucciones globales (toda la raíz)
├── src/
│   ├── AGENTS.md              ← sobrescribe/complementa para src/
│   └── backend/
│       └── AGENTS.md          ← más específico para src/backend/
└── tests/
    └── AGENTS.md              ← instrucciones específicas para tests/

El archivo más cercano en el árbol de directorios tiene precedencia sobre los de nivel superior. Las instrucciones más genéricas van en la raíz; las más específicas, en subcarpetas.

VS Code: El soporte de AGENTS.md fuera de la raíz del workspace está desactivado por defecto. Para activarlo, consulta la documentación de VS Code sobre custom instructions.

Soporte por entorno

Qué incluir en un AGENTS.md

Un buen AGENTS.md contiene instrucciones sobre el proceso de trabajo, no sobre estándares de código. Piensa en él como el "manual de incorporación" del agente:

1. Cómo explorar el repositorio

Indica al agente qué archivos leer primero, dónde está la configuración, cómo está organizado el código para que no pierda tiempo buscando.

2. Cómo ejecutar builds y tests

Documenta el orden exacto de comandos, las versiones de herramientas requeridas, los errores conocidos y sus remedios. El agente ejecutará estos comandos — necesita instrucciones precisas y verificadas.

3. Cómo crear Pull Requests

Indica el formato del título y descripción del PR, a quién asignar para revisión, qué checks de CI deben pasar antes de solicitar review, si hay template de PR a usar.

4. Validaciones antes de finalizar

Qué pasos debe completar el agente antes de considerar su trabajo terminado: lint, tests, build, revisión de seguridad, etc.

5. Información de arquitectura crítica

Dependencias no obvias entre módulos, ficheros que deben sincronizarse, patrones de error que el agente debe respetar.

Plantilla de AGENTS.md

# Agent Instructions

## Repository Overview

[Descripción breve de qué hace este repositorio y su arquitectura principal.]

## Getting Started

Before making changes, read these files to understand the codebase:
- `README.md` — project overview and setup
- `[ruta a fichero de configuración principal]` — application config
- `[ruta a fichero de arquitectura o ADR]` — architectural decisions

## Build & Validation

Always run these commands in this exact order before submitting:

1. Install dependencies: `[comando]`
2. Build: `[comando]`
3. Run tests: `[comando]`
4. Lint: `[comando]`

All commands must pass without errors. If a test fails, fix the issue — do not skip.

## Creating Pull Requests

- Title format: `[type]: [short description]` (types: feat, fix, docs, refactor, test)
- Description must include: what changed, why it changed, and how to test it.
- Assign `[team or user]` as reviewer.
- The `[CI workflow name]` GitHub Actions workflow must pass before requesting review.

## Important Architecture Notes

- [Dependencia crítica entre módulos A y B]
- [Ficheros que deben mantenerse sincronizados]
- [Patrón de errores que debe respetarse]
- [Cualquier workaround conocido a un problema del entorno]

## Constraints

- Do not modify `[ficheros protegidos]` without explicit user instruction.
- Do not upgrade dependencies unless specifically asked.
- Always trust these instructions; only search if the information here is incomplete or outdated.

Ejemplo completo — API Node.js

# Agent Instructions

## Repository Overview

REST API for task management built with Node.js 20, Express 4, TypeScript, and PostgreSQL.
The Prisma ORM handles all database access. Tests run with Jest + Supertest.

## Getting Started

Read these files before making changes:
- `README.md` for project overview
- `prisma/schema.prisma` for the database schema
- `src/middleware/` to understand authentication and validation layers

## Build & Validation

Run in this order every time:

1. `npm install` — install dependencies
2. `npm run build` — compile TypeScript (must succeed with 0 errors)
3. `npm test` — all tests must pass
4. `npm run lint` — no lint errors allowed

If `npm run build` fails due to a missing type, check if there is a `@types/` package
to install. Do not use `// @ts-ignore` to bypass errors.

## Creating Pull Requests

- Title format: `feat:`, `fix:`, `refactor:`, `test:`, or `docs:` prefix required.
- PR description must include a "Testing" section explaining how to verify the change.
- The "CI / build-and-test" GitHub Actions check must be green before requesting review.
- Assign the `backend-team` group as reviewer.

## Architecture Notes

- Route handlers must only call service functions — never access the database directly.
- All database queries go through `src/repositories/`. Never import Prisma client
  outside of repository files.
- Environment variables are validated on startup in `src/config/env.ts`. Add new
  variables there before using them elsewhere.
- The `src/middleware/auth.ts` middleware must be applied to all non-public routes.

## Constraints

- Do not modify `prisma/migrations/` manually — use `npx prisma migrate dev` instead.
- Do not upgrade `prisma` or `@prisma/client` unless asked — there is a known
  breaking change in version 6.x under investigation.

Ejemplo completo — Monorepo con subdirectorios

Cuando tienes un monorepo, puedes tener instrucciones generales en la raíz y específicas en cada paquete:

/AGENTS.md (raíz):

# Agent Instructions — Monorepo Root

This monorepo contains three packages: `packages/api`, `packages/web`, and `packages/shared`.

## Global Commands

- Install all dependencies: `npm install` (run from root — uses workspaces)
- Build all packages: `npm run build --workspaces`
- Run all tests: `npm test --workspaces`

## Making Changes

Always determine which package(s) are affected before making changes. Read the
relevant package-level AGENTS.md for specific instructions.

/packages/api/AGENTS.md (específico del paquete api):

# Agent Instructions — API Package

## Build & Test

- Build: `npm run build` (from packages/api/)
- Test: `npm test` (from packages/api/)

## Database Changes

Always run `npx prisma generate` after modifying `prisma/schema.prisma`.
Run `npx prisma migrate dev --name [description]` to create a new migration.
Never edit migration files manually.

Buenas prácticas

Sí ✅

• Documentar comandos verificados con el orden exacto y precondiciones
• Mencionar errores conocidos y sus remedios
• Indicar archivos críticos que el agente debe leer primero
• Especificar el formato de PR y qué checks deben pasar
• Usar "Always", "Never", "Must" para instrucciones obligatorias
• Indicar explícitamente al agente que confíe en estas instrucciones y solo busque si están incompletas

No ❌

• Duplicar reglas de código que ya están en copilot-instructions.md
• Instrucciones vagas: Be careful with the database — mejor: Never write raw SQL; always use Prisma client methods
• Comandos que no has verificado que funcionen — el agente los ejecutará tal cual
• Dejar AGENTS.md vacío o sin actualizar cuando el proceso de build cambia

Referencia oficial

• Adding repository custom instructions — Agent instructions
• Support for different types of custom instructions
• openai/agents.md — AGENTS.md specification
• About agentic memory for GitHub Copilot

Source: Zoimback/copilot-dev-core — distributed by TomeVault.