'Write AGENTS.md' Skill

by Nikita Chernyi in AI (RSS)

TL;DR for the bots (humans, scroll on)

Auto-Generated AGENTS.md: What the write-agentsmd Skill Does and Why a Draft Is Not Enough

write-agentsmd is an agent skill that drafts, audits, and maintains AGENTS.md files, including nested ones. The post argues that a generated file is only a starting point, and compares AGENTS.md with path-scoped rules, sticky rules, and TTSR enforcement in the Oh My Pi harness.

Recently I published Learn How To Prompt Already, and multiple readers poked me with “hey, your ‘design prompt’ is exactly what goes into AGENTS.md and you don’t need to repeat that in the prompt, learn how to write AGENTS.md already!”.

The thing is: I know how to do that, but I prefer path-scoped rules over AGENTS.md: the harness keeps a one-line entry with the rule’s globs in context and loads the full text only on demand, when a task touches a matching file. For example, here is my go-to rules file for Go: go.md.

And the most important thing is: none of that replaces your head as the source of domain knowledge and the architect of the project.

Okay, the intro is too long already, skill, vibecoder, do you speak it?!

The skill

Repo: github.com/rakshazi/write-agentsmd (opens in new tab)

What it does: writes/updates/maintains AGENTS.md files in your projects, including nested ones.

Install (replace ~/.agents with your agent’s directory, if needed):

git clone https://github.com/rakshazi/write-agentsmd.git ~/.agents/skills/write-agentsmd

Then ask your agent to write AGENTS.md (or audit/update the existing one).

Apart from create/edit/maintain/audit AGENTS.md files, the skill also:

And has a “scope creep” fix: any bugs found during the codebase scan when drafting AGENTS.md are not fixed in place, but saved in a separate file (TODO_BEFORE_SHIPPING.md), which you later review and either fix or accept as expected, because I don’t like when “write AGENTS.md” becomes a 10k-line diff with the agent reporting “while I was there, I fixed 100500 bugs”. Yes, painfully specific, consider that my personal trauma.

The skill was developed and calibrated on dozens of runs with potatoes 4b models, so it will work somewhat good even on small local models.

There are even more features, but naming everything would turn this post into a single-page copy of the skill’s repo, so go check out the skill for the details.

And it might be pointless. What? Why?!

Flip the coin

Heads or Tails? That’s what you get with auto-generated AGENTS.md.

Evidence (opens in new tab) shows that while AGENTS.md may help with reducing the amount of time and tokens to do the job, there is no 100% guarantee that it will, and the best way to find out is to do a verification (opens in new tab) run with 2 conditions on 2 tasks, five runs each, which is 20 agent runs to measure the effect, exactly the verification only people with unlimited tokens can afford.

Also, in one controlled study (opens in new tab), generated AGENTS.md files added about 20% cost without improving success, and hand-written ones beat them significantly. Another (opens in new tab) found AGENTS.md cut median runtime by 29% and output tokens by 17%, without changing task completion. Short, specific files save you time and tokens, while generic AI slop costs more and does nothing for success.

That doesn’t sound convincing, right? Yeah, but there is a neat part:

So, what’s the point?

Drafting and maintenance.

Yeah, “machine god” is not a panacea, but it can give you a good starting point: a draft AGENTS.md that you edit and improve manually before using it.

Also, agents are better at maintaining AGENTS.md: they read it every session, and contradictory (or stale) instructions are visible during the work.

One of the examples from a real project: AGENTS.md had a bullet point “raw SQL is prohibited”, the agent writes raw SQL in Go code, and when you ask “why?”, it answers that the migrations/ dir has 700 raw SQL files, so it decided raw SQL is acceptable in the code as well.

The skill’s audit mode flags exactly such things.

Any other options?

Yup, plenty of them. Your “global” AGENTS.md/CLAUDE.md/etc., path-scoped rules, hooks/extensions that trigger on specific actions, and so on. Depending on the harness you use, the options might be different, but the basic idea remains unchanged.

For example, I use the Oh My Pi (opens in new tab) harness, and it has extended context files support (opens in new tab) and a thing called TTSR (opens in new tab).

Oh My Pi config
  • global AGENTS.md (~/.omp/agent/AGENTS.md), which holds global rules: when to spawn reviewers and under what conditions, how security scanners (govulncheck, gosec) fit into the pipeline, and so on.
  • rulebooks (~/.omp/agent/rules/go.md) - path-scoped rules, like Go conventions mentioned above
  • “sticky” rules (~/.omp/agent/RULES.md) - attached each turn, like reminders to use built-in tools instead of bash scripts
  • TTSRs (~/.omp/agent/rules/*.md) - triggered by a regex or an AST pattern in thinking, the response, or tool calls. Example: errors.AsType over errors.As (this is basically how you make the agent “learn” modern Go features)
You can do similar in Claude Code, though with limitations

It uses a bit different approach with CLAUDE.md files (opens in new tab), path-scoped rules (opens in new tab), and hooks (opens in new tab):

  • global CLAUDE.md (~/.claude/CLAUDE.md)
  • global path-scoped rules (~/.claude/rules/go.md)
  • no sticky rules or TTSRs, but you can try hooks instead
And in Codex, even more limited

It uses AGENTS.md files (opens in new tab), but I didn’t find an alternative for path-scoped rules.

  • global AGENTS.md (~/.codex/AGENTS.md)
  • no global path-scoped rules
  • no sticky rules or TTSRs, and Codex Rules (opens in new tab) is a completely different beast

Conclusion

Even with project-level AGENTS.md (which you can generate now, thanks to the skill), global AGENTS.md/CLAUDE.md/etc., path-scoped rules, “sticky” rules, and TTSRs, YOU are still the source of truth, the domain knowledge, and the architect of your project.

A catgirl scribe writing a long AGENTS.md scroll while the engineer crosses out lines with a red pen AI-generated catgirl, contractually obligated to lure you into the post.

So, Learn How To Prompt Already.

AI, SI, AGI, ASI, LLMs, and other buzzwords from the position of a backend engineer already tired of ‘Dear colleagues, we are AI-first now!’

Too much AI for today? See Misc, SMTP for a change

llms.txt