Skip to content
Skills Library
Programming · Review & audit

validate-docs

/validate-docs

Validate and update the public user docs in `site/` (Mintlify) against the code — map every user-facing change since a ref to the pages it touches, fix the pages, then run the docs test, the Mintlify build and link checks and the anonymization scan. Also adds a release's changelog entry. Use when the user says "validate docs", "check the user docs", "are the docs up to date", "update the docs for this change", "/validate-docs", and from the `release` skill.

Repository
factory ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

95/ 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.
Content30 / 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
1
Deprecation

No signals detected. Repository changed on 13.11.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

Validate and update the public user docs in `site/` (Mintlify) against the code — map every user-facing change since a ref to the pages it touches, fix the pages, then run the docs test, the Mintlify build and link checks and the anonymization scan. Also adds a release's changelog entry. Use when the user says "validate docs", "check the user docs", "are the docs up to date", "update the docs for this change", "/validate-docs", and from the `release` skill.

Triggers from the description

s changelog entry. Use when the user sayscheck the user docsare the docs up to dateupdate the docs for this change
Original author description

Validate and update the public user docs in `site/` (Mintlify) against the code — map every user-facing change since a ref to the pages it touches, fix the pages, then run the docs test, the Mintlify build and link checks and the anonymization scan. Also adds a release's changelog entry. Use when the user says "validate docs", "check the user docs", "are the docs up to date", "update the docs for this change", "/validate-docs", and from the `release` skill.

How it works

  1. 1. Find what changed for users
  2. 2. Run the checks
  3. 3. Release mode: the changelog entry
  4. 4. Ship
  5. Reporting back
Original SKILL.md headings · 84 lines, 641 words
SKILL.md preview
---
name: validate-docs
description: Validate and update the public user docs in `site/` (Mintlify) against the code — map every user-facing change since a ref to the pages it touches, fix the pages, then run the docs test, the Mintlify build and link checks and the anonymization scan. Also adds a release's changelog entry. Use when the user says "validate docs", "check the user docs", "are the docs up to date", "update the docs for this change", "/validate-docs", and from the `release` skill.
---

# Validate the user docs

