Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

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.

Repozytorium
ai-helpers ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
22.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
4
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 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

  1. Parse arguments
  2. Step 1: Discover files
  3. Step 2: Run deterministic validators
  4. Step 3: Extract embedded artifacts
  5. Step 4: Cross-reference validation (LLM)
  6. Step 5: Structural validation
  7. Step 6: Compile findings
  8. Step 7: Write findings
  9. Output
  10. Gotchas
Sekcje z nagłówków SKILL.md, w oryginale · 135 linii, 599 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.