Skip to content
Skills Library
Documents & office · Writing

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.

Licence
MIT
Last repository change
24.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

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

  1. The principle
  2. When this bites
  3. When duplication is acceptable
  4. Litmus test before adding docs
  5. Rationale
  6. Related
Original SKILL.md headings · 68 lines, 577 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.