Drowning in markdown

I'd like to talk about the world of AI markdown.

Hear me out.

AGENTS.md

Let's start with this file. It's a README.md, but for agents. Okay, but why do we need two READMEs? Why should the contents of this file be anything but:

@README.md

I think that when AI performs poorly on a task that the maintainers know how to do, the conclusion is that AI-specific documentation is needed, because the README is meant for humans and those humans are able to do this task just fine.

It seems that using AI agents in a codebase forces us to confront incomplete and poorly written documentation – it doesn't mean we need AI-specific documentation. "But AI docs are different" – yes! They're more prescriptive and concise, focusing on the do's and don'ts. Explaining the "why" of something in a README is often not the right place. The README should link to another document for that discussion.

I've also seen AGENTS.md files that had better content than the project's own README.md. They did a better job of keeping context to a minimum and provided a list of available documentation so that the agent can decide to read it when it needs to. To be honest, that sounds great for my human brain too. I want that to be the actual README.md

Skills

Skills are markdown files with frontmatter. They can be invoked manually by the user, or automatically by the agent. If a skill can be triggered automatically, the harness will insert the skill description into context at the start of a session. If not, then the user will need to trigger the skill at will e.g. /security-review

One of my problems with skills is that someone is eventually going to take this post and turn it into one for no reason. There's a skills craze. People are dealing skills and selling undergound Claude dotfiles like JavaScript starter kits in 2020.

/fml

I've seen three variants of skills, and I'm totally inventing the below terms:

1. Passive knowledge (automatically invoked)
2. Vague instruction (manual)
3. Explicit instruction of tools (manual)

The passive knowledge type is an anti-pattern in my opinion. Skills that are invoked automatically to add information to context that is presumably missing from tranining data are well-intentioned, but that's the wrong tool for the job. This is what documentation is for. There's nothing skillful about passive knowledge. Add it as a new doc entry to the README instead.

Vague instruction skills offer little value over what the agent already knows and can do. They arm the agent with a prompt nudging it to use that knowledge without explicit 'how-to's e.g. "You are a security researcher, find security issues, look for secrets". Those skills are often so generic and non-prescriptive that I doubt their longevity as models evolve. In the future, I should be able to say "find security issues" without other magic incantations.

Lastly, type 3: actual skills. Those are genuinely good – please keep making them. They either provide new tools or give clear step-by-step instructions to do a thing. The latter gets mixed up with runbooks. If they're generic across systems, then they should be a skill. If it's about performing a well defined step-by-step procedure in a specific system, then it's a runbook. Skills are system agnostic. Runbooks are not. I don't see a benefit in replacing runbooks with skills. It just leads to confusion. Everyone already knows what runbooks are for.

# tired
/trace-request

# wired
@docs/runbooks/trace-request.md

Prompt begging

Docs created specifically for AI. These docs instruct beg future agents to follow certain rules. I have a memory file begging the machine to use jj instead of git. It's the right way for personal preferences, but it's not how we should go about enforcing shared practices in a codebase. Context engineering is hard, and most AI docs I see rarely have a test suite to prove the begging improves output. If context becomes code, then it's worth having tests that monitor for output degradation as the codebase, the surrounding docs, and the AI models in fashion change over time.

Instead of creating more documentation, we need to build actual guard rails. We should take as much of our programming taste as possible and express it in static analysis tooling. Duplicating markdown everywhere is not manageable. Many skills could be written as scripts and CLIs rather than markdown. And the best thing is, we're very familiar with writing tests for those.

Seeing how easy it is to tell the markdown goblin to run its skill generator or to "write documentation with what you learned from our interaction" – I can see how we got here. It makes the wrong thing easy to do.

Conclusion

In conclusion, to drown in markdown, we should:

• Write a superior AGENTS.md instead of refactoring the README.md
• Create skills that should be documentation
• Rebrand runbooks as skills
• Focus on creating new skills instead of tools
• Generate codebase rules in markdown instead of linters
• Repeat the above endlessly