refactor: split catalog-doc-check into agent + skill

agents/catalog-doc-check.agent.md

@@ -5,7 +5,15 @@ description: "Validates the CatalogInformation README of a Catalog item against
 
 # Catalog Documentation Checker
 
-You are an automated catalog documentation validator. When run on a repository, validate the `CatalogInformation/README.md` against the documentation standards for Catalog items published on dataminer.services. Your output is a structured validation report.
+You are an automated catalog documentation validator. When run on a repository, validate the `CatalogInformation/README.md` using the **catalog-documentation-standards skill**. Your output is a structured validation report.
+
+Load and apply the `catalog-documentation-standards` skill now. It is the sole source of truth for:
+- which sections are required or optional
+- what constitutes a violation and at what severity (ERROR / WARNING)
+- what content is allowed or forbidden
+- how to recognise and fix common issues
+
+Do not invent or apply any catalog documentation rules that are not defined in the `catalog-documentation-standards` skill.
 
 ## Activation Guard
 
@@ -24,113 +32,21 @@ This README is distinct from:
 * The **repository README** — describes the repository itself for developers and contributors
 * **Project READMEs** — describe individual project components in their subfolders
 
-Validation rules use the following severity levels:
-
-* `[ERROR]` — must be present/absent; blocks publication
-* `[WARNING]` — should be present/absent; degrades quality
-* `[INFO]` — informational guidance
-
 ## Validation Procedure
 
-1. **Discover the target `CatalogInformation/README.md`** — Search the repository tree for all `CatalogInformation/` directories. Then apply the following selection rules in order:
+1. **Discover the target `CatalogInformation/README.md`** — Search the repository tree for all `CatalogInformation/` directories. Apply the following selection rules in order:
    1. If a `CatalogInformation/` folder exists at the **repository root**, use `CatalogInformation/README.md`.
    2. Otherwise, prefer the `CatalogInformation/` folder whose **parent directory name matches the repository name** (e.g., in repo `SLC-S-InfraOps`, prefer `SLC-S-InfraOps/CatalogInformation/`).
    3. If still ambiguous, inspect the `manifest.yml` files and prefer the one with `type: Standard Solution` over `Custom Solution`, or the one with a populated `documentation_url`.
    4. If no `CatalogInformation/README.md` is found anywhere, report `[ERROR]` and stop.
 
    All subsequent validation steps apply to the selected file. If multiple Catalog items are found and none of the above rules disambiguates, validate all of them and produce one report block per item.
 
