Stately.ai Skills: When README Files Become Queries Over Code

Your READMEs are almost always out of date The fix: <!-- HTML comments --> Now your AI agents know what's stale and how to regenerate it; no tools necessary Try the "readme" skill: npx skills add statelyai/skills https://t.co/qYonlRZ1pA

David K, DavidKPiano, 84,116 followers · @DavidKPiano on X

Most README tools try to make writing easier. This one tries to make stale documentation harder to produce. The core idea is almost mischievous: hide a symbolic anchor in an HTML comment, then let an AI agent treat that comment as a query against the codebase.

That changes the status of the README. It stops being a hand-edited artifact and becomes a compiled view of the repository. If the code changes, the text can be regenerated from the same anchor without losing the connection to what it was supposed to describe.

README as a Query Language

The clever bit is not that comments exist. Comments have always been there. The trick is that Stately uses them as symbolic references, which means a line of documentation can point to a concept instead of a filename. That is the difference between a note stuck to a cabinet and a real lookup key.

<!-- exported creator functions in src/state.ts -->
## Public API

The public API is derived from the exported creator functions in the module above.

A human sees prose. The skill sees a durable contract. It can scan the comment, resolve what it points to, and then rewrite the section beneath it so the README reflects the current code.

How the Skill Resolves a Comment Into Code

The pipeline is simple enough to describe, which is part of the appeal. First, the agent scans Markdown files for HTML comments. Then it resolves the symbolic reference into a code target, regenerates the linked section, and writes the updated content back into place.

1. Detect HTML comments in Markdown.
2. Resolve the symbolic reference to a code concept.
3. Regenerate the section beneath the comment.
4. Backfill missing anchors when the docs imply a match.
5. Flag ambiguity instead of silently guessing.

That last step matters. The system is not just a replace script with better branding. It is designed to notice drift, infer where a link should have existed, and repair the missing relationship. In other words, it is optimistic about maintenance but not casual about evidence.

Why Logical References Matter More Than File Paths

Path-qualified references are useful, but they still keep documentation tied to the shape of the file tree. Logical references are stronger because they describe intent: public API, exported creators, conceptual sections, the thing a reader actually cares about.

This is the quiet breakthrough. The README is no longer asking, "What file did this come from?" It is asking, "What idea in the codebase should this paragraph represent?"

The Self-Healing README

The best version of this system does not wait for a developer to annotate everything perfectly. It backfills missing references when the prose already implies a connection to code. That makes it feel less like a formatter and more like a maintenance agent with institutional memory.

This is also where the project stops being a clever doc trick and starts looking like infrastructure. If the agent can keep a README aligned with the codebase, then the same pattern can support changelogs, API docs, and any other prose that should never drift far from the source of truth.

The practical gain is not that prose becomes magical. It is that maintenance gets cheaper. A comment anchor is small, familiar, and robust. It gives the agent something stable to hold onto while the surrounding code keeps moving.

From Chatbot to Documentation Daemon

State machines are useful in AI programming and can be used to build agents that observe environments and take actions based on goals.

David Khourshid, CEO, Stately · David Khourshid, CEO Stately: How State Machines Create Robust Software (Deep Dive)

That quote explains the broader philosophy here. Stately keeps returning to systems that observe, act, and stay explicit about state. Skills fit that worldview because they turn LLM behavior into something more like a background process than a one-off chat response.

That is the real thesis. The project is not trying to replace writers. It is trying to remove the tax that makes documentation decay. If the README can be regenerated from structured anchors, then keeping it honest becomes a system property instead of a heroic habit.

Where This Fits in the Skills Ecosystem

The larger trend is toward portable, reusable agent capabilities. In that world, skills are not prompts to paste into a window. They are bounded packages of behavior that can be loaded, resolved, and reused across tasks and tools.

Stately's angle is narrower than a general-purpose skills registry and more interesting for that reason. It uses the skills format to solve one painful problem well: documentation drift. That discipline gives the idea teeth.

What the Repo Is Really Optimizing For

Look past the novelty and the priorities are clear. It optimizes for doc-code alignment, low-friction maintenance, and AI-readable structure. The hidden win is trust. If the README can be regenerated from the repository itself, readers have a better reason to believe what they are reading.

That is the quiet promise of the project. Not better documentation theater. Better documentation reliability.