Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

writing-docs-and-skills

Writes and maintains the documentation of a repository that agents work in, so that an agent reads little, finds the one place each fact lives and is not misled by stale text. Symptoms: a fact written in several places that disagree, a rules file loaded on every turn that has grown past its budget, a doc that describes what the code no longer does, docs written in house terms instead of the field's standard terms, a restructuring of the docs, or a method to be kept as a skill. Puts each text in its kind and the one place that kind lives, checks each claim against the code, states the current state only, turns a rule that can be checked into a check, rewrites docs from an inventory without losing an item, and distils a skill from recorded work with the project's facts in a binding. Use with any repository developed mostly by AI agents (an AGENTS.md or CLAUDE.md, skills, a docs folder) whenever a doc, a rule, a module's header, a tool's manual or a skill is written, moved or rewritten.

HuberyLL · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add HuberyLL/ponlai --skill writing-docs-and-skills

About this skill


name: writing-docs-and-skills description: Writes and maintains the documentation of a repository that agents work in, so that an agent reads little, finds the one place each fact lives and is not misled by stale text. Symptoms: a fact written in several places that disagree, a rules file loaded on every turn that has grown past its budget, a doc that describes what the code no longer does, docs written in house terms instead of the field's standard terms, a restructuring of the docs, or a method to be kept as a skill. Puts each text in its kind and the one place that kind lives, checks each claim against the code, states the current state only, turns a rule that can be checked into a check, rewrites docs from an inventory without losing an item, and distils a skill from recorded work with the project's facts in a binding. Use with any repository developed mostly by AI agents (an AGENTS.md or CLAUDE.md, skills, a docs folder) whenever a doc, a rule, a module's header, a tool's manual or a skill is written, moved or rewritten.

Writing docs and skills

An agent reads what it is given and what it finds, and trusts both. Two copies of a fact drift apart, and the agent follows either one. A sentence that the code has outgrown is followed as if it were still true. A rules file is loaded on every turn, so each of its lines costs context on every turn. The method is to put each text in the one place where its kind lives, check it against the code, write only the current state, and keep it true with checks rather than with care.

Rules most often broken without notice

  • Write each fact or rule in one place. Every other place links to it and does not restate it. Before you write a fact, search for it. Move or link an existing copy; never leave it beside yours.
  • Check a claim about the code against the code before you write it. If a doc disagrees with the code, fix the doc to match the code. Copying a sentence from another doc is not checking it.
  • Write only the current state. What was tried, what the code did before, and why it changed go in the commit message. Never cite private notes, plans, task names or milestones.
  • The rules file is loaded on every turn. It holds the rules that every change follows and an index, nothing else. A multi-step method goes in a skill; a rule of one module goes in that module's header.
  • If a rule can be a check, make it a check in the same change. Text is the last resort.
  • When a path moves, fix it everywhere in the same change: docs, code comments, strings, configuration and skills.
  • A rewrite never drops an item or changes a rule's meaning in passing. Take deletions and changes of meaning to the owner first. If you think a rule is wrong, list it for the owner; do not fix it.
  • A rule that must hold is never only in a skill, because the model decides whether a skill loads. Give the rule a check, or a line in the rules file.

The project's facts: the binding

Steps marked "(binding: X)" need facts about the project: where each kind of text lives, the size budget of the rules file, the docs checks and how to run them, the commit convention, where skills and their bindings live. Read section X of docs/bindings/writing-docs-and-skills.md when you reach the step. If the project's AGENTS.md or CLAUDE.md names another file for this skill, that file wins.

No binding: find each fact in the project (the rules file, the docs index, package.json's scripts, the checks the commit hooks run) and ask the owner for what you cannot find. When the work ends, offer to write what you found as the binding, one section per step.

Workflow

Copy this checklist and keep it up to date:

- [ ] 1. Name the kind and where it lives
- [ ] 2. Check the claim against the code
- [ ] 3. Write it once; link from the rest
- [ ] 4. Keep the always-loaded text in budget
- [ ] 5. Turn what can be checked into a check
- [ ] 6. Run the docs checks
- [ ] 7. Commit, with the history in the message

For a restructuring of existing docs, follow "Rewriting docs" below as well; for a new skill, "Writing a skill".

1. Name the kind and where it lives (binding: Kinds)

Each text is one kind, and each kind has one home and one time it is read:

KindWhat it holdsRead whenWhat does not belong
Rules file (AGENTS.md, or CLAUDE.md importing it)Rules every change follows (one line each; what enforces each and the mistake behind it are recorded where the binding says), the commands, the folders, an index of what to read before which taskEvery turnSteps of a method; rules of one module; reasons at length; anything a check holds
SkillA method for one kind of task, its silent-failure rules firstWhen the task comes upThe project's paths and values (the binding); what the model already knows
BindingOne project's facts for a skill, a section per stepAt the step that needs itThe method
Tool manual (the tool's header, printed by --help)The question it answers, how to call it, its output, what it needs (a GPU, a server)When the tool is usedHow it came to be
Architecture pageWhat the project is, its layers and what each owns, the main flows, the folders, the rules across layers in one sentence eachBefore a structural changeImplementation detail; each rule's full text (a reference page)
Reference pageFacts on one subject, looked up a section at a timeWhen looking something upSteps; reasons
Design pageDecisions: what, why, what to avoid, what it shows as on screen or in playBefore a decision of directionMeasured values (reference)
Module headerThat module's purpose (first line, one sentence), its rules and their reasonsWhen the module is openedRules that span modules
Commit messageWhy the change, what was tried and droppedWhen tracing history—
  • A fact or rule of one module lives in that module's header
Read the complete source ↗