# Cqa Modularization

> Use when assessing CQA parameters P2-P7 (modularization). Checks assembly structure, module prefixes, required elements, templates, and nesting depth.

- **Type:** Skill
- **Install:** `agentstack add skill-abhatt-rh-redhat-docs-agent-tools-cqa-modularization`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [abhatt-rh](https://agentstack.voostack.com/s/abhatt-rh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [abhatt-rh](https://github.com/abhatt-rh)
- **Source:** https://github.com/abhatt-rh/redhat-docs-agent-tools/tree/main/plugins/cqa-tools/skills/cqa-modularization
- **Website:** https://redhat-documentation.github.io/redhat-docs-agent-tools/

## Install

```sh
agentstack add skill-abhatt-rh-redhat-docs-agent-tools-cqa-modularization
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CQA P2-P7: Modularization

## Parameters

| # | Parameter | Level |
|---|-----------|-------|
| P2 | Assemblies contain only intro + includes (no rendered text between includes) | Required |
| P3 | Content is modularized (correct prefixes: assembly_, con_, proc_, ref_, snip_) | Required |
| P4 | Modules use official templates (Concept, Procedure, Reference) | Required |
| P5 | All required modular elements present (content type, ID, title, abstract) | Required |
| P6 | Assemblies use official template | Required |
| P7 | Content not deeply nested (max 3 levels: master -> assembly -> topic) | Important |

## Automation scripts

This skill has an automation script:

| Script | Parameters | What it checks |
|--------|-----------|----------------|
| `check-content-types.py` | P3, P4, P5 | Prefix vs content type match, required elements, invalid block titles, procedure structure |

Python 3.9+ stdlib only, no dependencies. Exit code 0 = pass, 1 = issues found.

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/cqa-assess/scripts/check-content-types.py "$DOCS_REPO"
```

Checks: filename prefix matches `:_mod-docs-content-type:`, `[role="_abstract"]` present, `[id="..._{context}"]` present, no procedure-only block titles in non-procedure files, no `==` subsections in procedures, ordered list after `.Procedure`.

## Step 1: Identify the docs repo

Ask the user for the path to their Red Hat modular documentation repository. This is the directory that contains `assemblies/`, `topics/`, and `titles/` directories.

Store this as `DOCS_REPO` for all subsequent steps.

## Step 2: P2 — Assembly structure (no rendered text between includes)

Assemblies map to DITA maps. DITA maps do not accept rendered text between module includes.

### Rule

An assembly has three sections in strict order:

1. **Introductory section** (before the first `include::`) — metadata, title, abstract, and one or more paragraphs, admonition blocks, and/or lists. All rendered text must appear here.
2. **Include statements** — `include::` directives for topics, separated only by blank lines and AsciiDoc comments (`// ...`). No rendered text is allowed between includes.
3. **Additional resources** (optional, after all includes) — a `[role="_additional-resources"]` `.Additional resources` section with links.

### Check procedure

For each `assembly_*.adoc` file in `assemblies/`:

1. Read the file
2. Find the line number of the first `include::` directive
3. Find the line number of the last `include::` directive
4. Scan lines between the first and last `include::` — only the following are allowed:
   - `include::` directives
   - Blank lines
   - AsciiDoc comments (`// ...`)
5. Any other content (paragraphs, bullet lists, ordered lists, admonition blocks, bold text) is a **violation**

### Fix pattern

Move all rendered text that appears between includes to the introductory section before the first `include::`. If the text is specific to a particular topic, consider absorbing it into that topic's abstract or content instead.

### Scoring

| Score | Criteria |
|-------|----------|
| **4** | All assemblies have no rendered text between includes |
| **3** | 1-2 assemblies with minor text between includes (e.g., a single comment-like sentence) |
| **2** | Multiple assemblies with paragraphs, lists, or admonitions between includes |
| **1** | Assembly structure not assessed or widespread violations |

## Step 3: P3 — Content is modularized

Reference: https://redhat-documentation.github.io/modular-docs/

### Rule

Content is modularized when it follows the Red Hat modular documentation framework:

1. **All content is organized into discrete modules** — each module is an independent, self-contained chunk of information that makes sense on its own.
2. **Each module has a single content type** — Concept (explains what/why), Procedure (step-by-step how-to), or Reference (lookup data). No mixed types in a single file.
3. **Modules are grouped into assemblies** — assemblies correspond to user stories and include related modules via `include::` directives.
4. **Consistent naming prefixes** — every file uses the correct prefix for its content type.
5. **Content type declaration matches actual content** — the `:_mod-docs-content-type:` attribute, the filename prefix, and the actual content must all agree.

### Check 1: File prefix compliance

Ask the user for the directory structure of their docs repo. The typical Red Hat modular docs repo has `assemblies/`, `topics/` (or `modules/`), and `snippets/` directories.

For each `.adoc` file, verify it uses the correct prefix:

| Directory | Required prefix(es) |
|-----------|---------------------|
| Assemblies directory | `assembly_` |
| Topics/modules directory (concepts) | `con_` |
| Topics/modules directory (procedures) | `proc_` |
| Topics/modules directory (references) | `ref_` |
| Snippets directory | `snip_` |

List all files and flag any that don't match the expected prefix pattern.

### Check 2: Content type declaration

For each `.adoc` file in the assemblies and topics directories, read the first line and check for `:_mod-docs-content-type:` attribute. Valid values: `ASSEMBLY`, `CONCEPT`, `PROCEDURE`, `REFERENCE`, `SNIPPET`.

Flag any files that:
- Are missing the `:_mod-docs-content-type:` declaration
- Have an invalid or misspelled value

### Check 3: Prefix vs content type cross-check

For each file, verify the filename prefix matches the declared content type:

| Prefix | Expected `:_mod-docs-content-type:` |
|--------|--------------------------------------|
| `assembly_` | `ASSEMBLY` |
| `con_` | `CONCEPT` |
| `proc_` | `PROCEDURE` |
| `ref_` | `REFERENCE` |
| `snip_` | `SNIPPET` |

Flag any mismatches.

### Check 4: Content type vs actual content

Verify the declared content type matches what the file actually contains:

| Content type | Must contain | Must NOT contain |
|--------------|-------------|------------------|
| PROCEDURE | `.Procedure` section with ordered list steps (`. `) | — |
| CONCEPT | Explanatory/descriptive content | `.Procedure` section |
| REFERENCE | Structured data (tables, lists, source blocks) | `.Procedure` section |
| ASSEMBLY | `include::` directives | `.Procedure` section |

Check ALL procedure files for `.Procedure` with ordered steps. Check ALL concept files to confirm they have no `.Procedure` section. Check ALL reference files to confirm they contain structured data.

### Check 5: Title quality

Reference:
- https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs
- https://ccs-internal-documentation.pages.redhat.com/peer-review/#_style

Titles must be brief, complete, and descriptive. Assess three dimensions:

**Check 5a: Grammatical form**

| Module type | Required form | Examples |
|-------------|--------------|----------|
| PROCEDURE | Imperative phrase (verb) | "Configure OAuth", "Install Dev Spaces" |
| CONCEPT | Noun phrase (NOT gerund) | "Architecture overview", "Server components" |
| REFERENCE | Noun phrase | "Supported platforms", "CheCluster fields" |
| ASSEMBLY (task-based) | Imperative phrase | "Configure server components" |
| ASSEMBLY (non-procedural) | Noun phrase | "Red Hat Process Automation Manager API reference" |

An assembly is task-based if it contains procedure modules. Flag any procedure title not in imperative form, concept/reference titles using imperatives or gerunds, or task-based assembly titles using noun phrases.

**Check 5b: Title length**

Per the CCS peer review guide, titles should be **3-11 words** long and have **50-80 characters**.

| Violation | Threshold | Action |
|-----------|-----------|--------|
| Too short | 1-2 words AND title is vague without context | Flag — add descriptive context |
| Too long | Over 11 words OR over 80 resolved characters | Flag — shorten by removing redundant qualifiers |
| Borderline short | 2 words but unambiguous (e.g., "Creating workspaces") | Do NOT flag — acceptable in context |

When counting characters, resolve AsciiDoc attributes to their display text (e.g., `{prod-short}` = "OpenShift Dev Spaces" = 20 chars).

**Check 5c: Title quality**

| Criterion | Rule |
|-----------|------|
| Descriptive | A reader should understand what the content covers from the title alone |
| Customer-focused | Focus on customer tasks, not product features |
| Sentence case | Only proper nouns, product names, and Kubernetes resource names are capitalized |
| No weak openers | Do not start concept titles with "About" or "Understanding" — use a noun phrase that directly names the concept |
| No vague titles | Single-word titles like "Architecture" or "Gateway" lack context — add the product or component name |
| Correct article before attributes | `{prod-short}` resolves to "OpenShift Dev Spaces" (vowel sound) — use "an {prod-short}", not "a {prod-short}" |
| No redundant product names | Do not hardcode product names before attributes that already contain them (e.g., "OpenShift {prod}" doubles "OpenShift") |
| Concise phrasing | Remove filler words ("the code of applications running in" → "application code from") |

### Scoring

| Score | Criteria |
|-------|----------|
| **4** | All files use correct prefixes, all content type declarations match, all content matches declared type, all titles follow conventions |
| **3** | 1-3 minor issues (e.g., a borderline title, a concept with a minor procedural element) |
| **2** | Multiple files with wrong prefixes, missing declarations, or content type mismatches |
| **1** | Content is not modularized or no consistent structure |

Record: total file count, count by content type, number of violations per check.

## Step 4: P4 — Modules use official templates

Reference: https://github.com/redhat-documentation/modular-docs/tree/main/modular-docs-manual/files

The official templates define the required structural elements for each module type. Every module must conform to its type's template.

### Check 1: Required elements (all non-snippet files)

Every module (except snippets) must have these 4 elements:

1. `:_mod-docs-content-type:` attribute as the first content line (value: `CONCEPT`, `PROCEDURE`, `REFERENCE`, or `ASSEMBLY`)
2. `[id="name_{context}"]` anchor with `{context}` suffix
3. `= Title` level-1 heading
4. `[role="_abstract"]` annotation followed by a short description paragraph

For each `.adoc` file in the assemblies and topics directories, verify all 4 elements are present. Report any files missing any element.

### Check 2: Procedure template compliance

Per the official procedure template, procedure modules must have:

- `.Procedure` section followed by ordered list steps (`. `)

The following block titles are optional but, when present, must appear in the correct order:

| Block title | Position | Required? |
|-------------|----------|-----------|
| `.Prerequisites` or `.Prerequisite` | Before `.Procedure` | Optional |
| `.Procedure` | Required position | **Required** |
| `.Verification`, `.Results`, or `.Result` | After `.Procedure` | Optional |
| `.Troubleshooting`, `.Troubleshooting steps`, or `.Troubleshooting step` | After `.Verification` | Optional |
| `.Next steps` or `.Next step` | After `.Troubleshooting` | Optional |
| `.Additional resources` | Last section | Optional |

Each block title can appear at most once per module. Check all procedure files for:
- Presence of `.Procedure` with ordered list steps
- Correct ordering of optional sections
- No duplicate block titles

### Check 3: Procedure-only block titles in wrong module types

These block titles are ONLY allowed in procedure modules:

- `.Prerequisites` / `.Prerequisite`
- `.Procedure`
- `.Verification` / `.Results` / `.Result`
- `.Troubleshooting` / `.Troubleshooting steps` / `.Troubleshooting step`
- `.Next steps` / `.Next step`

Search ALL concept, reference, and assembly files for these block titles. Any occurrence is a violation.

### Check 4: Additional resources annotation

For every file that contains `.Additional resources`, verify that `[role="_additional-resources"]` appears on the line immediately before it. A missing role annotation is a violation.

### Check 5: Prerequisites quality

Reference: https://redhat-documentation.github.io/modular-docs/#prerequisites

If a procedure includes prerequisites, verify:

**Check 5a: Label format**

- Must use `.Prerequisites` (plural, dot-prefixed AsciiDoc block title), even with a single prerequisite item
- Flag: `.Prerequisite` (singular), `**Prerequisites**` (bold pseudo-heading), `== Prerequisites` (heading)

**Check 5b: Formatting**

- Prerequisites must be an unordered list using `*` bullet markers
- List items must have parallel grammatical structure
- Admonition blocks within the prerequisites section must be attached to a list item via `+` continuation — not placed as standalone blocks between `.Prerequisites` and `.Procedure`

**Check 5c: Maximum count**

- Do not exceed 10 prerequisite items per procedure

**Check 5d: No steps in prerequisites (declarative language)**

Prerequisites are conditions that must already be true, not steps the user must perform.

| Pattern | Assessment |
|---------|------------|
| "You have access to..." | GOOD — declarative condition |
| "A running instance of..." | GOOD — declarative state |
| "`tool-name` is installed." | GOOD — declarative condition |
| "You must have access to..." | BAD — imperative "must have", change to "You have" |
| "Install the CLI tool." | BAD — imperative action step |
| "Ensure that you have..." | BAD — imperative instruction |
| "To get X, rebuild Y." | BAD — imperative action disguised as prerequisite |
| "Ask a DNS provider to..." | BAD — imperative action step |

A prerequisite may reference another procedure with an xref for HOW to achieve the condition (e.g., "`{prod-cli}`. See: xref:proc_installing-the-dsc-management-tool_{context}[].").

**Check 5e: Placement**

- `.Prerequisites` must appear before `.Procedure`
- No rendered content (admonitions, paragraphs, snippet includes) between the prerequisites list and `.Procedure` unless attached to a list item via `+` continuation

**Common placement violations:**

| Pattern | Problem | Fix |
|---------|---------|-----|
| Standalone `[WARNING]` block between prerequisites and `.Procedure` | Content gap between sections | Attach to last prerequisite item with `+` continuation |
| `include::snippets/...` between prerequisites and `.Procedure` | Snippet renders outside list | Attach to last prerequisite item with `+` continuation |
| `[IMPORTANT]` block with imperative items between prerequisites and `.Procedure` | Combines placement and language violations | Convert to proper prerequisite list items with declarative wording |

### Scoring

| Score | Criteria |
|-------|----------|
| **4** | All modules conform to their official template — all required elements present, correct block title usage, no procedure-only titles in wrong types, all Additional resources annotated, all prerequisites use declarative language with correct formatting |
| **3** | 1-3 minor issues (e.g., a missing optional annotation, one misplaced block title) |
| **2** | Multiple files missing required elements or widespread block title violations |
| **1** | Templates not followed or not assessed |

Record: total files checked, checks performed per file, number of violations per check category.

## Step 5: P5 — All required modular elements are present

Reference:
- Templates: https://github.com/redhat-documentation/modular-docs/tree/main/modular-docs-manual/files
- Assembly definition: https://redhat-documentation.github.io/modular-docs/#assembly-definition

P5 checks that every non-negotiable modular element is present AND meets quality standards. The structural presence of elements is checked in P4. P5 adds the quality dimension — particularly for the short description (abstract).

### Check 1: Structural elements and abstract formatting

Reference: "Rewrite for Impact: DITA short descriptions" (CC

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [abhatt-rh](https://github.com/abhatt-rh)
- **Source:** [abhatt-rh/redhat-docs-agent-tools](https://github.com/abhatt-rh/redhat-docs-agent-tools)
- **License:** Apache-2.0
- **Homepage:** https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-abhatt-rh-redhat-docs-agent-tools-cqa-modularization
- Seller: https://agentstack.voostack.com/s/abhatt-rh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.