Skip to content
Skills Library
Programming · Automation

docs-as-code

/docs-as-code

Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow.

Repository
AI-SKILLS ↗
Licence
MIT
Last repository change
05.09.2026

Assessment and security

100/ 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.
Content35 / 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 05.09.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

Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow.

Original author description

Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow.

How it works

  1. Method
  2. Boundaries
Original SKILL.md headings · 66 lines, 466 words
SKILL.md preview
---
name: docs-as-code
description: "Treat documentation like code: in the repo, in pull requests, CI-checked, with preview builds. Use when docs drift from reality or the docs workflow is separate from the code workflow."
---

# Docs as code

The reason docs go stale is that they live apart from the code they
describe, changed by different people through a different process.
Docs-as-code closes that gap: documentation lives in the repo, changes
in the same pull request as the code, and CI checks it: so drift
becomes a build failure instead of a discovery months later.

## Method

1. **Keep docs in the repo, beside the code.** Markdown (or
   the docs framework's format) versioned with the source:
   the docs for a feature live next to it and change in the
   same commit. This co-location is the whole idea: the
   documentation and the code share one history, one review,
   one source of truth (see monolith-first's co-location
   instinct, applied to docs).
2. **Change docs in the same PR as the code.** A change that
   alters behavior updates the docs in the same pull request,
   reviewed together (see pull-request-size, code-review):
   the reviewer checks that the docs match the change while
   both are fresh. Separate docs-later tickets are how docs
   fall permanently behind.
3. **Check docs in CI.** Link checking (dead links fail the
   build), spell/style linting (see style-guides), and
   crucially, testing that code examples actually run (see
   api-reference-docs, tutorial-writing): a broken example
   fails CI like a broken test. Automated checks are what
   make "docs match reality" enforceable rather than
   aspirational.
4. **Build previews on every change.** A rendered preview of
   the docs per pull request (the framework deployed to a
   preview URL) lets reviewers see the actual output, not
   the raw markup: catches formatting breaks and reads the
   way users will. Reviewing docs as source is like
   reviewing a rendered UI as HTML.
5. **Generate what should be generated, write what should
   be written.** API reference from the schema (see
   api-reference-docs), CLI help from the parser, config
   options from the code: generated so they never drift;
   conceptual guides, tutorials, and rationale hand-written
   because no generator produces insight. Know which is
   which and wire the generation into the build.
6. **Lower the contribution barrier.** If fixing a typo
   requires learning a bespoke CMS, typos stay; if it is a
   markdown edit in the repo with a preview, anyone fixes
   it (see community-building's contributor ladder). The
   docs-as-code payoff includes that the whole team, not a
   docs silo, keeps docs current.

## Boundaries

- Docs-as-code fits developer-facing and technical docs
  well; end-user documentation with heavy media,
  localization, and non-technical authors may need a CMS
  or hybrid: match the tooling to who writes and reads.
- The workflow's value depends on the CI checks being real
  (tested examples, link checks): docs-in-the-repo without
  the checks is just a different place for stale docs to
  live.
- Generated docs still need curation (see
  api-reference-docs); "generate everything" produces
  complete, correct, and unhelpful reference. The method
  is generate-plus-write, both in the repo.

Versions

The database has no other skills named docs-as-code.

Database snapshot: 13.11.2026 · package version d5d7502f34e4 (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

  • 100update-ui-inventory
    Update the UI component inventory and documentation when components are added or removed. Use when adding new components, after code reviews flag inventory mismatches, or periodically to ensure docs match reality.
  • 100cpp-review
    Review C++ code against Google C++ Style Guide. Use when reviewing C++ code, pull requests, or when asked to check code style compliance.
  • 100docs-maintenance
    Keep documentation from rotting through staleness detection, ownership, doc tests, and deliberate deprecation. Use when docs have drifted from reality or no process keeps them current.
  • 100repo
    Update repository documentation (README.md, docs/, CLAUDE.md) based on session changes by dispatching the up-docs-propagate-repo sub-agent. This skill should be used when the user runs /up-docs:repo.
  • 100docs-review
    Review documentation changes for compliance with the Metabase writing style guide. Use when reviewing pull requests, files, or diffs containing documentation markdown files.
  • 100update-docs
    Update public documentation in docs/public/ when features or tools change. Triggers on "/update-docs", "update docs", "update documentation".

Feedback and reports

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