---

name: init-agents-md description: Create or refresh a minimal repository-level AGENTS.md for coding agents, keeping it short and repo-specific, and symlinking CLAUDE.md to it. Use when Codex needs to inspect a codebase, draft AGENTS.md, preserve useful details from an existing CLAUDE.md, stop before overwriting an existing AGENTS.md, or symlink CLAUDE.md to AGENTS.md.

Initialize AGENTS.md

Create a short, repo-specific AGENTS.md. Inspect the repository first, keep only the facts that help an agent work faster, treat AGENTS.md as the canonical context file, and ensure CLAUDE.md is a symlink to AGENTS.md.

Read references/agents-md-best-practices.md before drafting.

Workflow

1. Check the current files.

• If AGENTS.md already exists, stop. Tell the user and ask whether to continue and overwrite it.
• If CLAUDE.md exists and is a regular file (not a symlink), read it and use it as seed material for the new AGENTS.md.
• If CLAUDE.md does not exist or is already a symlink, plan to symlink it after creating AGENTS.md.

2. Explore the repository.

• Inspect only enough to explain the real project shape and workflows.
• Start with root files and directories, using the README as an initial guide to understand the project.
• Look for the commands people actually run, where the important code lives, whether tests exist, and any sharp edges an agent could miss.
• Prefer rg, rg --files, ls, and targeted file reads over broad dumps.

3. Draft AGENTS.md.

• Keep it minimal. Cut anything generic, obvious, or duplicated from existing docs.
• Start the file with # AGENTS.md.
• Place ## Project Instructions near the top. Leave it blank if there is nothing project-specific to add.
• Favor section names that match the real repo shape instead of generic placeholders.
• Focus on a few high-value facts:
  • what the repository is
  • where important code or content lives
  • the main workflows or commands
  • testing or validation expectations
  • any important gotchas
• Use short sections and terse bullets. If the file starts feeling long, compress it again.
• If the repository has useful topic-specific groupings, split them into small sections like Reference Docs, Development Commands, Architecture, Important Notes, or similarly precise names.

4. Symlink CLAUDE.md.

• If CLAUDE.md existed as a regular file, remove it after extracting any useful details into AGENTS.md.
• Create a relative symlink from CLAUDE.md pointing to AGENTS.md:

  ln -sf AGENTS.md CLAUDE.md
  

5. Sanity-check the result.

• Confirm AGENTS.md is the source of truth.
• Confirm CLAUDE.md is a relative symlink pointing to AGENTS.md.
• Confirm every command and path matches the repository.
• Confirm the file stays short and agent-specific.

Suggested Shape

Use only the sections that earn their keep. A good default for a richer repo is:

• ## Project Overview
• ## Project Instructions
• ## Reference Docs
• ## Development Commands
• ## Architecture
• ## Important Notes
• ## Validation

If the repository has clear domain-specific buckets, prefer those over the generic defaults. For example: Styling System, Path Aliases, State Management, or Admin Scripts.