doc-lint

Doc-Lint Skill

Purpose

This skill IS:

• Markdown validator: Checks MD040 (language tags), heading levels, link validity
• Cross-reference checker: Validates links between documents resolve
• JSON structure validator: Checks for duplicate keys, valid structure
• Quality reporter: Produces actionable findings with file:line references

This skill IS NOT:

• Auto-fixer: Reports issues, does not fix them
• Content quality auditor: Checks syntax, not content quality (that's context-audit)
• Full linter: Focused subset of checks relevant to context ecosystems

Validation Categories

1. Markdown Quality

| Check | Severity | Description | | --------------------- | -------- | --------------------------------------- | | MD040 | LOW | Fenced code blocks without language tag | | Heading jumps | LOW | h1 to h3 without h2 | | Broken internal links | MEDIUM | Links to non-existent files | | Missing frontmatter | MEDIUM | SKILL.md or AGENT.md without frontmatter | | Trailing whitespace | LOW | Lines ending with spaces |

2. Cross-Reference Validation

| Check | Severity | Description | | ---------------------- | -------- | -------------------------------------------- | | Broken file links | HIGH | Markdown links to files that don't exist | | Broken section anchors | MEDIUM | Links to headings that don't exist in target | | Orphaned documents | LOW | Files not referenced by any other document |

3. JSON Structure Validation

| Check | Severity | Description | | ------------------- | -------- | -------------------------------- | | Duplicate keys | HIGH | Same key appears twice in object | | Duplicate IDs | HIGH | Same ID in array of objects | | Trailing commas | MEDIUM | Invalid JSON syntax | | Malformed structure | HIGH | Parse errors |

Invocation

Inline (FIXED END)

Runs automatically as part of scenario FIXED END phases.

Direct

@doc-lint {file-or-directory}
@doc-lint .claude/skills/
@doc-lint docs/context/

Context-Aware Filtering

Skip files that should not be validated:

| Location | Handling | | ----------------------------- | ------------------ | | docs/_<name>/ (any underscore-prefixed top-level folder) | SKIP entirely — opt-out convention | | _archive/ | SKIP entirely | | _inbox/ | SKIP entirely | | _planned/ | Relaxed validation | | .claude/quality/sessions/*/ | SKIP (historical) | | Inside example blocks | Relaxed validation | | Intentionally invalid | SKIP if marked |

**The _* rule is the prefix, not a fixed list.** A user-created docs/_drafts/ or docs/_vendor-evals/ is skipped just like the framework folders. See docs/_bcos-framework/guides/folder-conventions.md.

Content markers that skip validation:

• // Invalid: - Intentional bad example
• # Bad example - Intentional bad example
• HISTORICAL: - Audit documentation
• ... in code - Partial snippet

Output Schema

{
  "mode": "doc_lint",
  "timestamp": "ISO-8601",
  "scope": {
    "files": ["list of files checked"],
    "skipped": ["list of files skipped with reason"]
  },
  "summary": {
    "high": 0,
    "medium": 0,
    "low": 0,
    "total": 0
  },
  "findings": [
    {
      "id": "LINT-001",
      "category": "markdown_quality | cross_reference | json_structure",
      "severity": "HIGH | MEDIUM | LOW",
      "location": "file:line",
      "issue": "Description of the issue",
      "suggestedFix": "Action to take"
    }
  ],
  "contextFiltered": [
    {
      "location": "file:line",
      "reason": "historical_session | archived | intentional_example"
    }
  ]
}

Workflow

Step 1: Discover Files

# For directory input
Glob: {directory}/**/*.md
Glob: {directory}/**/*.json

Step 2: Apply Pre-Filter

Skip archived files, historical sessions, and intentionally invalid content.

Step 3: Validate Each File

For each file:

• If .md: Run markdown quality checks and cross-reference validation
• If .json: Run JSON structure validation

Step 4: Generate Report

Aggregate findings, apply context filtering, output report with file:line references.

Integration with Scenarios

DOCUMENTATION Scenario FIXED END

Px_001: Run markdown quality check    -> doc-lint (markdown category)
Px_002: Run example code validation   -> doc-lint (cross_reference category)

AGENTING Scenario FIXED END

Px_001: Run JSON structure validation -> doc-lint (json_structure category)
Px_002: Run markdown quality check    -> doc-lint (markdown category)

Key Principles

1. Detection only - Report issues, don't auto-fix
2. Context-aware - Skip historical/archived files
3. Actionable - Every finding has location and suggested fix
4. Low noise - Filter false positives before reporting

Related Documents

• docs/_bcos-framework/methodology/document-standards.md - The standards this skill validates against (required fields, valid types, valid statuses)
• .claude/skills/context-audit/SKILL.md - For content quality auditing
• .claude/skills/clear-planner/references/scenario-phases.md - FIXED END integration