# Agent Project Scaffold: free AGENTS.md check

**Six read-only checks on one AGENTS.md, so the rules every agent reads first are short, scoped and say who approves.**

## The five sections that matter

1. **Purpose**: one or two lines on what this project is for.
2. **Scope**: what is in, and what is out (production, money, messages to people).
3. **Approval rule**: draft, prepared, approved and sent are four states. Nothing is sent, posted, deployed, bought, deleted or merged without the owner's written yes.
4. **Where things live**: rules/, commands/, skills/, agents/, hooks/.
5. **Done means**: the check passes and the agent says what it ran and what it did not test.

Keep it under 120 lines. Claude Code reads it through a one-line CLAUDE.md (`@AGENTS.md`); Codex and Hermes read it directly; paste it into Grok Bot as a standing instruction.

## Run it

`python3 agents_md_check.py AGENTS.md`

Prompt for any agent:
> Run python3 agents_md_check.py AGENTS.md and tell me what is missing. Propose text for each missing section, but do not write the Approval rule for me.

#### file: mini/agents_md_check.py
~~~~python
#!/usr/bin/env python3
"""Agent Project Scaffold free sample: six read-only checks on one AGENTS.md. Python 3.8+.
Usage: python3 agents_md_check.py AGENTS.md"""
import re, sys
def check(t):
    F = []
    if len(t.splitlines()) > 120: F.append("M01 over 120 lines; agents skim long rule files. Move detail into rules/")
    for h, c in (("Purpose", "M02"), ("Scope", "M03"), ("Approval rule", "M04"), ("Done means", "M05")):
        if not re.search(r"^## " + h, t, re.M): F.append(f"{c} no '## {h}' section")
    if re.search(r"(sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16})", t): F.append("M06 looks like a secret key in the file")
    return F
if __name__ == "__main__":
    if len(sys.argv) != 2: print(__doc__); sys.exit(2)
    F = check(open(sys.argv[1], encoding="utf-8").read()); print("\n".join(F) or "OK: 0 findings"); sys.exit(1 if F else 0)
~~~~

## The full kit adds

`init` for the whole tree, 23 checks across rules, skills, agents, hooks and `.mcp.json`, a secret scan, a pre-done hook, starter files and 29 tests. $19.

Tested 2026-11-01 on Linux, Python 3.8 to 3.13: the template passes and each of the six faults is caught.