# Documentation And Adrs

> Write documentation that stays accurate and decisions that stay recorded

- **Type:** Skill
- **Install:** `agentstack add skill-vignesh2027-ai-agent-skills-documentation-and-adrs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vignesh2027](https://agentstack.voostack.com/s/vignesh2027)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vignesh2027](https://github.com/vignesh2027)
- **Source:** https://github.com/vignesh2027/AI-AGENT-SKILLS/tree/main/skills/documentation-and-adrs

## Install

```sh
agentstack add skill-vignesh2027-ai-agent-skills-documentation-and-adrs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## 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:
1. What is this? (one sentence)
2. Why does it exist? (one paragraph)
3. Quick start (the first 5 minutes)
4. Core concepts (only what's non-obvious)
5. Reference (exhaustive, machine-readable if possible)
6. 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:
```markdown
# 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vignesh2027](https://github.com/vignesh2027)
- **Source:** [vignesh2027/AI-AGENT-SKILLS](https://github.com/vignesh2027/AI-AGENT-SKILLS)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vignesh2027-ai-agent-skills-documentation-and-adrs
- Seller: https://agentstack.voostack.com/s/vignesh2027
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.