Create Agents Md

---
name: create-agents-md
description: Generate or rewrite an AGENTS.md file — a high-signal-density operational checklist for AI coding agents.
argument-hint: Generates project-specific AGENTS.md with constraints, conventions, and gotchas that prevent costly agent mistakes.
disable-model-invocation: true
when-to-use: "user wants to generate an AGENTS.md operational checklist -- '/create-agents-md', 'create agents.md', 'generate agents file', 'write AGENTS.md'"
---

# Gather Context

```
!`git remote -v 2>/dev/null || echo "NO_GIT"`
```

```
!`git log --oneline -5 2>/dev/null || echo "NO_COMMITS"`
```

---

# Instructions

**Before starting**, use tools to gather project context silently (do not show results to the user):
1. Glob `**/*` (max depth 2, exclude `.git/`, `node_modules/`, `.build/`, `vendor/`, `target/`) -- project file structure
2. Read `AGENTS.md`, `README.md`, `CLAUDE.md` -- existing docs (skip if missing)
3. Glob `**/*ci*.yml`, `**/*ci*.yaml`, `**/Jenkinsfile`, `**/.travis.yml`, `**/Makefile` (max depth 3) -- CI config
4. Glob for linter configs in root: `.eslintrc*`, `.prettierrc*`, `biome.json`, `rustfmt.toml`, `.swiftlint.yml`, `.rubocop.yml`, `.editorconfig`, `.clang-format`

Treat missing files as empty. Proceed regardless.

You are an AGENTS.md architect. Your goal is **maximum signal density** — every line must be project-specific, non-obvious, and action-guiding. No generic advice. No README duplication. No rules already enforced by tooling.

```
┌───────────┐     ┌───────────┐     ┌───────────┐     ┌───────────┐
│ 1. GATHER │ ──► │ 2. ANALYZE│ ──► │ 3. GENERATE│ ──►│ 4. SAVE   │
│ Shell data │     │ Detect    │     │ Write      │     │ Write file│
│ from above │     │ project   │     │ AGENTS.md  │     │ Verify &  │
│            │     │ type &    │     │ sections   │     │ report    │
│            │     │ read cfgs │     │            │     │           │
└───────────┘     └───────────┘     └───────────┘     └───────────┘
```

Use the `find` output to understand project type, language, build system, and structure — regardless of whether it's Node, Rust, Go, Python, Ruby, Swift, Java, C++, Elixir, or anything else. Do not rely on hardcoded manifest names.

Silently determine which case applies:

- **Branch A — No project detected:** If the directory has no recognizable source files, manifests, or config → tell the user this doesn't appear to be a project directory. **Stop here.**
- **Branch B — Existing AGENTS.md:** If `cat AGENTS.md` returned content → enter **rewrite mode**. Aggressively trim generic advice, deduplicate against README.md and CLAUDE.md, tighten language to imperative form. Then proceed to AGENTS.md Generation using the existing content as a starting point.
- **Branch C — No AGENTS.md:** Proceed to AGENTS.md Generation and create from scratch.

---

# AGENTS.md Generation

Analyze all gathered context -- project structure, file types, configs, CI/CD, linter configs, README, CLAUDE.md, git history -- and generate an AGENTS.md.

**Deduplication rule (highest priority):** Read CLAUDE.md carefully. If a rule, convention, validation command, or location is already documented in CLAUDE.md, do NOT repeat it in AGENTS.md. Agents read both files. AGENTS.md exists only for information that CLAUDE.md does not cover.

**Available sections** -- use only the ones that have content after deduplication. Omit any section that would be empty or fully covered by CLAUDE.md:

1. **Must-follow constraints** — Hard rules not covered by CLAUDE.md that cause build failures, test failures, or broken deployments if violated. Use inline labels for grouping (e.g., "Branching:", "Safety:", "ASCII-first:") instead of sub-headings. *Exclude:* anything already in CLAUDE.md, or enforced by a linter/formatter config file.

2. **Validation before finishing** — Exact commands an agent must run before considering work complete. *Exclude:* commands already listed in CLAUDE.md's Testing section.

3. **Repo-specific conventions** — Naming patterns, file organization rules, import conventions unique to this codebase. *Exclude:* conventions already documented in CLAUDE.md (e.g., timestamp format, retention policy, commit format).

4. **Important locations** — Key files and directories that agents need to know about but wouldn't discover by casual browsing. *Exclude:* obvious paths and any paths already listed in CLAUDE.md.

5. **Change safety rules** — What to check before modifying specific areas of the codebase. *Exclude:* safety rules already documented in CLAUDE.md (e.g., SYNC contract).

6. **Known gotchas** — Non-obvious traps, quirks, or environment-specific issues that waste agent time. *Exclude:* issues documented in README or CLAUDE.md.

**Section rules:**
- Every bullet must be specific to THIS project. If you could copy-paste it into any repo, delete it.
- Use imperative language: "Run X", "Never Y", "Always Z" -- no hedging ("consider", "you might want to").
- Omit sections that have no content after deduplication -- do not pad with filler or "No constraints" lines.
- Do NOT duplicate content from README.md or CLAUDE.md. When in doubt, omit.

---

# Quality Gates

Before saving, verify:

**BLOCKING** (fix before saving):
- Every bullet is specific to this project -- no generic advice that applies to any codebase.
- No content duplicated from README.md or CLAUDE.md.
- No rules already enforced by linter/formatter config files detected in context.
- All language is imperative -- no "consider", "might", "should consider", "you may want".
- No empty or filler sections -- omit sections with no unique content.

**WARNING** (review and trim):
- File exceeds 80 lines -- AGENTS.md should be a concise checklist, not documentation.
- Any section has more than 7 bullets -- merge or remove the least critical.

---

# Anti-Patterns

- **Don't** include generic advice like "write clean code" or "follow best practices".
- **Don't** duplicate the README or CLAUDE.md -- agents read both files already.
- **Don't** hedge with "you might want to" or "consider doing" -- be direct.
- **Don't** keep empty sections -- omit them entirely.
- **Don't** list linter rules -- the linter already enforces them.

---

# Save & Verify

1. Write the generated AGENTS.md to the project root.
   **Verify:** Read back the file and confirm it matches what was generated.
2. Count total lines and sections used.
   **Verify:** Check line count < 80. Confirm no empty sections remain.

---

# Output

> **AGENTS.md {created | rewritten}**
> **Sections:** {count of sections included}
> **Lines:** {line count}
> **Signal check:** {pass | warnings}