What does this skill do, and when should you use it?
Documentation-and-adrs is one skill in addyosmani/agent-skills, focused on architecture decision records, API documentation, inline comments, README files, changelogs, and documentation for AI agents. It prioritizes recording why a decision was made, not merely what the code does, and instructs agents to follow an existing repository convention before applying a default ADR format. It also defines an ADR lifecycle, documentation checks, and common anti-patterns. It fits teams that need durable engineering context, but it is not presented as an automated documentation generator or publishing tool.
Guides an agent to create or update documentation for significant architecture decisions, public API changes, user-facing feature releases, and repeatedly explained context; inspect existing ADRs, project instructions, and related configuration to match location, format, numbering, and headings; produce ADRs covering status, date, context, decision, alternatives, and consequences; document public API parameters, return values, errors, and examples; record non-obvious intent and known gotchas in inline comments; and verify README coverage, changelog updates, agent rules, and documentation checklists.
- An engineer choosing a framework, database, authentication strategy, or infrastructure needs to preserve the rationale and rejected alternatives.
- A team maintaining a public REST, GraphQL, or library interface needs parameter, return-value, error, and example documentation.
- A feature release changes user-facing behavior and requires coordinated README, changelog, and project-context updates.
- New engineers or AI agents repeatedly ask about the same design context and the team wants to turn that knowledge into durable documentation.
How do you install this skill?
- No scripts or installation flows were executed, so actual agent triggering, document generation, and failure behavior remain unverified.
- Before use, add project-specific ADR location and numbering rules, sensitive-information review, user-confirmation, and rollback requirements; the default template must not override existing conventions.
- Publisher identity is not verified by the FollowSkills enterprise registry, so maintenance status and provenance should be checked separately.
- Local filesystem
Install the repository's full set of 24 skills with npx skills add addyosmani/agent-skills. Browse first with npx skills add addyosmani/agent-skills --list. The README also documents installing an individual skill by name; for this skill, use npx skills add addyosmani/agent-skills --skill documentation-and-adrs. The repository is licensed under MIT.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/addyosmani/agent-skills.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/skills/documentation-and-adrs" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- Create an ADR for this database choice. First inspect the repository’s existing ADR location, numbering, and format, then document the context, alternatives, decision, and consequences.
Use the skill as a source in an Agent Skills-compatible client and give it a concrete task, for example: “Create an ADR for this database choice. First inspect the repository’s existing ADR location, numbering, and format, then document the context, alternatives, decision, and consequences.” Its description indicates use for architectural decisions, public API changes, and feature releases. The README does not list a dedicated slash command for this skill or document extra scripts or automated execution.
What are this skill's strengths and limitations?
- Covers ADRs, API documentation, inline comments, READMEs, changelogs, and AI-agent context.
- Requires matching an existing repository convention before introducing a new ADR scheme.
- Separates documenting intent from restating code and includes a post-documentation verification checklist.
- The MIT license permits use in projects, teams, and tools.
- The supplied material presents process guidance and templates, not scripts for automatic creation, validation, or publishing.
- Examples use technologies such as PostgreSQL and Prisma, but the skill does not require those technologies.
- The supplied material provides no test suite, runtime integration, or evidence of adoption in a specific project.
- Teams still must judge which decisions are significant and resolve conflicts in existing documentation conventions.
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| Architecture Decisions & Docs this page | 53 · Use with care | ★ 107k | 13d ago | MIT |
| Azure Skill Creator ✓ Microsoft · Official | 48 · Use with care | ★ 2.7k | 3mo ago | MIT |
| Skill Seekers Bootstrap | 41 · Not recommended | ★ 15k | 26d ago | MIT |
| Effect JSDoc Authoring Skill | 77 · Strongly recommended | ★ 28k | 12d ago | MIT |
| cmux Architecture Skill | 63 · Recommended | ★ 28k | 12d ago | NOASSERTION |
The README names Superpowers and Matt Pocock's skills as comparison alternatives and links to a comparison document. That document's contents were not supplied, so specific differences cannot be verified here.
How did FollowSkills review this skill?
The skill only provides documentation and ADR guidance; it executes no commands and requests no credentials or external services, so permission risk is low. It does not specify sensitive-data handling, user confirmation, data flows, rollback, or source verification, so full marks are not justified.
The content is internally consistent and includes triggers, templates, anti-patterns, and verification checklists, making the happy path plausible. There are no skill-specific tests, abnormal-input handling, or diagnosable failure messages, so the static cap requires a deduction.
It clearly targets architectural decisions, public APIs, shipped features, and team or agent context, and states when not to use it. Output formats, non-fit boundaries, and semantic trigger details remain broad, and Chinese-language support is not documented. Core functionality does not depend on overseas services.
The skill has an overview, usage guidance, templates, lifecycle, examples, rationalization table, and verification section; repository context supplies an MIT license and maintainer information. The skill itself lacks versioning, changelog, installation or dependency notes, and a clear update owner or path.
The ADR template, documentation principles, API example, and checklist can directly support common documentation work. However, the material is generic and provides no verified representative outputs or comparative-benefit evidence, so project-specific adaptation may still be substantial.
Repository CI claims to validate skill structure and run evaluations, but the supplied test fixture is unrelated to this skill. No dedicated tests cover ADR, API-documentation, or checklist paths, so only limited auditable evidence is available.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →