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

Multiple sources need separate configurations

One configuration has one source. A root configuration does not recursively discover package configurations, even with scan --nested. For independently scoped instructions, put a separate .agentlink.yaml beside each package’s real AGENTS.md, declaring only that package’s aliases. Run agentlink sync --dry-run and then agentlink sync from each configured package directory. Do not list package aliases under the root config unless they should read the root source.

Alternatively, leave the repository unconfigured and use nested scanning for the documented alias set. These are distinct workflows; explicit root configuration always wins over automatic discovery.

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