Prepara tu codebase para los agentes

Así es como estructuro los archivos relacionados con agentes de IA en mis proyectos.

Puede que estés usando múltiples herramientas como Claude Code, OpenCode, Aider, AMP, Cursor, Droid y otras—a menudo comparando modelos y resultados en el mismo codebase.

Cada herramienta usa su propia convención para cargar reglas, habilidades y comandos, lo que lleva a duplicación si no se maneja con cuidado. El objetivo es mantener el contenido DRY (Don’t Repeat Yourself): una única fuente de verdad para las instrucciones de los agentes.

La Solución

Usa un único archivo AGENTS.md agnóstico de herramientas en la raíz del proyecto + un directorio agents/ para contenido modular.

Estructura recomendada:

agents/
├── rules/
│   ├── python.md
│   ├── nextjs.md
│   ├── security.md
│   └── ...
├── skills/
│   ├── testing.md
│   ├── infrastructure.md
│   ├── refactoring.md
│   └── ...
├── commands/
│   ├── fix-tests.md
│   ├── fix-linter.md
│   ├── add-feature.md
│   └── ...
└── scripts/
    ├── parse_test_coverage.py
    ├── run_linter_fix.sh
    └── ...

Configura cada herramienta para cargar o referenciar AGENTS.md (y opcionalmente archivos dentro de agents/).

AGENTS.md actúa como el índice central:

Instrucciones obligatorias al principio
Secciones para reglas, habilidades, comandos con referencias estilo @ donde sea soportado
Guía clara de carga (ej., “Siempre cargar rules/python.md para archivos Python”)

Configuración de Herramientas

Notas de Compatibilidad

Muchas herramientas soportan habilidades compatibles con Claude (formato .claude/skills/):

OpenCode
AMP
Cursor

Esto permite compartir archivos de habilidades entre ellas con cambios mínimos.

Claude Code

Docs: Skills • Changelog
Directorio: .claude/
Estado (2026): Los comandos slash y las habilidades están unificados en skills (v2.1+). Los archivos de comandos existentes siguen siendo compatibles.

Archivos recomendados:

.claude/skills/my-skill/SKILL.md

---
description: Brief purpose of this skill
user-invocable: true           # optional: show in / menu
---

# My Skill

Follow the relevant instructions in `AGENTS.md` (usually under /skills/ or /commands/).
Load matching content from agents/ when the task matches.

CLAUDE.md (todavía soportado, pero se prefiere AGENTS.md)

## Mandatory

- **ALWAYS** read and follow `AGENTS.md` at the project root before any action.
- For language-specific rules, load from `agents/rules/`.
- For task patterns, reference `agents/skills/` or `agents/commands/`.

OpenCode

Docs: Rules • Skills • Commands
Directorio: Raíz del proyecto (sin carpeta .opencode/ obligatoria)

Estructura de Archivos:

opencode.json (opcional, para globs adicionales / archivos remotos)

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENTS.md",
    "agents/rules/*.md"
  ]
}

OpenCode prefiere AGENTS.md nativamente (con fallback a CLAUDE.md). Usa opencode.json para incluir más archivos automáticamente.

AMP

Docs: Agent Skills • Custom Commands
Directorio: .agents/

Estructura de Archivos:

.agents/skills/my-skill/SKILL.md (compatible con Claude)

---
description: [your description]
---

# My Skill

Read and follow instructions in `AGENTS.md` — usually under agents/skills/.

.agents/commands/my-command-name.md

---
name: my-command-name
description: [brief description]
---

# My Command

Follow the matching section in `AGENTS.md`.

Aider

Docs: Config Reference
Archivo: .aider.conf.yml (o ~/.aider.conf.yml)

read:
  - AGENTS.md
  - agents/rules/python.md     # optional: include specific rules

Aider carga los archivos listados en el contexto automáticamente.

Droid

Docs: Skills • Custom Slash Commands
Directorio: .factory/

Estructura de Archivos:

.factory/skills/my-skill/SKILL.md

---
description: [your description]
---

# My Skill

Refer to `AGENTS.md` for detailed instructions (agents/skills/ section).

.factory/commands/my-command-name.md (estructura similar)

Cursor

Docs: Rules • Skills • Commands
Directorio: .cursor/

Estructura de Archivos:

.cursor/rules/general.mdc (o .md)

---
description: Core project instructions — always apply
alwaysApply: true
---

## Mandatory Instructions

- **ALWAYS** read `AGENTS.md` at project root.
- Load relevant rules from `agents/rules/` based on file type.
- Use `@agents/skills/...` syntax to reference skills when applicable.

.cursor/skills/my-skill/SKILL.md (compatible con Claude)
.cursor/commands/my-command-name.md

Cursor carga AGENTS.md automáticamente cuando está presente (sin configuración necesaria). Las reglas con alwaysApply: true aseguran un comportamiento consistente.

Antigravity

Docs: Rules & Workflows • Skills
Directorio: .agent/ (proyecto) o global ~/.gemini/

Estructura de Archivos:

.agent/rules/general.md

---
description: Always read this before anything
trigger: always_on
---

## Core Rules

- **ALWAYS** read `AGENTS.md`.
- Reference `agents/` subfolders as needed.

.agent/skills/my-skill/SKILL.md (formato estándar)

Consejos Rápidos

Mantén AGENTS.md < 400–500 líneas para evitar presión de contexto.
Usa encabezados Markdown y anclas para facilitar las referencias.
Para equipos: commitea agents/ + AGENTS.md en git; considera symlinks o submódulos para reglas compartidas.
Prueba: Pregunta a cada herramienta algo simple (“Explica las reglas del proyecto”) y verifica que se referencie AGENTS.md.
Seguridad: Nunca pongas secretos en estos archivos—usa variables de entorno o vaults seguros.

Esta configuración minimiza la duplicación mientras maximiza la compatibilidad entre herramientas (estado 2026).