documentation-and-adrs
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
About
- Publisher
- Addy Osmani
- Tool
- Documentation
Install
The project doesn't document install steps that we could confirm. See the project's own instructions
MCP servers and skills can run code on your computer and act on your data. Review the source before installing.
Details
| Fact | Value | Source |
|---|---|---|
| Type | Skill | |
| Tool | Documentation | |
| Publisher | Addy Osmani | source |
| Official status | Not stated in its documentation | |
| Needs an API key or sign-in | Not stated in its documentation | |
| Includes scripts | No | source |
| Platforms | Not stated in its documentation | |
| AI clients | Not stated in its documentation | |
| Licence | MIT | source |
| Pricing | Not stated in its documentation | |
| Activity | Last commit Nov 1, 2026115,373 GitHub starsDownload data not available (not on npm or PyPI) | source |
| Links | Repository Website |
Other copies of this skill (5)
These differ from this skill's text. They may be adapted copies or older versions.
- documentation-and-adrsnota-america/forgecat-agent-profiles
- documentation-and-adrsnota-america/forgecat-agent-profiles
- documentation-and-adrsnota-america/forgecat-agent-profiles
- documentation-and-adrsmarcmarti9/agentit
- documentation-and-adrsrvey/agent-engineering-kit
More from Addy Osmani
25 skills
- ci-cd-and-automation (Skill)
- api-and-interface-design (Skill)
- browser-testing-with-devtools (Skill)
- code-simplification (Skill)
- constraint-driven-development (Skill)
- using-agent-skills (Skill)
Also listed under: Documentation
Sources
- Skill file (SKILL.md)github.com/addyosmani/agent-skillsNov 10, 2026
- Licence file (LICENSE)github.com/addyosmani/agent-skills · Backs: LicenceNov 12, 2026
- GitHub repositorygithub.com/addyosmani/agent-skills · Backs: Publisher, Activity, LicenceNov 11, 2026
- Folder in the repository (documentation-and-adrs)github.com/addyosmani/agent-skills · Backs: Includes scriptsNov 10, 2026