docs-single-source
/docs-single-source
Link docs to the single source of truth instead of restating it. Use when writing or restructuring docs, editing a README/CLAUDE.md, or copying a list that lives in code.
- Author
- laurigates ↗
- Repository
- claude-plugins ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Link docs to the single source of truth instead of restating it. Use when writing or restructuring docs, editing a README/CLAUDE.md, or copying a list that lives in code.
Original author description
Link docs to the single source of truth instead of restating it. Use when writing or restructuring docs, editing a README/CLAUDE.md, or copying a list that lives in code.
How it works
- The principle
- When this bites
- When duplication is acceptable
- Litmus test before adding docs
- Rationale
- Related
SKILL.md preview
---
name: docs-single-source
description: Link docs to the single source of truth instead of restating it. Use when writing or restructuring docs, editing a README/CLAUDE.md, or copying a list that lives in code.
allowed-tools: Read, Grep, Glob, Edit, TodoWrite
created: 2026-08-19
modified: 2026-08-19
reviewed: 2026-08-19
---
# Documentation: Link, Don't Duplicate
Write documentation that **points to the single source of truth** instead of
restating it. A fact copied into a second place is a fact that will drift — the
copy goes stale the moment the original changes, and nothing flags it. This is
DRY applied to prose.
## The principle
- **Link from where the reader starts.** Put a short pointer at the entry point
someone actually lands on (CLAUDE.md, README, a top-level index) that links to
the deep doc. Don't reproduce the deep doc at the entry point.
- **One canonical home per fact.** Each piece of information lives in exactly one
authoritative place; everywhere else references it.
- **A runnable artifact is its own doc.** When a skill, playbook, justfile
recipe, or script both *does* the thing and *explains* it, that artifact is the
documentation. Link to it — do not write a parallel prose copy that has to be
kept in sync by hand.
- **Reference the authoritative source, not a hand-copy.** When you must
enumerate (repos, packages, endpoints, flags), point at the source that's
already maintained — e.g. "the `comfy_registry = true` entries in
`repositories.tf`" — rather than transcribing a list that silently falls out of
date.
## When this bites
| Smell | Why it drifts | Do instead |
|---|---|---|
| A hand-maintained list mirroring config/code | The source changes; the list doesn't | Reference the source ("see the X entries in Y") |
| A command sequence copied into a doc *and* a script | One gets edited, the other rots | Keep it in the script; the doc links to it |
| The same workflow as prose *and* as a skill/playbook | Two copies, two truths | The skill is the doc; link to it |
| A config table duplicated across two READMEs | Updates land in one | One canonical doc; the other links |
| Re-explaining at the entry point what a deeper doc already covers | Entry point and deep doc disagree over time | Short pointer + link |
## When duplication is acceptable
- A one-line *summary* at the entry point (with a link to the full source) is a
signpost, not duplication. Keep it to the gist, not the detail.
- Small, stable facts (a default value cited inline) can be repeated when
restating is clearer than a link — but prefer the link if the fact can change.
## Litmus test before adding docs
Ask: *"Does this fact already live somewhere authoritative?"* If yes, link to it.
If you're about to type a second copy of something that exists elsewhere, stop
and reference the original. The best documentation edit is often a pointer, not a
paragraph.
## Rationale
Duplicated documentation doesn't just waste effort — it actively misleads,
because a stale copy still reads as authoritative. Linking from entry points
keeps docs discoverable without creating mirror copies that diverge. Referencing
the source-of-truth means the docs can't go stale relative to it, because there's
only one truth. This is the prose analogue of DRY (`~/.claude/rules/code-quality.md`) and the
docs-side complement of `~/.claude/rules/local-ci-parity.md` (one definition, consumed in many
places).
## Related
- `blueprint-plugin:blueprint-docs-currency` — the timing sibling: code and
the docs describing it land in the same commit.
- `documentation-plugin:docs-sync` — the mechanical catalog reconciler that
repairs drift after the fact in generated skill/command/agent tables.
- `code-quality-plugin:dry-consolidation` — the code-side analogue (clone
detection and shared-abstraction extraction over source).
Versions
The database has no other skills named docs-single-source.
Database snapshot: 13.11.2026 · package version 68674b925d66 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 85write-the-docs
Write or edit project documentation. Use when writing a README, design doc, or module doc. - 90ns-docs-writer
(NS) Human-facing project docs — README, docs/ guides, runbooks, contributor markdown. Use whenever the user asks for documentation, README updates, how-to guides, or docs/ content — even if they say \"explain how to use\" instead of \"write docs\". Do NOT use for code comments,… - 85docs-hygiene
Use when editing source-of-truth docs or status tables: three sources, Done / In progress / Not started, and live hour formulas. On demand only. - 90tc-docs-write
Use when writing or updating the TcKit documentation site or the README — anything under docs/content/ or README.md. Triggers on requests like "update the docs", "document this in the docs", "write a docs page for X", "the README needs Y", "add a capability page", "fix the home… - 100structuring-documentation
Use when writing, editing, auditing, splitting, or measuring Markdown documentation surfaces — README.md, AGENTS.md, CLAUDE.md, and docs/ siblings. Triggers include "is this doc too long", "split this README", "measure the docs", "where does this documentation belong", "audit… - 100sync-docs-site
Bring the user documentation in docs-site/ up to date with Folio's released features, from CHANGELOG.md, the README and the code. Use when the user asks to update, sync or check the docs site, after a release, or when a feature change should be reflected in the user docs.