You know the README that lies. It confidently walks you through a setup step that stopped working three commits ago, points at a flag that got renamed, describes an architecture the code outgrew months back. Nobody wrote it to be wrong. It was right once. Then the code moved and the docs didn't, because updating them was a separate task that lived on a separate day that never came.

That gap has a cost I only really noticed once agents started reading my projects. A human skims a stale doc and shrugs. An agent takes it literally, follows the instruction that no longer holds, and confidently does the wrong thing. The docs aren't just for people anymore; they're the map the agent navigates by. A wrong map is worse than no map.

So I built self-documenting, an Agent Skill with one stubborn rule: when the agent changes the code, it updates the docs in the same change. Not later, not in a follow-up pass. The same commit.

Why the same commit matters

Documentation drifts for exactly one reason: writing it is decoupled from changing the code. Anything you defer to "I'll document this later" is competing with everything else later, and it loses.

Tie the doc update to the code change and the whole problem goes away. There's no window for drift to open, because the doc and the code move together or not at all. It's the same reason tests live next to the code they cover. Distance is what rots.

Install it

It's packaged with skillship, so it installs across Cursor, Claude Code, Claude Web, and Cowork:

npx skillship@latest install shivdeepak/self-documenting -a cursor -a claude-code
# or, via the underlying multi-agent installer:
npx skills add shivdeepak/self-documenting

The skillship install does the part I care about most: for Cursor it also drops in the trigger rule (cursor/rules/self-documenting.mdc), so the agent invokes the skill on its own after a qualifying change instead of waiting for you to remember. npx skills installs the skill file only, not the rule, so reach for skillship if you want the automatic behavior.

What counts as a qualifying change

The skill stays out of the way until it's actually needed. It wakes up after the agent fulfills a request that adds, removes, or alters any of:

  • Behavior that the docs describe.
  • Config keys, env vars, or defaults.
  • Commands or setup steps.
  • APIs or interfaces: signatures, params, return values.
  • Project structure: new components, removed modules, moved files.

Refactors that change nothing a reader would notice don't trigger it. Neither does a typo fix. The point isn't to document everything; it's to never let the things that already are documented fall out of date.

What it does when it fires

Once a qualifying change lands, the agent runs a short checklist before considering the work done:

  • Figure out which docs the change touches, and update them to match the new behavior.
  • If the project has no docs yet, bootstrap a directory (.ai/ for agent guides, or docs/) seeded with an index.md, holding just the doc this change needs. It doesn't back-fill documentation for unrelated parts of the codebase.
  • If the change concerns a topic nothing covers yet, add a new focused doc, one concern per file, and link it from the nearest index.md.
  • Delete docs for anything that got removed, and keep each directory's index.md current.
  • Re-check that the examples and commands in the docs still run as written.

It also knows where each kind of change belongs: setup steps and usage go in the README, conventions and layout go in the agent guides (AGENTS.md, CLAUDE.md, .cursor/rules/), signatures and config keys go in the interface docs, and inline comments are reserved for non-obvious intent or trade-offs, never for narrating what the code plainly does.

The docs become a map, not a chore

Here's the part that turned out to matter more than the drift fix. Because the docs are split by topic behind an index.md, they double as the thing an agent reads to understand the project before it changes anything.

It's the same progressive disclosure idea I leaned on in knowledge-base-builder: the agent reads the index.md first, then opens only the one or two files it needs, instead of loading every doc and burning context and tokens on the rest. A well-kept index is cheaper to read and more accurate to act on. Keeping docs current stopped being upkeep and started being the thing that makes the next change go right.

The restraint I'm proudest of

The last line of the skill is the one I'd defend hardest: if a change affects no docs, do nothing. Don't invent documentation.

A skill whose whole job is writing docs is one bad instinct away from generating a paragraph for every commit, and that noise is its own kind of drift. So it's deliberately quiet. It updates an existing doc before it creates a new file, prefers correcting over adding, and when there's genuinely nothing to say, it says nothing. The goal was never more documentation. It was documentation you can trust because it has never been allowed to go stale.

The repo is at github.com/shivdeepak/self-documenting. Install it, make a change that renames a flag, and watch the README fix itself in the same breath. That small moment, the doc correcting itself without being asked, is the whole reason I wanted it.