doc-validate
/doc-validate
Waliduje dokumentację AsciiDoc pod kątem poprawności technicznej wzorcem Extract-Identify-Validate, z użyciem Vale, asciidoctor, lychee, kontroli YAML i weryfikacji odwołań przez LLM.
- Autor
- opendatahub-io ↗
- Repozytorium
- ai-helpers ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 22.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 5
- Skrypty
- 4
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 4 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/asciidoc-conventions.sh, scripts/load-env.sh, scripts/parse-product-config.py, scripts/validate-artifacts.py
Co robi i kiedy
Waliduje dokumentację AsciiDoc pod kątem poprawności technicznej wzorcem Extract-Identify-Validate, z użyciem Vale, asciidoctor, lychee, kontroli YAML i weryfikacji odwołań przez LLM.
Argumenty
/doc-validate <file-or-directory> [--context workspace/context-package.json]
Oryginalny opis (EN)
Use when you need to validate AsciiDoc documentation for technical accuracy using Extract-Identify-Validate pattern. Runs Vale, asciidoctor, lychee, YAML syntax checks, and LLM-powered cross-reference validation. Produces workspace/validation-findings.json.
Jak działa
- Parse arguments
- Step 1: Discover files
- Step 2: Run deterministic validators
- Step 3: Extract embedded artifacts
- Step 4: Cross-reference validation (LLM)
- Step 5: Structural validation
- Step 6: Compile findings
- Step 7: Write findings
- Output
- Gotchas
Podgląd SKILL.md
---
name: doc-validate
description: >
Use when you need to validate AsciiDoc documentation for technical
accuracy using Extract-Identify-Validate pattern. Runs Vale,
asciidoctor, lychee, YAML syntax checks, and LLM-powered
cross-reference validation. Produces workspace/validation-findings.json.
argument-hint: "<file-or-directory> [--context workspace/context-package.json]"
model: claude-sonnet-4-5
effort: high
---
# doc-validate
Validate AsciiDoc documentation files for technical accuracy, style compliance, and structural correctness.
## Parse arguments
`$ARGUMENTS` contains:
1. **Target**: file path, directory, or glob pattern for AsciiDoc files to validate
2. **--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:
```bash
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:
1. **YAML blocks**: Content within `[source,yaml]` delimiters
2. **CLI commands**: Content within `[source,bash]` or `[source,terminal]` delimiters
3. **Configuration references**: Attribute references like `{attribute-name}`
4. **API paths**: URLs or paths in the format `/api/v1/...`
5. **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):
```bash
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:
```json
{
"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
Pliki w paczce (5)
- SKILL.md 5 KB
- scripts/asciidoc-conventions.sh 6 KB
- scripts/load-env.sh 2 KB
- scripts/parse-product-config.py 13 KB
- scripts/validate-artifacts.py 9 KB
Wersje
W bazie nie ma innych skilli o nazwie doc-validate.
Migawka bazy z 13.11.2026 · wersja paczki 9c471e0e8f2b (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100documentation-validation
Waliduje jakość dokumentacji: linting prozy z Vale, składnia Markdown i RST, sprawdzanie linków, testy przykładów kodu, walidacja notebooków i instrukcji instalacji oraz CI dla testów dokumentacji. - 100vale
Instaluje, naprawia i waliduje linting prozy w Vale: konfiguracja, synchronizacja stylów, bramki lintu dokumentacji i diagnoza zepsutego workflow. - 100docs-instrument
Wdraża bramkę weryfikacji dokumentacji w repozytorium z zasadami docs-quality: kontrole, konfiguracje, markdownlint i Vale, sprawdzanie linków lychee, testy przykładów i deklaracje doc_type oraz doc_tier. - 100triage
Pomaga przejść od pierwszego dużego przebiegu Vale do decyzji dla każdej reguły: poprawić, obniżyć lub wyłączyć. - 100doc-generate
Generuje moduły dokumentacji AsciiDoc z zebranego kontekstu: czyta pakiet kontekstu i raport luk, tworzy treść i sam waliduje ją z iteracyjną korektą do 3 prób. - 95rhdh-feature-docs
Generuje dokumentację AsciiDoc dla funkcji RHDH na podstawie zgłoszeń Jira, PR-ów i istniejących dokumentów.