Agent Skills
› NeverSight/learn-skills.dev
› documentation-cleanup
documentation-cleanup
GitHub验证并修复SolTechnology.Core项目文档完整性，包括模块与文档一致性、索引、表格及Mermaid图表语法、ADR结构、链接有效性及列表格式。
Trigger Scenarios
需要检查或修复docs目录下的Markdown文档质量
验证模块文档与代码库的对应关系
清理和标准化架构决策记录(ADR)及内部链接
Install
npx skills add NeverSight/learn-skills.dev --skill documentation-cleanup -g -y
SKILL.md
Frontmatter
{
"name": "documentation-cleanup",
"description": "Validate and fix documentation integrity in SolTechnology.Core — module\/doc parity, indexes, tables, Mermaid diagrams, links, ADR formatting, numbered lists."
}
Documentation Cleanup
Validate and fix documentation integrity across the docs/ folder.
Process overview
- Identify files to validate
- Check module ↔ doc parity
- Check indexes
- Validate tables and Mermaid diagrams
- Validate ADR structure
- Check links and formatting
- Fix numbered lists
Documentation references
- README.md — top-level module index
- docs/ — per-module docs and reviews
- docs/adr/ — Architecture Decision Records
Step-by-step procedure
1. Identify files
Collect every *.md under docs/ and the workspace root.
2. Module ↔ Doc Parity
For each folder src/SolTechnology.Core.<Module>/:
- A documentation file exists under docs/ (the file name is set by
README.md — e.g.
Story→docs/Story.md,MessageBus→docs/Bus.md). - The module is listed in the README table with a NuGet badge.
- A review template exists under docs/reviews/ when the module is publicly consumed; missing review templates are reported as gaps, not failures.
3. Check Indexes
For files that contain an index (README, docs/Story.md, etc.):
- Every index entry has a matching section in the document.
- Every top-level section is listed in the index.
- Index links use angle brackets for any path containing spaces:
[Text](<path/file.md>). - Index hierarchy matches the document hierarchy.
4. Validate Tables and Mermaid Diagrams
For each table:
- Header row present, separator row matches column count, every data row matches column count.
For each Mermaid block:
- Syntax parses (no stray characters).
classDefdeclared before first use.- Node names with spaces use
<br>line breaks:Node[Name<br>With<br>Spaces].
5. Validate ADR Structure
For every file under docs/adr/:
- File name matches
NNN-kebab-title.md, numbering monotonic with no gaps. - Required sections present: Status, Context, Decision, Consequences.
- Recommended sections noted as gaps when missing: Alternatives Considered, Stakeholders.
- ADR is linked from at least one other doc or from
CLAUDE.md/README.md.
6. Check Links and Formatting
- Paths with spaces use angle brackets:
[Text](<path/file.md>). - Relative paths resolve from the file's location.
- Linked files exist on disk.
- Module docs use relative links into
src/SolTechnology.Core.*only when the file is stable (interfaces,ModuleInstaller.cs, public entrypoints).
7. Fix Numbered Lists
- Use
1.for every item (markdown auto-numbers). - Nested lists indented by 4 spaces.
- Hierarchy consistent within a document.
Ignore backtick / inline-code formatting issues unless they break rendering.
Output format
Documentation Cleanup Report
Files Validated
Issues Found
Module ↔ Doc Parity
Index Issues
Table / Mermaid Issues
ADR Issues
Link Issues
Numbered List Issues
Fixes Applied
Summary
Files validated:
Version History
- e0220ca Current 2026-07-05 23:31
