Documentation and adrs

Skill vignesh2027/AI-AGENT-SKILLS/skills/documentation-and-adrs

Turn your ai agent into senior engineer..The result is fast code that fails slowly. AI Agent Skills solves this by giving agents the same disciplined workflows senior engineers use

Install

npx -y skills add vignesh2027/AI-AGENT-SKILLS --skill documentation-and-adrs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Write documentation that stays accurate and decisions that stay recorded

SKILL.md

3.0 KB, as published. Nobody here has run it

Overview

Documentation that is wrong is worse than no documentation — it confidently misleads. This skill writes documentation that is minimal, accurate, and maintained. It also captures architectural decisions (ADRs) so future engineers understand why the system is the way it is.

When to Use

Before shipping a new feature or API
When changing a public interface
When making an architectural decision that is hard to reverse
When documenting a non-obvious system behavior

Process

Step 1: Audience-first

Before writing: who is the reader? What do they already know? What do they need to do after reading this? Write for that person, not for yourself.

Step 2: Document the why, not just the what

The code describes what. The documentation must describe: why this design, what was rejected, what trade-offs were made. This is what prevents future engineers from "improving" something that can't be improved.

Step 3: README structure

Good README:

What is this? (one sentence)
Why does it exist? (one paragraph)
Quick start (the first 5 minutes)
Core concepts (only what's non-obvious)
Reference (exhaustive, machine-readable if possible)
Contributing (link to CONTRIBUTING.md)

Step 4: API documentation

For every public API endpoint or function:

Purpose (one sentence)
Parameters: name, type, constraints, required/optional
Return value: type, shape, possible values
Error cases: what errors can occur and when
Example: one complete working example

Step 5: Architecture Decision Records (ADRs)

Write an ADR for every decision that is:

Hard to reverse
Non-obvious in its rationale
Likely to be questioned by a future engineer

ADR format:

# ADR-NNN: [Short Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-NNN]

## Context
[What situation led to this decision?]

## Decision
[What was decided?]

## Alternatives Considered
[What else was evaluated and why was it rejected?]

## Consequences
[What becomes easier or harder as a result?]

Step 6: Keep documentation close to the code

Documentation in a separate wiki will drift. Prefer: inline docstrings for functions, README.md in each directory, ADRs in a docs/decisions/ folder.

Step 7: Test your documentation

Have someone unfamiliar with the system follow the quick start. If they get stuck, the documentation is wrong.

Anti-Rationalizations

"The code is self-documenting" Code says what. Documentation says why. No code is self-documenting for the why.

"No one reads ADRs" No one reads ADRs until they need to. That moment always comes.

Verification Requirements

README has: what, why, quick start, contributing
All public APIs documented with parameters, returns, and examples
ADR written for hard-to-reverse decisions
Documentation reviewed by someone unfamiliar with the system
Docs live close to the code they describe