AGENTS.md — Cross-Tool AI Agent Entry Point

By Amr

How the repository-root AGENTS.md file provides a single source of truth for AI coding agents (Copilot, Codex, Cursor, Aider, Jules, Continue, Claude Code, and others).

Estimated reading time: 2 minutes

• Share on Reddit
• Share on LinkedIn
• Share on Twitter

• ---

• Page Improvements

• Improve Page Polish content, structure, and presentation of this page
• Expand Page Add depth, examples, and missing sections to this page
• Update Page Refresh outdated content, versions, links, and screenshots
• Fix Page Issue Report a typo, broken link, layout glitch, or content bug
• SEO Optimize Improve discoverability, metadata, and structured data
• Accessibility Audit Audit this page for WCAG 2.1 AA compliance

• ---

• Site Improvements

• UI/UX Improvement Propose a design or UX refinement for the theme
• New Feature Propose a new site-wide feature or capability
• Component Enhancement Improve a Jekyll layout, include, or shared component
• Performance Optimization Improve load time, Core Web Vitals, and asset delivery

Edit on GitHub

Table of Contents

AGENTS.md — Cross-Tool AI Agent Entry Point

AGENTS.md in the repository root is a single, short entry-point file for AI coding agents. It follows the emerging agents.md convention and is read by GitHub Copilot, OpenAI Codex, Cursor, Aider, Jules, Continue, Claude Code, and any other agent that respects the convention.

Why AGENTS.md?

Different AI tools each have their own config file format:

Tool	Its own file
GitHub Copilot	.github/copilot-instructions.md
Cursor	.cursor/ rules
Aider	.aider.conf.yml
Continue	.continuerc.json

Rather than maintaining separate instruction files with duplicated content, AGENTS.md acts as a cross-tool entry point that links to the canonical, detailed guidance already in .github/. This prevents drift and keeps a single source of truth.

File Location

AGENTS.md   ← repository root

GitHub Copilot also reads it as supplementary context. Other tools that support the AGENTS.md convention will discover it automatically.

What It Contains

AGENTS.md is intentionally short. It covers:

1. Project snapshot — what the repo is, primary languages, version source of truth
2. Guidance map — a table showing which file to read for which task
3. Essential commands — the handful of commands every agent needs
4. Operating rules — seven concise rules (minimal changes, validate before done, etc.)
5. Extension guide — how to add new agent capabilities

Layered Guidance Model

AGENTS.md          ← Cross-tool entry point (always read first)
    │
    ├── .github/copilot-instructions.md  ← Full architecture & conventions
    │
    └── .github/instructions/*.instructions.md  ← File-scoped rules
            layouts.instructions.md       → _layouts/**
            includes.instructions.md      → _includes/**
            scripts.instructions.md       → scripts/**
            sass.instructions.md          → _sass/**, assets/css/**
            obsidian.instructions.md      → _plugins/obsidian_links.rb, …
            testing.instructions.md       → test/**
            documentation.instructions.md → docs/**, pages/_docs/**
            version-control.instructions.md → CHANGELOG.md, version.*, …
            features.instructions.md      → features/features.yml, _data/features.yml
            install.instructions.md       → install.sh, scripts/lib/install/**, …

Operating Rules for Agents

All agents working in this repository must follow these rules (quoted from AGENTS.md):

1. Make minimal, surgical changes. Match the existing style. Do not refactor unrelated code.
2. Respect the layered guidance. File-scoped instructions override generic best practices.
3. Validate before declaring done. Run relevant tests; for theme changes run the Docker Jekyll build.
4. Update CHANGELOG.md for any user-visible change.
5. Bump the version only via ./scripts/bin/release — never in unrelated PRs.
6. Do not commit secrets. Use environment variables.
7. Prefer existing libraries and patterns.

Adding a New Tool

To onboard a new AI tool without duplicating content:

1. Create the tool’s own config file (e.g. CLAUDE.md)
2. In that file, write: “See AGENTS.md.”
3. That’s it — the layered guidance already covers everything

Related

• Scripts Overview
• CI/CD Pipeline

See also

• [[Development]]
• [[Documentation]]