Skip to content
Skills Library
Programming · Review & audit

docs-alignment

/docs-alignment

Validate and align a whole documentation corpus against the codebase — broken-link/orphan detection, Diataxis structure, front-matter metadata, Mermaid diagram compliance (ASCII→Mermaid), UK-English spelling, and navigation/index generation — optionally via an agent swarm. Use when auditing or modernising a full /docs corpus, enforcing Diataxis, fixing link coverage, or preparing docs for a release. Not for writing a single README (write markdown directly), LaTeX reports (report-builder), or standalone diagrams (mermaid-diagrams).

Repository
agentbox ↗
Licence
AGPL-3.0
Last repository change
27.10.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
15
Scripts
9
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What to check before installing
  • 9 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/detect-ascii.sh, scripts/generate-reports.sh, scripts/validate-all.sh, scripts/validate-coverage.sh, scripts/validate-frontmatter.sh, scripts/validate-links.sh, scripts/validate-mermaid.sh, scripts/validate-spelling.sh, scripts/validate-structure.sh

What it does and when to use it

Validate and align a whole documentation corpus against the codebase — broken-link/orphan detection, Diataxis structure, front-matter metadata, Mermaid diagram compliance (ASCII→Mermaid), UK-English spelling, and navigation/index generation — optionally via an agent swarm. Use when auditing or modernising a full /docs corpus, enforcing Diataxis, fixing link coverage, or preparing docs for a release. Not for writing a single README (write markdown directly), LaTeX reports (report-builder), or standalone diagrams (mermaid-diagrams).

Original author description

Validate and align a whole documentation corpus against the codebase — broken-link/orphan detection, Diataxis structure, front-matter metadata, Mermaid diagram compliance (ASCII→Mermaid), UK-English spelling, and navigation/index generation — optionally via an agent swarm. Use when auditing or modernising a full /docs corpus, enforcing Diataxis, fixing link coverage, or preparing docs for a release. Not for writing a single README (write markdown directly), LaTeX reports (report-builder), or standalone diagrams (mermaid-diagrams).

How it works

  1. When to use / not use
  2. Sequencing with prose-sanitiser
  3. Prerequisites
  4. Quick start
  5. A diagrams-as-code corpus is audited by its own gate
  6. Swarm path (large corpora)
  7. References
  8. Related skills
Original SKILL.md headings · 128 lines, 674 words
SKILL.md preview
---
name: docs-alignment
description: "Validate and align a whole documentation corpus against the codebase — broken-link/orphan detection, Diataxis structure, front-matter metadata, Mermaid diagram compliance (ASCII→Mermaid), UK-English spelling, and navigation/index generation — optionally via an agent swarm. Use when auditing or modernising a full /docs corpus, enforcing Diataxis, fixing link coverage, or preparing docs for a release. Not for writing a single README (write markdown directly), LaTeX reports (report-builder), or standalone diagrams (mermaid-diagrams)."
---

# Documentation Alignment Skill

Modernise and validate a project's documentation corpus so it stays consistent
with the codebase: links, front matter, diagrams, spelling, Diataxis structure,
navigation, and CI. Runs as standalone scripts or as a 15-agent swarm for
large corpora.

## When to use / not use

Use for whole-corpus work: auditing, modernising, aligning docs to code, or
release/onboarding prep.

Skip in favour of a more direct path when:
- Writing a single markdown file or README — just write markdown.
- Generating a LaTeX report with charts/bibliography — use `report-builder`.
- Creating a diagram from text — use `mermaid-diagrams`.
- Generating API docs from code — use code-level doc tools directly.
- General code quality/testing workflows — use `build-with-quality`.

## Sequencing with prose-sanitiser

`validate-spelling.sh` is a structural, corpus-wide check: file by file, pass or fail,
against a UK-English wordlist. It does not catch AI writing tells such as em-dash
density, hedge padding, or generic phrasing. For a full modernisation, run
`docs-alignment` first to fix links, front matter, diagrams, and spelling, then run
`prose-sanitiser` per file for the prose-quality pass. Skipping the second step leaves
AI-tell removal undone.

## Prerequisites

- `docs-alignment` and sibling `docs-*` binaries (Rust, built from
  `services/skill-tools`) on `PATH`; Python 3.10+ (only for the
  still-Python `archive_working_docs.py`/`scan_stubs.py` steps); Node.js
  18+ (Mermaid validation); Git.
- A git repo with docs in `/docs` and a codebase to validate against.
- Claude Code Task tool (only for swarm orchestration).

## Quick start

Binary path — run the whole alignment in one command:

```bash
npm install -g @mermaid-js/mermaid-cli

docs-alignment \
  --project-root /path/to/project \
  --docs-dir ./docs \
  --codebase-dir ./src \
  --output-dir ./docs/working
```

Individual validators (each supports `--json`):

```bash
./scripts/validate-all.sh          # runs every check below
./scripts/validate-links.sh        # link integrity + orphans
./scripts/validate-frontmatter.sh  # YAML metadata
./scripts/validate-mermaid.sh      # diagram syntax / Git compliance
./scripts/detect-ascii.sh          # ASCII art to convert
./scripts/validate-spelling.sh     # UK English
./scripts/validate-structure.sh    # naming / layout
./scripts/generate-reports.sh      # quality scorecard
```

