'Write AGENTS.md' Skill

by Nikita Chernyi in AI (RSS)

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. 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 (omp path shown, so change it if you use a different one):

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

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

Salesman brochure with features ("Worth reading!" - Salesman)

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

  • hunts secret leaks
  • finds context bloat
  • identifies conflicting instructions
  • detects stale rules
  • contains harness-specific guidance (like Codex limits, or Claude Code’s free HTML comments)
  • comes with behavioral evals

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.

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.

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.

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.

I personally use all of them + more. You see, 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), so my setup looks like this:

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.

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