AGENTS.md Generation¶

AGENTS.md is the primary file AI agents read when starting a session. It contains workspace instructions, operational guidelines, documentation listings, and your project-specific content. This workspace auto-generates it from a Jinja2 template so that it stays in sync with your configuration and agent docs.

Why auto-generate?¶

A manually maintained AGENTS.md falls out of sync as you add agent docs, enable/disable features, or change workspace structure. Auto-generation ensures the file always reflects the current state:

• Agent docs listing - Automatically updated when you add, remove, or edit docs in agent-docs/
• Feature sections - Skills and commands sections appear only when those features are enabled and have content
• Consistent structure - Workspace-level instructions (submodule workflow, pre-commit, temporary files) are maintained in the template, separate from your project-specific content

Writing your instructions¶

Edit AGENTS.project.md at the repo root. This is where you write your own instructions and context for AI agents - the same kind of content you’d normally put in a regular AGENTS.md:

## Project Overview
Brief description of what this project does.

## Key Concepts
- **Term 1** - Definition
- **Term 2** - Definition

## Repository Structure
- `repositories/backend/` - Go API server
- `repositories/frontend/` - React web app

This content is injected into the generated AGENTS.md under a “Project-Specific Context” heading. The file ships with <placeholder> tags - remove them when adding your content (the placeholder content is ignored during generation).

Instruction priority with submodule repositories¶

Each repository under repositories/ may have its own AGENTS.md (or CLAUDE.md) with repo-specific instructions. The generated workspace AGENTS.md instructs agents to:

1. Read and follow submodule instructions - Agents read the submodule’s AGENTS.md and README.md before making changes, and follow repo-specific conventions, commands, and boundaries
2. Workspace takes priority on conflicts - If a submodule instruction conflicts with the workspace-level AGENTS.md, the workspace instruction wins. This covers workspace-wide concerns like submodule workflow, package management, pre-commit, and documentation systems

This means submodule AGENTS.md files don’t need to repeat workspace-level instructions, and teams can maintain repo-specific conventions without worrying about conflicts.

Regeneration¶

AGENTS.md is regenerated by running the alignment script:

uv run .ai-workspace/scripts/align-workspace.py

Pre-commit hooks verify that AGENTS.md is up to date on every commit, but do not regenerate it automatically. If the pre-commit check fails, run the alignment script above and stage the updated file.

Modifying the template (advanced)¶

The Jinja2 template at .ai-workspace/templates/AGENTS.md.j2 defines the structure and workspace-level instructions of the generated AGENTS.md. Most users won’t need to touch this file - AGENTS.project.md covers project-specific customization. But if you need to change the workspace-level instructions themselves (reword guidelines, add new sections, remove parts that don’t apply), you can edit the template directly.

Available template variables¶

The template receives these variables during rendering:

features.agent_docs.enabled

Type: bool - Whether the agent docs feature is enabled

features.agent_docs.docs

Type: list - Agent doc entries (each has display_name, description, when_to_read, doc_path)

features.skills.enabled

Type: bool - Whether the skills feature is enabled

features.skills.count

Type: int - Number of validated skills

features.commands.enabled

Type: bool - Whether the commands feature is enabled

features.commands.count

Type: int - Number of validated commands

project_content

Type: str or None - Content of AGENTS.project.md (None if missing or placeholder)