Make your codebase agent ready

This is how I structure files related to AI coding agents in my projects.

You might be using multiple tools like Claude Code, OpenCode, Aider, AMP, Cursor, Droid, and others—often comparing models and results on the same codebase.

Each tool uses its own convention for loading rules, skills, and commands, leading to duplication if not handled carefully. The goal is to keep content DRY (Don’t Repeat Yourself): one source of truth for agent instructions.

The Solution

Use a single, tool-agnostic AGENTS.md file at the project root + an agents/ directory for modular content.

Recommended structure:

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
    └── ...

Point every tool’s configuration to load or reference AGENTS.md (and optionally files inside agents/).

AGENTS.md acts as the central index:

• Mandatory instructions at the top
• Sections for rules, skills, commands with @-style references where supported
• Clear loading guidance (e.g., “Always load rules/python.md for Python files”)

Tool Configuration

Compatibility Notes

Many tools support Claude-compatible skills (.claude/skills/ format):

• OpenCode
• AMP
• Cursor

This allows sharing skill files across them with minimal changes.

Claude Code

• Docs: Skills • Changelog
• Directory: .claude/
• Status (2026): Slash commands and skills are merged into unified skills (v2.1+). Existing command files remain supported for compatibility.

Recommended files:

• .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 (still supported, but prefer 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
• Directory: Project root (no mandatory .opencode/ folder)

File Structure:

• opencode.json (optional, for extra globs / remote files)

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

OpenCode prefers AGENTS.md natively (with fallback to CLAUDE.md). Use opencode.json to include more files automatically.

AMP

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

File Structure:

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

---
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
• File: .aider.conf.yml (or ~/.aider.conf.yml)

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

Aider loads listed files into context automatically.

Droid

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

File Structure:

• .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 (similar structure)

Cursor

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

File Structure:

• .cursor/rules/general.mdc (or .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 (Claude-compatible)
• .cursor/commands/my-command-name.md

Cursor auto-loads AGENTS.md when present (no config needed). Rules with alwaysApply: true ensure consistent behavior.

Antigravity

• Docs: Rules & Workflows • Skills
• Directory: .agent/ (project) or global ~/.gemini/

File Structure:

• .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 (standard format)

Quick Tips

• Keep AGENTS.md < 400–500 lines to avoid context pressure.
• Use Markdown headings and anchors for easy referencing.
• For teams: commit agents/ + AGENTS.md to git; consider symlinks or submodules for shared rules.
• Test: Ask each tool a simple question (“Explain project rules”) and verify AGENTS.md is referenced.
• Security: Never put secrets in these files—use env vars or secure vaults.

This setup minimizes duplication while maximizing compatibility across tools (2026 status).