From cqa-tools
Runs Vale with AsciiDocDITA rules on AsciiDoc files in Red Hat modular docs repos (repo-wide or assembly/topic scope via dita-validate-asciidoc) and fixes violations for 0 errors/warnings.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin cqa-toolsThis skill is limited to using the following tools:
**P1: Content passes Vale dita-tools:dita-validate-asciidoc check with no errors or warnings.**
Validates AsciiDoc files for DITA conversion readiness using Vale linting with AsciiDocDITA rules. Reports warnings and errors in markdown table format. Useful when checking files before DITA conversion.
Orchestrates full CQA 2.1 content quality assessments for Red Hat modular documentation repositories, guiding parameter-by-parameter through Pre-migration, Quality, and Onboarding tabs using specialized skills.
Runs Vale linting on Markdown, AsciiDoc, reStructuredText, HTML, XML, and source code comments to detect style guide violations. Use for documentation linting, style checks, or validation.
Share bugs, ideas, or general feedback.
P1: Content passes Vale dita-tools:dita-validate-asciidoc check with no errors or warnings. Level: Required. Target: Score 4 (0 errors, 0 warnings).
Ask the user for the path to their Red Hat modular documentation repository. This is the directory that contains assemblies/, topics/ (or modules/), and titles/ directories.
Store this as DOCS_REPO for all subsequent steps.
Vale must be installed (v3.x+). For assembly/topic scope, the dita-tools:dita-validate-asciidoc skill checks this automatically. For repo-wide scope, verify manually:
vale --version
If not installed, stop and tell the user to install Vale v3.x+. Do not install it for them.
Choose the approach based on scope.
Run Vale directly against all AsciiDoc files in the repo. This catches every .adoc file, including orphan files not referenced by any assembly.
IMPORTANT: CQA P1 requires checking with AsciiDocDITA rules only. The repo may have its own .vale.ini with different styles (e.g., RedHat, AsciiDoc, RHEL10). Do NOT use the repo's own Vale config for CQA P1 — those are for the repo's CI, not for CQA assessment. Always create and use a dedicated CQA config file.
Create .vale-cqa.ini in the docs repo root (overwrite if it exists):
StylesPath = .vale/styles
MinAlertLevel = warning
Packages = https://github.com/jhradilek/asciidoctor-dita-vale/releases/latest/download/AsciiDocDITA.zip
[*.adoc]
BasedOnStyles = AsciiDocDITA
Then sync and run with the CQA config explicitly:
cd "$DOCS_REPO"
vale --config=.vale-cqa.ini sync
find . -name '*.adoc' -not -type l | xargs vale --config=.vale-cqa.ini
Do NOT run vale without --config=.vale-cqa.ini — without it, Vale picks up the repo's own .vale.ini which may use different style packages and produce errors/warnings unrelated to CQA P1.
Invoke the dita-tools:dita-validate-asciidoc skill, which discovers all included files and runs Vale with content-type-aware ShortDescription filtering:
Skill: dita-tools:dita-validate-asciidoc, args: "$DOCS_REPO/assemblies/admin/assembly_installing.adoc"
Skill: dita-tools:dita-validate-asciidoc, args: "$DOCS_REPO/topics/con-overview.adoc"
If the result is 0 errors, 0 warnings (or no output for dita-validate-asciidoc) — score 4 and skip to Step 6.
Group the output by rule name. Common rules and their fixes:
| Rule | Meaning | Fix |
|---|---|---|
ContentType | Missing :_mod-docs-content-type: | Add attribute as first line |
ShortDescription | Missing [role="_abstract"] | Add abstract paragraph after title |
ConceptLink | Link/xref in body of CONCEPT or ASSEMBLY | Move link to .Additional resources section. Rewrite surrounding text. |
TaskInclude | include:: inside .Procedure | Inline the included content directly into procedure steps |
RelatedLinks | Non-link content inside .Additional resources | Ensure only links appear. Use proper == headings (not bold pseudo-headings) after .Additional resources to close the section. |
TaskStep | Content after .Procedure is not ordered list | Convert * to . |
TaskSection | == subsections in a PROCEDURE | Remove subsection headings or split into multiple procedures |
TaskTitle | Procedure title not imperative | Rename to imperative phrase |
BlockTitle | Unsupported block title in wrong module type | Remove .Procedure from concepts, etc. |
ExampleBlock | Nested ==== delimiters | Restructure to avoid nesting example blocks |
Process fixes in this order to avoid cascading issues:
For each flagged link/xref in a CONCEPT or ASSEMBLY file:
[role="_additional-resources"] .Additional resources section (create one at end of file if none exists)**text**), convert to == headings (CONCEPT files allow subsections)For each include:: inside a .Procedure:
include:: directiveThe .Additional resources section ends only when Vale encounters a recognized heading (a line matching == Title or .Title format). Bold pseudo-headings (**text**) are NOT recognized as headings.
For each RelatedLinks warning:
.Additional resources — convert it to a == subsection headinglink:, xref:, <<...>>, bare URLs) appear inside the .Additional resources section.Additional resources is mid-file, ensure a proper == heading follows it to close the sectionRe-run the same method used in Step 2. The result MUST be clean before scoring.
cd "$DOCS_REPO"
find . -name '*.adoc' -not -type l | xargs vale --config=.vale-cqa.ini
Skill: dita-tools:dita-validate-asciidoc, args: "$ASSEMBLY_OR_TOPIC"
If warnings remain, return to Step 3. Do not score until the output is clean.
| Score | Criteria |
|---|---|
| 4 | 0 errors, 0 warnings |
| 3 | 0 errors, fewer than 10 warnings |
| 2 | Errors present or 10+ warnings |
| 1 | Vale not configured or not run |
Record the score, the exact Vale output (file count, error count, warning count), and the Vale version used.
.vale-cqa.ini — the repo's .vale.ini may use RedHat, AsciiDoc, or RHEL10 styles that produce errors unrelated to CQA P1 (e.g., RedHat.TermsErrors for "vs"). CQA P1 only checks AsciiDocDITA rules.== headings in concept files