`site/` is the user documentation, published by Mintlify from `main` on every merge
(<https://docs.bellows.cloud>). `docs/` is the maintainer index and belongs to the
`doc-maintenance` skill, not this one. The code is the source of truth: a page that disagrees with
it is wrong, whatever the page says.

Input: a ref to compare against (default: the last tag, `git describe --tags --abbrev=0`), and in
release mode the tag and its notes file. Work in a worktree on a branch; never commit to `main`.

## 1. Find what changed for users

```bash
REF=${REF:-$(git describe --tags --abbrev=0)}
git diff --stat "$REF"..HEAD -- web/src cli/src server/src/mcp server/src/workspace server/src/routes \
  core/src driver/src/config.ts server/src/config.ts charts docker/skills .env.example
```

Map each change to the pages that state it. Read the diff, not only the stat: a renamed label or a
new limit is one line.

| Change in | Check these pages |
| --- | --- |
| `web/src` labels, buttons, statuses, settings screens | `overview/quickstart`, `guides/run-tasks`, `guides/task-lifecycle`, the guide for that screen; screenshots in `site/images` |
| `cli/src/usage.ts`, `cli/src/config.ts` | `cli/commands`, `cli/install` |
| `server/src/mcp/tools` | `mcp/tools`, `mcp/connect`, `use-cases/drive-from-claude-code` |
| `server/src/workspace/bellows*.ts` | `reference/bellows-yaml`, `guides/configure-repo`, `guides/gates`, `guides/services`, `guides/policy-and-reviewers` |
| Limits (`MAX_*`, `*_LIMIT`, `docs/limits.md`) | `reference/limits` and the guide that quotes the value |
| Failure kinds, job states | `guides/task-lifecycle`, `reference/faq` |
| Executors, skills, connections, env/secrets, attachments, tokens | the matching `guides/*` page, `cli/install` for tokens |
| `server/src/config.ts`, `driver/src/config.ts`, `.env.example`, `charts/` | `self-host/configuration`, `self-host/kubernetes`, `self-host/docker-compose` |
| GitHub App / Jira app setup, auth modes, runner isolation | `self-host/github-app`, `self-host/jira-app`, `self-host/security` |

Update every page the change makes wrong, in the page's own style (see `site/README.md`). A new
user-facing feature with no page gets a section in the closest guide; a new page also needs its
entry in `site/docs.json` → `navigation`. Features behind a flag that is off by default
(`BATCHES_ENABLED`) stay out, apart from the one note each page already has.

A screen shown in a screenshot that changed visibly gets a fresh capture at the same path and size,
light theme, fictional data only (`acme`, `acme/notes-api`, `alex-doe`, `sam-roe`). If you cannot
capture it, list it in the report rather than leave a stale image silently.

## 2. Run the checks

```bash
npm run build -w core                            # server tests import core/dist
npx vitest run server/test/site-docs.test.ts     # examples parse; CLI, MCP and nav match the code
cd site && npx mint@latest validate && npx mint@latest broken-links && cd ..
```

The test fails when a full `.bellows.yaml` example does not parse (fragments are titled
`.bellows.yaml (excerpt)`), when the documented CLI commands or MCP tools differ from the code, or
when `docs.json` and the pages disagree. Fix the docs, never the test, unless the test is wrong.

Then the anonymization scan — the repo is public:

```bash
grep -rnE "[A-Z][A-Z0-9]+-[0-9]+" site --include='*.mdx' | grep -v PROJ-   # real ticket keys
grep -rniE "https?://[a-z0-9.-]+\.[a-z]{2,}" site --include='*.mdx' \
  | grep -vE "bellows\.cloud|example\.com|github\.com/Bellows-AI|mintlify|localhost|127\.0\.0\.1"
```

Every hit is either fictional (`acme`, `PROJ-123`, `example.com`) or a public Bellows URL. Look at
every new or replaced image yourself.

## 3. Release mode: the changelog entry

Run after the GitHub release exists. Add one `<Update label="vX.Y.Z" description="YYYY-MM-DD">`
block at the top of `site/reference/changelog.mdx`, newest first, from the release notes: user-facing
changes only, in plain words, grouped **New**, **Improved**, **Fixed**, each linking its guide. Drop
internal refactors, CI and test-only items, and every issue number, task id or name. Upgrade notes
for operators stay in the GitHub release.

## 4. Ship

One PR titled `docs(site): …` with what changed and why, the check results, and any screenshot
you could not refresh. Merging publishes the site.

## Reporting back

Pages changed and the code change behind each, checks run and their result, images refreshed or
still stale, and anything you chose not to document with the reason.

Versions

The database has no other skills named validate-docs.

Database snapshot: 13.11.2026 · package version f6a84db21438 (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-docs
    Update public documentation in docs/public/ when features or tools change. Triggers on "/update-docs", "update docs", "update documentation".
  • 100docs-incremental-update
    Incrementally update Mintlify documentation (.mdx) from Python source changes only. Use when: (1) Python files referenced in doc_code_map frontmatter have changed, (2) a PR touches Python modules documented in docs/mintlify/key_modules/ or docs/mintlify/mcp/, (3) the user asks…
  • 100mintlify
    Build and maintain documentation sites with Mintlify. Use when creating docs pages, configuring navigation, adding components, or setting up API references.
  • 100docs-writing
    Write, rewrite, audit, or review a page of the Onyx customer docs (the Mintlify site in `documentation/`). Use for new pages, release refreshes, screenshot updates, connector and provider guides, API guides, docs edits in a feature PR, and docs quality reviews. Covers audience,…
  • 100mintlify
    Mintlify is a hosted documentation platform that turns MDX files and a docs.json config in a Git repository into a developer docs site with built-in search, an API playground generated from OpenAPI, and an AI assistant. Use this skill to create a documentation site, set up the…
  • 100nacl-tl-docs
    Update NaCl TL documentation after approved implementation and review evidence. Use when synchronizing docs, updating README or API docs, writing a changelog entry, finalizing task docs, or when the user says `/nacl-tl-docs`.

Feedback and reports

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