Table of Contents
- Abstract
- Motivation
- Benefits
- Alternatives Considered
- Backwards Compatibility
- Open Questions
Abstract
This proposal introduces a YAML front matter header to AGENTS.md files with lifecycle and builtin commands support.
- lifecycle:
bootstrap, post-chat
bootstrap: runs once when the session starts, before the first API callpost-chat: fires after the client completes a full task cycle (all API calls and tool calls), when waiting for the next user input
- builtin commands:
read, read-as-system, run
# AGENTS.md
---
bootstrap:
- read: .claude/skills/code-guide.md
- read-as-system: docs/team-rules.md
post-chat:
- run: npx eslint --fix ./src/**/*
- run: ruff format ./src-python/**/*
---
## Python code guide
{{@read .claude/skills/python-code-guide.md}}
-
read command sequentially reads the specified files and prepends their contents to the first user message.
-
read-as-system command reads the specified file and injects its contents as system context, preferable for project rules and guidelines that should not appear directly in the user message.
-
If a file specified in read or read-as-system cannot be found or accessed, the client must emit a warning (e.g., [AGENTS.md] read failed: <path>) and continue processing remaining commands.
-
All relative paths in read, read-as-system, and run are resolved from the workspace/project root (the directory containing AGENTS.md).
-
{{@read <path>}} is an inline directive processed by the client before the message is sent to the model, replacing the directive with the file contents inline. Implementations should follow a consistent syntax to avoid fragmentation.
-
run command executes the specified shell command after each post-chat event, run from the workspace/project root. This is helpful when the project is complex and the AI cannot reliably run build or lint workflows.
Motivation
read command
This request happens when I want to share the reuseable parts with my teammates (Mainly as company rules), but AGENTS.md is too personal or project specific.
SKILLs are kind of solving the problem but it happens AFTER THE FIRST AI MODEL CALL. As so many AI providers have support "Cache Hit" or "Prompt Caching" technology, the bootstrap read command can load the contents before the first API call to improve efficiency and reduce token usage.
read & @read command can make AGENTS.md more flexible.
post-chat run command
When the project is complex and the AI cannot reliably run build or lint workflows, it's better to let the AI focus on code changes and leave tooling to the human or CI/CD system. For example: code lint, binary build, dev server start, debug environment setup.
The post-chat lifecycle event fires after the client completes a full task cycle — all API calls and tool calls are done — and the client is waiting for the next user input. This ensures run commands only execute at natural breakpoints in the conversation, not between intermediate tool calls.
Benefits
- Improved efficiency: By allowing the agent to read files before the first API call, we can reduce token usage and improve response times.
- Better collaboration: Sharing reusable parts with teammates becomes easier, fostering better collaboration and consistency across projects.
- Enhanced functionality: The ability to run commands after each
post-chat event can help maintain code quality and streamline workflows, especially in complex projects.
Alternatives Considered
- System prompt / config injection: Some clients support a global system prompt field. This does not support per-project file reuse or composability across team members.
- IDE context references (e.g.,
#file: in VS Code Copilot): Requires manual user action each session; not automatic or portable.
- Tool calls during conversation: Files can be read via tool calls, but this happens after the first API call, forfeiting prompt caching benefits.
- Inline copy-paste into AGENTS.md: Works but creates duplication, making shared rules hard to maintain across projects.
Backwards Compatibility
- AGENTS.md files without YAML front matter are unaffected; this extension is purely additive.
- Implementations that do not recognize the front matter block should silently ignore it and continue parsing the Markdown body.
- Unknown keys within the front matter must be ignored to allow forward compatibility as the spec evolves.
Open Questions
- Should
read-as-system be a separate command or a mode/option on read (e.g., read: { path: ..., as: system })?
- Should
{{@read ...}} syntax be formally standardized in the spec, or remain an optional client-level feature?
- Should
post-chat run commands require explicit user confirmation in interactive clients?
- Should there be a maximum file size threshold for
read/read-as-system before the client emits a warning?
draft project: https://github.com/aolyang/AGENTS.md-proposal-lifecycle-commands
Table of Contents
Abstract
This proposal introduces a YAML front matter header to
AGENTS.mdfiles with lifecycle and builtin commands support.bootstrap,post-chatbootstrap: runs once when the session starts, before the first API callpost-chat: fires after the client completes a full task cycle (all API calls and tool calls), when waiting for the next user inputread,read-as-system,runreadcommand sequentially reads the specified files and prepends their contents to the first user message.read-as-systemcommand reads the specified file and injects its contents as system context, preferable for project rules and guidelines that should not appear directly in the user message.If a file specified in
readorread-as-systemcannot be found or accessed, the client must emit a warning (e.g.,[AGENTS.md] read failed: <path>) and continue processing remaining commands.All relative paths in
read,read-as-system, andrunare resolved from the workspace/project root (the directory containingAGENTS.md).{{@read <path>}}is an inline directive processed by the client before the message is sent to the model, replacing the directive with the file contents inline. Implementations should follow a consistent syntax to avoid fragmentation.runcommand executes the specified shell command after eachpost-chatevent, run from the workspace/project root. This is helpful when the project is complex and the AI cannot reliably run build or lint workflows.Motivation
read command
This request happens when I want to share the reuseable parts with my teammates (Mainly as company rules), but AGENTS.md is too personal or project specific.
SKILLs are kind of solving the problem but it happens AFTER THE FIRST AI MODEL CALL. As so many AI providers have support "Cache Hit" or "Prompt Caching" technology, the bootstrap read command can load the contents before the first API call to improve efficiency and reduce token usage.
read&@readcommand can make AGENTS.md more flexible.post-chat run command
When the project is complex and the AI cannot reliably run build or lint workflows, it's better to let the AI focus on code changes and leave tooling to the human or CI/CD system. For example: code lint, binary build, dev server start, debug environment setup.
The
post-chatlifecycle event fires after the client completes a full task cycle — all API calls and tool calls are done — and the client is waiting for the next user input. This ensuresruncommands only execute at natural breakpoints in the conversation, not between intermediate tool calls.Benefits
post-chatevent can help maintain code quality and streamline workflows, especially in complex projects.Alternatives Considered
#file:in VS Code Copilot): Requires manual user action each session; not automatic or portable.Backwards Compatibility
Open Questions
read-as-systembe a separate command or a mode/option onread(e.g.,read: { path: ..., as: system })?{{@read ...}}syntax be formally standardized in the spec, or remain an optional client-level feature?post-chatruncommands require explicit user confirmation in interactive clients?read/read-as-systembefore the client emits a warning?