Skip to content
Kitbay
Skill

documentation-and-adrs

MITUpdated on Nov 1, 2026115,373GitHub stars

A skill from Addy Osmani's agent-skills collection for recording why code is the way it is.

What the skill teaches

A skill from Addy Osmani's agent-skills collection for recording why code is the way it is. When the agent makes an architectural decision, changes a public API or ships user-facing behaviour, it writes an architecture decision record, first matching any existing ADR folder, numbering and headings, and otherwise using the skill's template with context, decision, alternatives and consequences. It also covers when inline comments are worth adding and when not, API documentation through typed doc comments or OpenAPI, a README outline, keeping a changelog, documentation written for agents, and a final prose review.

Capabilities

  • Write architecture decision records matching existing conventions
  • Document public APIs with doc comments or OpenAPI
  • Outline a README and maintain a changelog
  • Decide when inline comments are needed