mags-docs-validate
npx machina-cli add skill doancan/mags/mags-docs-validate --openclawMAGS Docs Validate
Run validation checks on all project documents.
Usage
/mags-docs-validate
Steps
-
Ask the user: "Standard validation or deep validation?"
- Standard — checks frontmatter, required sections, cross-references, freshness
- Deep — all standard checks plus: version conflict detection, memory-doc consistency, ADR structure validation, and module completeness checks
If deep: call
mags_validate_docswithdeep: true. If standard (or no preference): callmags_validate_docswith default parameters. -
Display results grouped by severity:
== Document Validation == Errors (must fix): - docs/architecture/overview.md: Missing required section "Tech Stack" - docs/rules/backend.md: Broken internal link to ../api/auth.md Warnings (should fix): - docs/modules/auth.md: No code examples found - docs/changelog/changes.md: Last updated over 30 days ago Passed: <N>/<total> documents are healthy -
If there are errors, ask: "Would you like me to fix the errors?"
-
If yes, read each problematic doc with
mags_get_doc, fix the issues, and callmags_update_doc.
Related commands:
| Command | Description |
|---|---|
/mags-docs | List all project documents |
/mags-docs-search <query> | Search across all documents |
Source
git clone https://github.com/doancan/mags/blob/main/skills/mags-docs-validate/SKILL.mdView on GitHub Overview
MAGS Docs Validate runs automated checks on your project documents to ensure frontmatter integrity, required sections, and accurate cross-references. It offers a standard validation pass or a deeper sweep that checks for conflicts, ADR structure, and module completeness.
How This Skill Works
Trigger the command /mags-docs-validate to start. Choose standard (default) or deep validation; the tool calls mags_validate_docs with appropriate parameters and returns results grouped by severity. If issues are found, you can inspect and fix them using mags_get_doc and mags_update_doc.
When to Use It
- Run a quick health check after minor docs edits (standard validation).
- Perform a deep validation to detect version conflicts, memory-doc consistency, ADR structure, and module completeness.
- Identify missing required sections or broken internal links and re-run validation after fixes.
- Audit cross-references and freshness before a public release.
- Post-fix workflow: review errors, then fetch with mags_get_doc, apply fixes, and update with mags_update_doc.
Quick Start
- Step 1: Run /mags-docs-validate
- Step 2: If prompted, choose Standard or Deep validation (deep: true).
- Step 3: Review the grouped results and, if needed, fix issues using mags_get_doc and mags_update_doc.
Best Practices
- Run standard validation first to surface obvious issues quickly.
- Use deep validation for critical docs to catch deeper consistency problems.
- Validate after major changes or before releases to ensure health.
- Regularly check cross-references and freshness (e.g., last updated dates).
- Use mags_get_doc and mags_update_doc to fetch, fix, and publish corrections.
Example Use Cases
- Validate docs after adding a new feature to catch missing Tech Stack or broken links.
- Run standard validation to surface missing sections in docs/rules/backend.md.
- Run deep validation to catch ADR structure errors and version conflicts.
- Audit changelog freshness to ensure recent updates are reflected.
- After fixing issues, fetch the doc with mags_get_doc, apply changes, and update with mags_update_doc.
