Skip to content
SkillModel-led2,694 tokens in use

documentation-and-adrs

Record architecture decisions, comments, API docs and changelogs, and check whether a doc has drifted from its code.

119,377 stars on the repository MIT Licenseaddyosmani/agent-skills · skills/documentation-and-adrs
npx skills add addyosmani/agent-skills --skill documentation-and-adrs
View source

Install command as written in the repository's README

Skill label

measured from its files

What installing documentation-and-adrs costs

91tokens idle
2,694tokens in use

Idle is what sits in context while the skill is installed. In use is its instructions, loaded when it runs. Counts are approximate, made offline with cl100k_base.

Model dependence Model-led

Script-ledMixedModel-led

Mostly instructions, so how well it works depends on the model that follows them.

This describes the skill's structure, how much of it is scripts. It does not say how well it works.

Touches

shelldetectednetworkdetectedgitdetectedcredentialsdetected

Declared tags come from the skill's frontmatter; detected ones from its scripts, its code blocks and the commands it names in inline code. This is detected, not audited.

How it scores

Quality

How well the skill is written, counted from its own files: its frontmatter, its steps, examples, stated output and constraints, its size and whether every file it ships is one it names.How we score it →
Excellent
  • Frontmatter12/15
  • Structure25/25
  • Examples15/15
  • Output15/15
  • Size13/15
  • Resources10/15

Security

Starts at 100 and loses points for each thing in the skill's files that a reader should look at first.How we score it →
Good
  • Reaches the network−10

    does this on the machine, and the frontmatter does not say so

    SKILL.md, line 212
  • Reads credentials−15

    does this on the machine, and the frontmatter does not say so

    SKILL.md, line 213
  • Runs shell commands−5

    does this on the machine, and the frontmatter does not say so

    SKILL.md, line 273
  • Runs git commands−5

    does this on the machine, and the frontmatter does not say so

    SKILL.md, line 276

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Excellent
  • Development activity96
  • Maintenance100
  • Community76
  • Maturity32
  • Momentum40

Documentation and ADRs teaches an agent to document the why behind decisions. It provides an ADR template with status, context, alternatives and consequences, and tells the agent to match any existing ADR convention before applying its defaults.

The skill also covers inline comments, API documentation, README structure, changelogs, documentation for agents, a prose review pass and a git-based method for deciding whether a doc is stale.

What You Get

  • An ADR template and lifecycle
  • Guidance for inline comments, API docs, READMEs and changelogs
  • A drift-detection shell snippet that uses git history
  • A prose review procedure and a verification checklist

Common Use Cases

  • Writing an ADR for a significant technical choice
  • Documenting a public API change
  • Checking whether docs are out of date
  • Setting up README and rules files for a project

What Makes It Unique

The skill includes a drift check that decides staleness from commit order and refuses to call a doc current when the order is unknown. It also protects change logs by requiring dated appended entries and a prose review step that preserves qualifiers.

Under The Hood

The skill is a single SKILL.md of instructions and templates. Its drift snippet runs git log and git merge-base on the repository, which is read-only. The agent also writes documentation files such as ADRs, READMEs and changelogs in the project.

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers