doc-validate Skill | Agent Skills

doc-validate

Validate AsciiDoc documentation files for technical accuracy, style compliance, and structural correctness.

Parse arguments

$ARGUMENTS contains:

Target: file path, directory, or glob pattern for AsciiDoc files to validate
--context (optional): path to context package for cross-reference validation (defaults to workspace/context-package.json)

Step 1: Discover files

Resolve the target argument to a list of .adoc files:

If a single file: validate that file
If a directory: glob for **/*.adoc
If a glob pattern: expand it

Step 2: Run deterministic validators

Execute the validation script on all discovered files:

python3 "${CLAUDE_SKILL_DIR}/scripts/validate-artifacts.py" "${file1}" "${file2}" ...

This runs:

Vale: prose style compliance
Asciidoctor: compilation check (can the file be built?)
Lychee: link checking (are URLs valid?)
YAML syntax: validate embedded YAML code blocks

Collect all findings from the script output.

Step 3: Extract embedded artifacts

For each AsciiDoc file, extract embedded technical artifacts:

YAML blocks: Content within [source,yaml] delimiters
CLI commands: Content within [source,bash] or [source,terminal] delimiters
Configuration references: Attribute references like {attribute-name}
API paths: URLs or paths in the format /api/v1/...
CRD references: Kubernetes resource kinds and API versions

Step 4: Cross-reference validation (LLM)

If a context package is available, use LLM judgment to cross-reference extracted artifacts against the gathered context:

For each extracted artifact:

YAML blocks: Compare against CRD schemas and config examples in context
CLI commands: Verify flags and options against --help output or source code in context
API paths: Check against API specs or route definitions in context
CRD references: Verify kind names, API versions, and field names against type definitions

Ask the LLM:

Does this artifact match the authoritative source in the context?
Are there incorrect field names, wrong API versions, or invalid options?
Is the example complete and would it work as shown?

Step 5: Structural validation

Check AsciiDoc structure requirements:

Source the AsciiDoc conventions helper (which internally sources scripts/load-env.sh for credentials and uses scripts/parse-product-config.py to resolve module prefixes):

source "${CLAUDE_SKILL_DIR}/scripts/asciidoc-conventions.sh"
for file in <files>; do
    adoc_validate_structure "$file"
    mod_type="$(adoc_module_type "$file")"
    if [[ "$mod_type" == "unknown" ]]; then
        # record structural finding: filename prefix does not map to a known module type
        :
    fi
done

Verify:

Module ID present ([id="..."])
Content type attribute set (:_mod-docs-content-type:)
Level-1 heading present
Module type matches filename prefix (enforced via adoc_module_type check)

Step 6: Compile findings

Merge all findings from Steps 2-5, deduplicating and normalizing:

{
    "validated_at": "2026-04-14T10:40:00Z",
    "files_validated": 5,
    "findings": [
        {
            "file": "modules/serving/pages/con_model-serving.adoc",
            "line": 42,
            "severity": "high|medium|low",
            "category": "vale|asciidoctor|lychee|yaml_syntax|cross_reference|structure",
            "tool": "vale|asciidoctor|lychee|yaml_syntax|llm|structural",
            "rule": "RedHat.Spelling",
            "message": "Description of the issue",
            "suggestion": "How to fix it"
        }
    ],
    "summary": {
        "high": 0,
        "medium": 3,
        "low": 5,
        "total": 8,
        "tools_run": ["vale", "asciidoctor", "yaml_syntax"],
        "tools_skipped": ["lychee"]
    }
}

Step 7: Write findings

Write workspace/validation-findings.json with the compiled results.

Output

Primary: workspace/validation-findings.json Report to caller: total findings by severity, which tools ran vs skipped.

Gotchas

Vale, asciidoctor, and lychee are optional dependencies; if any are missing, that validator is silently skipped. Check tools_skipped in the output to confirm which ran.
Cross-reference validation (Step 4) requires a context package; without it, only deterministic checks run and the results may miss technical inaccuracies.
Link checking via lychee can be slow on files with many external URLs and may produce false positives for rate-limited sites.

Stop conditions

Continue: Individual tool missing (warn and skip)
Continue: Individual file fails to parse (record finding, continue)
Halt: No files found matching the target argument

Agent Skills: doc-validate

Install this agent skill to your local

Skill Files