# 'Write AGENTS.md' Skill ## 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. **Published:** October 26, 2026 **Author:** Nikita Chernyi Recently I published [Learn How To Prompt Already](https://rakshazi.me/blog/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](https://rakshazi.me/blog/write-agentsmd-skill/go.md "unmodified Go conventions, copied as-is"). 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](#the-skill) Repo: [github.com/rakshazi/write-agentsmd](https://github.com/rakshazi/write-agentsmd) 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): ```bash 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](#flip-the-coin) Heads or Tails? That’s what you get with auto-generated AGENTS.md. [Evidence](https://github.com/rakshazi/write-agentsmd/blob/ba69ea71ee7c0d78539ff0a0e056e8f1dec9f0cc/references/evidence.md) 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](https://github.com/rakshazi/write-agentsmd/blob/ba69ea71ee7c0d78539ff0a0e056e8f1dec9f0cc/references/verification.md) run with 2 conditions on 2 tasks, five runs each, which is 20 agent runs to measure the effect. Also, in one [controlled study](https://arxiv.org/abs/2602.11988), generated AGENTS.md files added about 20% cost without improving success, and hand-written ones beat them significantly. [Another](https://arxiv.org/abs/2601.20404) 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?](#so-whats-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?](#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](https://omp.sh) harness, and it has extended [context files support](https://omp.sh/docs/context-files) and a thing called [TTSR](https://omp.sh/docs/ttsr "Time-Traveling Stream Rules"), so my setup looks like this: - 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](https://rakshazi.me/blog/write-agentsmd-skill/go.md) 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](https://rakshazi.me/blog/write-agentsmd-skill/go-as-type.md) (this is basically how you make the agent “learn” modern Go features) ## [Conclusion](#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](https://rakshazi.me/blog/learn-how-to-prompt-already/). --- ## (Un-)related posts about AI > 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!' * [Learn How To Prompt Already](/blog/learn-how-to-prompt-already/) * [Stop Enter-ing, YOLO It](/blog/stop-entering-yolo-it/) * [If It Is So Dangerous, Then Sandbox It!](/blog/it-is-so-dangerous-sandbox/) * [You Don't Need A %Frontier LLM%](/blog/you-dont-need-frontier-llm/) * [Krea 2 Prompting Skill](/blog/krea2-prompting-skill/) Too much AI for today? See [Misc](/blog/category/misc/), [SMTP](/blog/category/smtp/) for a change --- [Nikita Chernyi](https://rakshazi.me/) > [Blog](https://rakshazi.me/blog/) > [AI](https://rakshazi.me/blog/category/ai/) > 'Write AGENTS.md' Skill [llms.txt](https://rakshazi.me/llms.txt) - machine-readable site index