DLN.

Make your codebase agent ready

Make your codebase agent ready
English English Español Español Français Français

You’re drowning in AI coding tools right now. Claude Code, Cursor, Aider, AMP, Droid—maybe you’re running all of them at once. I’ve been exactly where you are. And here’s the thing: every single one of these tools wants its own special way of loading rules, skills, and commands.

The result? Duplication everywhere. The same instructions scattered across five different config folders. Trust me, it’s a nightmare.

Let me show you how I fixed this.

The Problem

Picture this, my friend. You write a coding guideline once. Then you copy it to .claude/, to .cursor/, to .aider.conf.yml. A week later you update the original. Now your configs are completely out of sync.

This isn’t sustainable. And you know it.

You need one source of truth for all your agent instructions. One place. Not five.

The Solution

Here’s what actually works: a single AGENTS.md file at your project root, plus an agents/ directory for modular content.

Think of AGENTS.md as the index. The table of contents. The boss. Every tool points to it.

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

Your AGENTS.md becomes the central hub:

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

Now let’s configure each tool to point here. I’ll walk you through every single one.

Tool Configuration

Good News First

Here’s something that’ll make your life easier. Many tools now support Claude-compatible skills (the .claude/skills/ format):

  • OpenCode
  • AMP
  • Cursor

Why does this matter? Because you can share skill files across them with minimal changes. One format, multiple tools. Write once, use everywhere.

Claude Code

Docs: Skills • Changelog

Directory: .claude/

Status (2026): Slash commands and skills are now unified (v2.1+). Your existing command files still work.

Create .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.

And your CLAUDE.md (or better, just use AGENTS.md directly):

## 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 folder needed)

OpenCode already prefers AGENTS.md natively. It falls back to CLAUDE.md if needed. This is the easiest setup you’ll see today.

Want to include more files automatically? Create opencode.json:

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

Done. That’s it.

AMP

Docs: Agent Skills • Custom Commands

Directory: .agents/

Create .agents/skills/my-skill/SKILL.md (Claude-compatible format):

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

# My Skill

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

For commands, use .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)

This is the simplest setup of all. I mean it:

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

Aider loads these files into context automatically. Boom. You’re done.

Droid

Docs: Skills • Custom Slash Commands

Directory: .factory/

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

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

# My Skill

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

Commands work the same way in .factory/commands/.

Cursor

Docs: Rules • Skills • Commands

Directory: .cursor/

Here’s the trick with Cursor: it auto-loads AGENTS.md when present. No config needed. Zero effort.

But if you want to make absolutely sure your rules always apply, create .cursor/rules/general.mdc:

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

Skills and commands follow the Claude-compatible format.

Antigravity

Docs: Rules & Workflows • Skills

Directory: .agent/ (project) or global ~/.gemini/

Create .agent/rules/general.md:

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

## Core Rules

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

Skills use the standard format in .agent/skills/my-skill/SKILL.md.

Tips That Actually Matter

Let me share what I’ve learned the hard way.

Keep AGENTS.md under 400-500 lines. Context pressure is real. Your AI can only hold so much in its working memory before things start getting fuzzy.

Use Markdown headings and anchors. Why? Because it makes referencing specific sections trivially easy. Your future self will thank you.

For teams: commit agents/ and AGENTS.md to git. Consider symlinks or submodules for shared rules across projects. This is how you scale.

Test your setup. Ask each tool “Explain the project rules” and verify it references AGENTS.md. If it doesn’t, your config is broken. Fix it now.

And please—never put secrets in these files. I shouldn’t have to say this, but I’ve seen it happen. Use environment variables or secure vaults. Always.

The Payoff

One place for all your agent instructions. Update once, every tool picks it up.

No more duplication. No more drift. No more chaos.

This is it. This is how it should work.