Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

docs-alignment

/docs-alignment

Weryfikuje i dostosowuje cały korpus dokumentacji do kodu: zepsute linki, struktura Diataxis, front-matter, diagramy Mermaid, brytyjska pisownia i generowanie nawigacji, opcjonalnie rojem agentów.

Repozytorium
agentbox ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
15
Skrypty
9
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

Co sprawdzić przed instalacją
  • 9 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: 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

Co robi i kiedy

Weryfikuje i dostosowuje cały korpus dokumentacji do kodu: zepsute linki, struktura Diataxis, front-matter, diagramy Mermaid, brytyjska pisownia i generowanie nawigacji, opcjonalnie rojem agentów.

Oryginalny opis (EN)

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).

Jak działa

  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
Sekcje z nagłówków SKILL.md, w oryginale · 128 linii, 674 słów
Podgląd SKILL.md
---
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.
Pliki w paczce (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

Wersje

W bazie nie ma innych skilli o nazwie docs-alignment.

Migawka bazy z 13.11.2026 · wersja paczki c5903ca6f1f0 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100mermaid-link
    Zamienia diagramy Mermaid w klikalne linki podglądu (mmd.dyu.sh), co oszczędza kopiowanie kodu z rozmowy.
  • 86write-doc
    Tworzy lub aktualizuje stronę dokumentacji w katalogu docs według typu Diataxis, z poprawnym nagłówkiem i jednozdaniowym podsumowaniem.
  • 100docs-creator
    Tworzy i poprawia pliki dokumentacji z uwzględnieniem modelu Diataxis, spójnych nazw i właściwego miejsca w repozytorium, w tym README i tutoriale.
  • 90mermaid-diagram-generator
    Tworzy diagramy Mermaid dla kodu Arduino: strukturę programu, maszyny stanów, diagramy czasowe, architekturę zadań i opisy przepływów.
  • 100docs-creator
    Tworzy lub poprawia pliki dokumentacji zgodnie z podziałem Diataxis i jednolitym nazewnictwem, także README i samouczki.
  • 86mermaid
    Renderuje diagram Mermaid w terminalu za pomocą termaid, także z pliku lub dokumentu Markdown, i sprawdza jego poprawność.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.