Agentlink guide

AI instruction files in monorepos

Start with one root policy, add nested files only for real local differences, and never assume that AGENTS.md, CLAUDE.md, and GEMINI.md share a precedence model.

By Sam RogersPublished September 1, 2026Agentlink v0.5.0

Separate content scope from file synchronization

Two questions are easy to conflate. First, which instructions should apply to work in a package? Second, which tool-specific paths should contain identical content? The repository’s instruction hierarchy answers the first question. Agentlink’s symlinks answer only the second.

A durable layout puts shared conventions at the repository root. Add a nested AGENTS.md when a package has genuinely different commands, architecture, or review requirements. Keep the nested file short and local rather than copying the root wholesale.

Prefer explicit project configuration

When a repository contains .agentlink.yaml, that configuration is authoritative. Agentlink manages only its declared source and links. This makes the intended topology reviewable and prevents a portfolio-wide scan from guessing how a complex repository should behave.

# .agentlink.yaml at repository root
source: AGENTS.md
links:
  - CLAUDE.md
  - GEMINI.md
  - .github/copilot-instructions.md

Keep a tool-specific file out of links when it is a real wrapper or has independent content. For example, a real CLAUDE.md can import @AGENTS.md and add Claude-only guidance.

Use nested scan intentionally

For repositories without explicit configuration, agentlink scan manages root aliases by default. The optional --nested flag also looks for nested AGENTS.md files, but creates adjacent aliases only for integrations with documented nested discovery. In v0.5.0, that gate covers Claude Code and Gemini CLI. Unknown tools remain root-only.

# Preview every repository first
agentlink scan ~/Git --nested --dry-run

# Apply after reviewing the paths and scopes
agentlink scan ~/Git --nested

Review checklist

  1. Write down the root instructions that truly apply across the repository.
  2. Add nested instructions only at package boundaries with different work.
  3. Choose which tool files must be identical and which need real wrappers.
  4. Run a dry scan and inspect paths, relative targets, and preserved files.
  5. Test each tool in both root and nested directories; tool behavior remains the final authority.
  6. Commit the topology so reviewers can see every source, wrapper, and symlink.

What Agentlink deliberately does not infer

Agentlink does not merge instructions, generate nested content, reconcile conflicting policies, or impose one tool’s precedence rules on another. It skips nested repositories, worktrees, dependency directories, build outputs, handoff folders, and other bounded paths during scanning. Existing real aliases are preserved unless replacement is explicitly requested.