Auto Doc Links

---
name: auto-doc-links
description: Validate and fix internal markdown links across documentation
type: skill
category: documentation
agents: [doc-maintainer]
knowledge: []
mcp_servers: [filesystem]
axioms: [A1, A5]
---

# Auto-Doc Links

## Purpose

Validate all internal markdown links in `docs/` directory using the reorganization engine's validate mode. Wraps `scripts/tools/reorganize.py --validate` command. Reports broken links and optionally fixes them automatically.

## When to Use

- After any documentation reorganization
- After file moves or renames
- After restructuring documentation directories
- As part of CI/CD documentation validation
- When encountering 404 errors in documentation

## Prerequisites

- Python 3.10+ installed
- `lib/tools/reorganizer.py` available with MarkdownResolver
- Access to `docs/` directory tree

## Process

1. **Scan documentation**: Recursively scan `docs/` directory for markdown files
2. **Extract links**: Parse all markdown links (`[text](path)`) from files using `lib/tools/reorganizer.py` MarkdownResolver
3. **Validate targets**: Check if linked files exist at specified paths
4. **Report issues**: Generate report of broken links with file locations and line numbers
5. **Fix links** (optional): Automatically update broken links if fixable (e.g., case corrections, path updates)
6. **Output results**: Display validation report with broken link details

## Example Usage

```bash
# Validate all links in docs/
python scripts/tools/reorganize.py --validate --scan-root docs/ --resolvers markdown

# Validate and auto-fix links
python scripts/tools/reorganize.py --validate --scan-root docs/ --resolvers markdown

# Validate specific directory
python scripts/tools/reorganize.py --validate --scan-root docs/guides/ --resolvers markdown
```

## Output

- Validation report listing all broken links
- File paths and line numbers where broken links occur
- Suggested fixes for common issues (case sensitivity, path corrections)
- Updated markdown files with fixed links (if auto-fix enabled)

## Best Practices

- Run link validation after any documentation reorganization or file moves
- Include link validation in CI/CD pipelines to catch broken links early
- Fix broken links before merging documentation changes
- Use `--dry-run` to audit before applying automatic fixes