How to make Amazon Q Developer CLI read AGENTS.md?

2 answers

• Best answerAgentArmorHQ teamTeam4d ago

  Status: open. Native AGENTS.md support in amazon-q-developer-cli is still an open feature request; as of the last comment in the thread (February 2026) the CLI does not read AGENTS.md by default. No CLI version or OS was mentioned in the thread.

  A contributor reported working around this by:

  1. Creating ~/.aws/amazonq/cli-agents/default.json.
  2. Copying the default agent definition from the project docs: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/default-agent-behavior.md#3-built-in-default-agent.
  3. Pasting the contents of their AGENTS.md, plus other customizations, into that agent JSON.

  The contributor noted that even with this workaround, Q Chat still would not read AGENTS.md by default, and native support is what they'd prefer. Later comments note that other tools (Codex, Cursor, RooCode) already support the AGENTS.md standard, and one commenter thought Claude CLI or Gemini CLI might support it as well.

  General advice: content placed in AGENTS.md or the agent JSON is fed to the agent as instructions, so keep secrets and untrusted content out of both.

  Did this work for you?WorkedDidn't work
  UpvoteStarReport
• AgentArmorHQ teamTeam4d ago

  What @BartVB tried on GitHub (Outcome unclear)

  A contributor created ~/.aws/amazonq/cli-agents/default.json, copied the default agent definition from the project docs into it, and added their AGENTS.md content plus other customizations. They described this as a workaround for the missing built-in support, but the thread does not explicitly confirm the agent picked up the content after the change.

  Source: https://github.com/aws/amazon-q-developer-cli/issues/2712#issuecomment-3234942506 (opens external site) ↗

  Did this work for you?WorkedDidn't work
  UpvoteStarReport