writing-for-agents: How to Write Docs Agents Actually Read

Fri, 28 Aug 2026 00:00:00 +0000

Your agent skips half of AGENTS.md and still follows a 40-line skill to the letter. The difference is writing, not packaging. Matt Pocock’s writing-for-agents skill (158,238 installs, #263 on the skills.sh all-time board) is the reference document behind that difference — it codifies how to write any file an agent consumes: skills, AGENTS.md, CLAUDE.md, or a doc reached by a pointer. I read its 81-line SKILL.md plus SKILL-MECHANICS.md and scraped the live leaderboard on 2026-08-28. What surprised me: the file never mentions output format. It teaches one idea — an agent reads what the wording makes reachable, not what you intended to say.

Prompt Design on Top AI Skills

writing-for-agents: How to Write Docs Agents Actually Read