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).
- Author
- dreamlab-ai ↗
- Repository
- agentbox ↗
- Licence
- AGPL-3.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 15
- Scripts
- 9
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.
- 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
- When to use / not use
- Sequencing with prose-sanitiser
- Prerequisites
- Quick start
- A diagrams-as-code corpus is audited by its own gate
- Swarm path (large corpora)
- References
- Related skills
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.