Full flag set for a strict pass:

```bash
docs-alignment --project-root . --docs-dir ./docs \
  --codebase-dir ./src --output-dir ./docs/working \
  --full-validation --git-compliant --uk-english --diataxis-strict
```

## A diagrams-as-code corpus is audited by its own gate

`validate-mermaid.sh` checks loose diagrams for syntax. A repository whose `docs/diagrams/`
follows the topic contract (frontmatter with `id`/`area`/`sources`/`verified_commit`, two
narratives, register markers — see `diagrams-as-code`) has a stronger check available and
this audit must run it, because a diagram that parses can still cite a line that moved:

```bash
node ../diagrams-as-code/scripts/diagram-index-gen.cjs docs/diagrams \
  --check --cite-check --worktree-citations --report ./docs/working/diagrams-report.json
```

Every citation warning in the report is an alignment finding (record → code drift) and is
listed in the scorecard beside broken links; a topic whose `sources:` changed since its
`verified_commit` is stale even with zero warnings. Fixing is the corpus owner's job
through that skill's verification recipe — this audit reports, it does not re-stamp.

## Swarm path (large corpora)

For a comprehensive modernisation, deploy the 15-agent swarm via the Task tool:

```bash
claude-code << 'EOF'
Task("Documentation Alignment Swarm", `
  Execute documentation alignment using a 15-agent swarm.
  Project: /home/devuser/workspace/project
  Docs: ./docs   Output: ./docs/working
  Waves: inventory → IA design → modernisation → consolidation → QA/CI.
`, "system-architect")
EOF
```

The five-wave agent roster, per-phase execution detail, topology config, and
memory-coordination keys are in [`references/swarm.md`](references/swarm.md).

## References

- [`references/swarm.md`](references/swarm.md) — 15-agent composition, five-wave
  execution phases, topology, memory coordination.
- [`references/standards.md`](references/standards.md) — full validation-standards
  catalog (links, diagrams, front matter, spelling, content, structure,
  coverage), the A–F quality-scoring rubric, all output deliverables, and
  success-metric targets. Treat thresholds as tunable per project.
- [`docs/ADVANCED.md`](docs/ADVANCED.md) — custom topologies, validation-rule
  config, CI/CD (GitHub Actions / GitLab), custom report templates, large-codebase
  performance tuning.
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — install/validation/permission/
  performance/swarm failure modes and fixes.

## Related skills

- `skill-tuning` measures whether a skill's wording raises task success; this skill only checks corpus consistency.
- `diagrams-as-code` owns the citation-verified diagram corpus and its generator; this audit runs that generator as one of its gates and reports its warnings, never edits the corpus.
- `explainer` ships a verified corpus as the Diagrams door of a repository explainer; run this audit and the corpus gate first.
Files in this package (15)
  • README.md 2 KB
  • SKILL.md 6 KB
  • docs/ADVANCED.md 5 KB
  • docs/TROUBLESHOOTING.md 4 KB
  • references/standards.md 5 KB
  • references/swarm.md 4 KB
  • scripts/detect-ascii.sh 2 KB
  • scripts/generate-reports.sh 4 KB
  • scripts/validate-all.sh 2 KB
  • scripts/validate-coverage.sh 2 KB
  • scripts/validate-frontmatter.sh 2 KB
  • scripts/validate-links.sh 3 KB
  • scripts/validate-mermaid.sh 2 KB
  • scripts/validate-spelling.sh 2 KB
  • scripts/validate-structure.sh 3 KB

Versions

The database has no other skills named docs-alignment.

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

  • 100mermaid-link
    把 Mermaid 图表变成可点击的预览链接(mmd.dyu.sh),省去从对话里复制粘贴代码。 Turn Mermaid diagrams into clickable preview links — no copy-paste. 触发: 当你在回复中输出了 Mermaid 图表 / ```mermaid 代码块时,主动在其后附上预览链接; 或用户说 "打开这个图", "预览这个图", "mermaid 链接", "在浏览器里看这个图", "open this diagram", "mermaid link", "preview mermaid"。
  • 86write-doc
    Creates or updates a documentation page in docs/ using the right Diataxis type, valid front matter and a one-sentence summary. Use whenever adding, changing, moving or deleting a doc.
  • 100docs-creator
    Create or improve documentation files with Diataxis-aware placement and consistent naming. Use when the user wants to create any new documentation, improve existing docs, write a README, or restructure documentation. Also use when asked to "write docs", "improve this doc", "add…
  • 90mermaid-diagram-generator
    Use when users need Mermaid diagrams for Arduino code structure, state machines, timing diagrams, task architecture, or workflow documentation.
  • 100docs-creator
    Create or improve documentation files with Diataxis-aware placement and consistent naming. Use when the user wants to create any new documentation, improve existing docs, write a README, or restructure documentation. Also use when asked to "write docs", "improve this doc", "add…
  • 86mermaid
    Render a Mermaid diagram in the terminal with termaid. Use when the user asks to draw, render, preview or check a Mermaid diagram, a file containing one, or the diagrams in a Markdown document, PR description or README.

Feedback and reports

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