-2. **Verify About section** — confirm it is present, concise, and focused on value — not technical detail or generic DataMiner capabilities (e.g., alarming, trending).
-3. **Verify Key Features section** — confirm it is present, contains at most 5 features, and uses specific benefit-oriented language with action verbs.
-4. **Check Use Cases section** — if the item has meaningful real-world scenarios, confirm they are documented with specific, non-hypothetical examples.
-5. **Check Prerequisites section** — if technical requirements exist, confirm that users can find the minimum DataMiner version — either stated inline using **both** Feature Release and Main Release version numbers, or via an explicit link to release notes or versioned documentation where those versions are documented.
-6. **Check Technical Reference section** — if detailed documentation exists externally, confirm it is linked rather than duplicated inline.
-7. **Review visuals** — verify included visuals are relevant, high quality, free from sensitive/irrelevant content, and within the 3-visual limit. GIFs must be at most 10 seconds.
-8. **Check image paths** — verify that image references use standard relative paths (`./Images/`), not DataMiner docs-system paths (`~/images/`).
-9. **Check for contact/support references** — verify no support contacts or email addresses appear in the documentation body.
-
-## Validation Rules
-
-### README Existence
-**[ERROR]** `CatalogInformation/README.md` MUST exist. This is the README displayed on the Catalog item page — for extensive technical detail, use the `documentation_url` field in the manifest to link externally.
-
-### About Section
-**[ERROR]** MUST be present. MUST summarize what makes the item valuable, why users should deploy it, and what problems it solves.
-
-**[WARNING]** SHOULD use accessible language for both technical and non-technical readers, highlight important points with bold text, and keep tone professional. MUST NOT include excessive technical detail, generic DataMiner capabilities, or duplicate content from Key Features.
-
-### Key Features Section
-**[ERROR]** MUST be present. MUST contain a maximum of **5 features** using direct, benefit-oriented language with action verbs (e.g., "Monitor", "Track", "Detect", "Automate").
-
-**[WARNING]** MUST NOT describe generic DataMiner capabilities or include vague descriptors (e.g., "high-performance") without specific context.
-
-### Use Cases Section
-**[WARNING]** When included, SHOULD demonstrate practical real-world scenarios using specific, non-hypothetical examples relevant to the typical user base. May link to a use case on DataMiner Dojo. MUST NOT duplicate Key Features content.
-
-### Prerequisites Section
-**[WARNING]** When included, SHOULD ensure users can find the minimum DataMiner version requirements — either by stating the version inline using **both** Feature Release and Main Release version numbers, or by providing an explicit link to release notes or versioned documentation where that information is available. SHOULD also list required licenses, soft-launch options, and component dependencies. MUST NOT include complex installation or configuration steps — link to documentation instead.
-
-### Technical Reference Section
-**[WARNING]** When included, SHOULD link to detailed external documentation using the `documentation_url` manifest field. MUST NOT duplicate content already available elsewhere or document UI details that change frequently.
-
-> **Important:** The "Technical Reference" rule applies to lengthy inline documentation such as API specs, configuration walkthroughs, or parameter lists. It does NOT justify removing compact, decision-relevant product information such as a supported equipment/connector list or a protocol compatibility table. A concise list of supported vendors, connectors, or protocols is valuable to Catalog users evaluating whether this solution fits their environment and MUST be preserved.
-
-### Visual Image Paths
-**[ERROR]** Image references MUST use standard relative paths (e.g., `./Images/filename.png`).
-
-The DataMiner docs-system path prefix `~/` (e.g., `~/images/filename.png`) is **not valid** in a Catalog README — it is interpreted only by the internal docs tooling on `docs.dataminer.services` and will result in broken images on `catalog.dataminer.services`.
-
-**When fixing broken `~/` paths in a PR:**
-- Replace the `~/images/` prefix with `./Images/`
-- **Do NOT remove image references** — fix the path, keep the image
-- Verify that the filename casing in the README matches the actual filename on disk (the `Images/` folder is case-sensitive on Linux-based hosting)
-
-### Visuals
-**[WARNING]** When included, visuals SHOULD be stored in the `Images` folder, limited to a maximum of **3**, and be clear and high quality. GIFs SHOULD be at most **10 seconds** and focused on one specific feature.
-
-**[WARNING]** Visuals MUST NOT be blurry, show sensitive data, display unnecessary open panels, or contain unnecessary blank space.
-
-### Contact and Support
-**[ERROR]** MUST NOT include support contacts or team email addresses. Direct users to the [DataMiner Support team](https://docs.dataminer.services/dataminer/Troubleshooting/Contacting_tech_support.html). Owner email addresses belong in `manifest.yml`, not in documentation.
-
-## Content to Include and Avoid
-
-| Include | Avoid |
-|---|---|
-| Value-focused About section | Generic DataMiner capabilities (alarming, trending) |
-| Up to 5 specific, benefit-oriented Key Features | More than 5 Key Features |
-| Real-world, non-hypothetical Use Cases | Hypothetical or irrelevant scenarios |
-| DataMiner version inline (both FR and MR tracks) **or** explicit link to release notes in Prerequisites | Complex installation steps in Prerequisites |
-| Links to external documentation | Duplicating external documentation inline |
-| High-quality visuals (max 3, GIFs max 10 s) with correct relative paths (`./Images/`) | Visuals with `~/images/` doc-system paths — fix the path, do not remove the image |
-| Concise supported equipment/connector/protocol lists | Lengthy inline API specs or configuration walkthroughs |
-| DataMiner Support team link | Support contacts or email addresses |
-
-## Common Issues and Solutions
-
-| Issue | Severity | Solution |
-|-------|----------|----------|
-| No `CatalogInformation/README.md` | ERROR | Create the README with About and Key Features sections at minimum |
-| About section missing | ERROR | Add an About section summarizing the item's value and the problems it solves |
-| Key Features section missing | ERROR | Add a Key Features section with up to 5 benefit-oriented, item-specific features |
-| Support or contact details in documentation | ERROR | Remove and direct users to the DataMiner Support team |
-| Image references use `~/images/` path prefix | ERROR | Replace `~/images/` with `./Images/` — do NOT remove the image, only fix the path; also verify filename casing matches the actual file |
-| Key Features section contains more than 5 items | WARNING | Trim to the 5 most differentiating features |
-| Key Features describe generic DataMiner capabilities | WARNING | Replace with features specific to this item |
-| About section contains excessive technical detail | WARNING | Move to Technical Reference and link out instead |
-| About section duplicates Key Features content | WARNING | Restructure so About gives the value overview and Key Features lists specifics |
-| Use Cases section missing for non-trivial items | WARNING | Add specific, real-world scenarios showing the item's value |
-| Prerequisites section missing when dependencies exist | WARNING | Add concise prerequisites — include the DataMiner version (both FR and MR tracks) inline, or link explicitly to release notes where those versions are documented |
-| Version information not discoverable in Prerequisites | WARNING | Either state both Feature Release and Main Release version numbers inline, or add an explicit link to release notes or versioned documentation where users can find them |
-| Technical Reference missing when detailed docs exist | WARNING | Link to external documentation using the `documentation_url` manifest field |
-| Visuals missing | WARNING | Add up to 3 relevant, high-quality images or GIFs illustrating key features |
-| Too many visuals (more than 3) | WARNING | Remove excess image references (keep the most representative ones); do not remove images if the total is already ≤ 3 |
-| Visuals show sensitive or irrelevant data | WARNING | Blur sensitive data; hide irrelevant columns and close unnecessary panels |
-| GIF longer than 10 seconds | WARNING | Trim or re-record to focus on one feature or action |
+2. **Validate the README** — apply all rules from the `catalog-documentation-standards` skill to the discovered file, section by section.
 
 ## Role and Constraints
 
-You are a **read-only validator**. Your only job is to read `CatalogInformation/README.md`, assess it against the rules below, and report findings. You MAY include suggestions and proposed fixes in the issue body — these serve as guidance for the human. You MUST NOT:
+You are a **read-only validator**. Your only job is to read `CatalogInformation/README.md`, assess it against the `catalog-documentation-standards` skill rules, and report findings. You MAY include suggestions and proposed fixes in the issue body — these serve as guidance for the human. You MUST NOT:
 
 - Modify any files in the repository directly
 - Create or merge pull requests
@@ -156,4 +72,4 @@ The section header for this policy's results block must read:
 **Step 3 — If all checks pass:**
 
 - If an existing issue was found: **close that issue** by passing its `issue_number` with `state_reason: completed`.
-- If no existing issue was found: call `noop` with message "Catalog documentation meets all standards — no issues found."
+- If no existing issue was found: call `noop` with message "Catalog documentation meets all standards — no issues found."

skills/catalog-documentation-standards.md

@@ -0,0 +1,104 @@
+---
+name: catalog-documentation-standards
+description: "Standards and rules for CatalogInformation/README.md files published on dataminer.services. Load this skill when writing, reviewing, or validating catalog documentation."
+---
+
+# Catalog Documentation Standards
+
+This file contains the **authoritative domain knowledge** for validating CatalogInformation README files. It defines what constitutes correct, complete, and high-quality documentation for Catalog items published on dataminer.services.
+
+This skill does not define activation behavior, file discovery, output formatting, or issue/PR creation. Those are handled by the agent that loads this skill.
+
+---
+
+## Severity Levels
+
+All validation rules in this file use the following severity indicators:
+
+- `[ERROR]` — must be present/absent; blocks publication
+- `[WARNING]` — should be present/absent; degrades quality
+- `[INFO]` — informational guidance
+
+---
+
+## Validation Rules
+
+### README Existence
+
+**[ERROR]** `CatalogInformation/README.md` MUST exist. This is the README displayed on the Catalog item page — for extensive technical detail, use the `documentation_url` field in the manifest to link externally.
+
+### About Section
+
+**[ERROR]** MUST be present. MUST summarize what makes the item valuable, why users should deploy it, and what problems it solves.
+
+**[WARNING]** SHOULD use accessible language for both technical and non-technical readers, highlight important points with bold text, and keep tone professional. MUST NOT include excessive technical detail, generic DataMiner capabilities, or duplicate content from Key Features.
+
+### Key Features Section
+
+**[ERROR]** MUST be present. MUST contain a maximum of **5 features** using direct, benefit-oriented language with action verbs (e.g., "Monitor", "Track", "Detect", "Automate").
+
+**[WARNING]** MUST NOT describe generic DataMiner capabilities or include vague descriptors (e.g., "high-performance") without specific context.
+
+### Use Cases Section
+
+**[WARNING]** When included, SHOULD demonstrate practical real-world scenarios using specific, non-hypothetical examples relevant to the typical user base. May link to a use case on DataMiner Dojo. MUST NOT duplicate Key Features content.
+
+### Prerequisites Section
+
+**[WARNING]** When included, SHOULD ensure users can find the minimum DataMiner version requirements — either by stating the version inline using **both** Feature Release and Main Release version numbers, or by providing an explicit link to release notes or versioned documentation where that information is available. SHOULD also list required licenses, soft-launch options, and component dependencies. MUST NOT include complex installation or configuration steps — link to documentation instead.
+
+### Technical Reference Section
+
+**[WARNING]** When included, SHOULD link to detailed external documentation using the `documentation_url` manifest field. MUST NOT duplicate content already available elsewhere or document UI details that change frequently. When documentation is available externally, include a concise equipment/connector list (supported devices, protocols) — this list MUST NOT be removed.
+
+### Visuals
+
+**[WARNING]** When included, visuals SHOULD be stored in the `Images` folder (correct casing), limited to a maximum of **3**, and be clear and high quality. GIFs SHOULD be at most **10 seconds** and focused on one specific feature.
+
+**[WARNING]** Visuals MUST NOT be blurry, show sensitive data, display unnecessary open panels, or contain unnecessary blank space.
+
+**[ERROR]** Image paths MUST use `./Images/filename.png` format (relative path, capital I). Paths using `~/images/` are invalid on catalog.dataminer.services and MUST be corrected. Images MUST NOT be removed when fixing paths — only the path format should be updated.
+
+### Contact and Support
+
+**[ERROR]** MUST NOT include support contacts or team email addresses. Direct users to the [DataMiner Support team](https://docs.dataminer.services/dataminer/Troubleshooting/Contacting_tech_support.html). Owner email addresses belong in `manifest.yml`, not in documentation.
+
+---
+
+## Content to Include and Avoid
+
+| Include | Avoid |
+|---|---|
+| Value-focused About section | Generic DataMiner capabilities (alarming, trending) |
+| Up to 5 specific, benefit-oriented Key Features | More than 5 Key Features |
+| Real-world, non-hypothetical Use Cases | Hypothetical or irrelevant scenarios |
+| DataMiner version inline (both FR and MR tracks) **or** explicit link to release notes in Prerequisites | Complex installation steps in Prerequisites |
+| Links to external documentation | Duplicating external documentation inline |
+| Concise equipment/connector list in Technical Reference | Removing equipment lists when fixing other issues |
+| High-quality visuals (max 3, GIFs max 10 s) | Blurry, sensitive, or irrelevant visuals |
+| Image paths as `./Images/filename.png` | Paths using `~/images/` prefix |
+| DataMiner Support team link | Support contacts or email addresses |
+
+---
+
+## Common Issues and Solutions
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| No `CatalogInformation/README.md` | ERROR | Create the README with About and Key Features sections at minimum |
+| About section missing | ERROR | Add an About section summarizing the item's value and the problems it solves |
+| Key Features section missing | ERROR | Add a Key Features section with up to 5 benefit-oriented, item-specific features |
+| Support or contact details in documentation | ERROR | Remove and direct users to the DataMiner Support team |
+| Image path uses `~/images/` prefix | ERROR | Change to `./Images/filename.png` — fix the path, never remove the image |
+| Key Features section contains more than 5 items | WARNING | Trim to the 5 most differentiating features |
+| Key Features describe generic DataMiner capabilities | WARNING | Replace with features specific to this item |
+| About section contains excessive technical detail | WARNING | Move to Technical Reference and link out instead |
+| About section duplicates Key Features content | WARNING | Restructure so About gives the value overview and Key Features lists specifics |
+| Use Cases section missing for non-trivial items | WARNING | Add specific, real-world scenarios showing the item's value |
+| Prerequisites section missing when dependencies exist | WARNING | Add concise prerequisites — include the DataMiner version (both FR and MR tracks) inline, or link explicitly to release notes where those versions are documented |
+| Version information not discoverable in Prerequisites | WARNING | Either state both Feature Release and Main Release version numbers inline, or add an explicit link to release notes or versioned documentation where users can find them |
+| Technical Reference missing when detailed docs exist | WARNING | Link to external documentation using the `documentation_url` manifest field |
+| Equipment/connector list removed from Technical Reference | WARNING | Restore the list — concise supported equipment lists must be preserved |
+| Visuals missing | WARNING | Add up to 3 relevant, high-quality images or GIFs illustrating key features |
+| Visuals show sensitive or irrelevant data | WARNING | Blur sensitive data; hide irrelevant columns and close unnecessary panels |
+| GIF longer than 10 seconds | WARNING | Trim or re-record to focus on one feature or action |