Case study: raising documentation quality with the well-documented skill

The well-documented skill ships in the software-design bundle. Unlike a template generator, it treats documentation as an evidence-first audit target: find what is missing, stale, or lying — then fix the smallest thing that moves the needle. This page walks through how it behaves on a real repository and why it is useful context for both humans and AI agents navigating the codebase.

Install the software-design bundle

The well-documented skill is installed as part of the software-design bundle. Register the marketplace first (see the installation guide), then install.

/plugin install software-design@llm-skills

The problem

Most repository documentation fails in one of three ways: it is missing, it is technically present but silently wrong (broken links, renamed commands, stale directory trees), or it has sprawled — a folder-per-folder README.md farm where file counts go up but nothing is trustworthy. AI agents make this worse: prompt them to "document the repo" and you get invented APIs, duplicated structure, and boilerplate that has nothing to do with the code.

The well-documented skill tries to reverse that pattern. Its default answer is do less, but make it true. The first command it runs is always an audit, and the first output is always a report — not new files.

Maturity levels, not one-size-fits-all

The skill refuses to generate a full documentation tree by default. Instead, you pick a maturity level that fits the repository’s actual surface area:

Figure 1. Documentation maturity ladder — narrower levels are the default.

minimal — just the high-value root files. Good for new or small repositories that only need a trustworthy entry point.
standard — add folder docs at important boundaries (packages, services, subsystems) and a CONCEPTS.md glossary. This is the default working target.
full — recursive per-folder docs, file headers, and docstrings. An explicit opt-in, because over-documenting is its own drift problem.

Audit first, write later

The most distinctive move is that every workflow starts with audit-docs. It scans the repository, scores findings against a published checklist, and reports PASS / WARN / FAIL / SKIP for each item before touching a file. Only then does it offer to fix — and the first fixes are always evidence-based: broken links, commands that no longer work, layout references that moved.

Figure 2. The audit-first loop. New files are a last resort, not a first move.

Walkthrough: a service repo in three turns

A plausible transcript. Assume a backend service repo with a thin README, a couple of Go packages, and no AGENTS.md file.

Turn 1 — audit only

audit-docs --maturity standard

The skill reports: root README exists but is missing a project summary and build-test section (WARN); no AGENTS.md (FAIL); CONCEPTS.md absent (WARN); two links in the README point at renamed files (FAIL); three public packages have no doc-comments on their exported types (WARN at standard, FAIL at full). No files written.

Turn 2 — fix evidence first

You review the report and agree. You ask for the evidence fixes — broken links, stale build commands — and the AGENTS.md + CONCEPTS.md baselines at standard maturity:

normalize-docs --maturity standard --project-type service

The skill writes only what the audit flagged: repairs two README links, creates AGENTS.md and CONCEPTS.md with the service template, and leaves bootstrap markers visible on generated sections so the next reviewer knows what still needs human input. No per-folder README sprawl.

Turn 3 — add docstrings where it matters

add-docstrings internal/api/

The skill delegates Go format choices to the go-docstrings skill (also in the software-design bundle), adds declaration-adjacent comments on exported types and functions, and reports which symbols were skipped and why — test helpers, generated code, internal-only types.

What ends up on disk

After the three turns, the repository has a small, honest set of documentation files arranged around real boundaries:

Figure 3. Typical layout after a standard-maturity normalize pass. No folder-per-folder README farm.

Why this is useful context for AI agents

Agents that read a repository cold tend to re-derive context from file paths and names. That works for small projects and fails on anything with a non-obvious domain vocabulary. Three artifacts this skill produces change that dynamic:

AGENTS.md tells an AI reader the house rules — preferred commands, test runners, things to avoid — without consuming human-facing README real estate. Claude Code and Codex both honor it.
CONCEPTS.md grounds domain terms in single-paragraph definitions with cross-references. It measurably reduces the chance an agent invents a plausible-but-wrong meaning for a term like tenant, quota, or run.
Bootstrap markers visible in generated sections keep agents honest: they can see at a glance which paragraphs are template residue and which have been refined by a human.

Safety rails worth noticing

Never deletes or rewrites accurate content just to fit a template.
Never invents APIs, workflows, or invariants — only documents what the code already supports.
Refuses to run tree-wide header or docstring generation on large repos without first reporting scope and exclusions.
Skips generated, vendored, minified, and fixture content by default.
Treats broad write operations as reversible batches and reports exactly what changed.

Where to go next

Install the software-design bundle and run audit-docs --maturity standard on a repository you already care about. Read the report before you approve any fix. If you want the broader case for skill-based agent augmentation, see why use a skills marketplace. If you are new to skills entirely, start with what are agent skills.