Documentation and ADRs: Agent Skill for Future-Proofing

Where this fits

You ask an agent to update a README or capture a design decision. It returns a wall of generic prose that a future maintainer can't act on. This skill grounds documentation and ADR generation in repository facts, explicit assumptions, and verification links, so the output is precise, testable, and useful for the next person who touches the codebase.

Why agents benefit

• It forces the agent to identify the reader, the decision, the freshness owner, and the expected action before writing a single line.
• It separates facts from assumptions and flags version- or environment-specific statements, reducing misleading docs.
• It requires the agent to test every command, code sample, relative link, and file path it mentions, catching broken instructions before they ship.
• It structures output as the shortest usable path first, pushing exhaustive detail into linked references—matching how engineers actually consume docs.
• Its ADR workflow captures context, decision, alternatives, and consequences for architecture- or interface-level choices, making trade-offs explicit.

Practical scenarios

Updating a README after a config change

Your agent needs to document a new RATE_LIMIT environment variable. Instead of guessing, it inspects the config loader, tests the variable's effect, and updates the README with a concrete example and a link to the full reference.

Recording a migration decision as an ADR

Your team switches from token-based to header-based authentication. The agent examines the auth middleware, lists alternatives like OAuth2 or API keys, and writes an ADR that records why the change was made and what operational consequences follow.

Writing a runbook for a new service

Your agent generates a runbook for a microservice. It pulls actual commands from the deployment scripts, verifies health-check endpoints, and marks any assumptions about environment-specific behavior—so on-call engineers get a reliable playbook.

Add it to your agent workflow

Install the skill with:

npx skills add thiientv/godmode --skill documentation-and-adrs

After installation, prompt your agent with a concrete task: "Document the new rate-limiting config in the README and add an ADR for the switch from token to header-based auth." The skill will inspect the repository, verify commands, and produce a PR-ready document with the right structure.

Compare before adopting

Before you adopt this skill, compare it against your current documentation workflow. Check quality signals like the skill's star count (94) and recent commit history—is it actively maintained? Look at alternatives: a generic "write docs" prompt might work for trivial tasks, but this skill enforces discipline. Also consider fit: does your agent already have a documentation pipeline? If so, this skill can complement it rather than replace it.

Why it is worth tracking

This skill directly addresses a common failure mode: agents producing plausible but unverifiable documentation. With 94 stars and a focused scope, it has shown early community traction. Track it if you want your agents to produce maintainable, fact-checked docs and ADRs. For more details, see its listing on OpenAgentSkill and evaluate it when your documentation output needs to meet higher engineering standards.