Collection catalogs - YAML schema validation, and authoring tooling

[dmartinol]

Summary

This branch introduces a machine-readable catalog per pack under /.catalog/ (collection.yaml plus a deterministic collection.json mirror and supporting fragments such as deploy_and_use.md), aligned with COLLECTION_SPEC.md and catalog/schema.yaml.

What changed

• Catalog artifacts (collection,yaml) generated from golden sources (skills, README, CLAUDE, marketplace) without overwriting those sources.
• Validation pipeline: collection schema checks, compliance checks, and wiring in Makefile / existing validation so CI can enforce catalog shape and roster consistency.
• Scripts: catalog bootstrap/scaffold, YAML→JSON mirroring, shared validation library, and pack_registry integration with existing tooling (e.g. generate_pack_data.py updates).
• Contributor docs: updates to README.md, docs/README.md, and root CLAUDE.md describing the catalog workflow and validation.
• Agent skills under .claude/skills/: create-collection and collection-compliance to author or refresh catalogs and fix validation failures.
• Repo hygiene: .pre-commit-config.yaml, small pyproject.toml / uv.lock updates, and a minor GitHub Pages workflow adjustment.

Pack(s) affected

• all
• rh-sre
• rh-developer
• ocp-admin
• rh-virt
• rh-ai-engineer
• Other / repo-wide

Change type

• New skill
• New agent
• New pack
• Update existing skill / agent
• MCP server config (mcps.json)
• Docs / README
• CI / tooling

CLAUDE.md compliance

• Agents orchestrate skills; no direct MCP/tool calls in agents
• Skills are single-purpose task executors
• Skills encapsulate all tool access (MCP tools invoked only inside skills)
• Document consultation: file is read with the Read tool, then declared to the user
• No credentials hardcoded; env vars used via ${VAR} references
• Human-in-the-loop confirmation added for any destructive or critical operations

Validation

• make validate passes locally
• New/changed skills have valid YAML frontmatter (name, description)
• New/changed agents have valid YAML frontmatter (name, description)

[github-actions]

Gemini Code Review

1. Summary

This PR introduces a comprehensive collection catalog specification (COLLECTION_SPEC.md) and schema (catalog/schema.yaml) to standardize metadata across all agentic packs. It bootstraps .catalog/ directories (YAML and JSON mirrors) for all existing packs, adds pre-commit hooks for validation, and introduces two new repository-level skills (collection-compliance and create-collection) to help maintainers and AI assistants manage catalog drift.

2. Project Rules Compliance

There are a few violations of the strict skill design principles in the newly added repository skills (.claude/skills/):

• Mandatory Section Headings:
  • In both collection-compliance/SKILL.md and create-collection/SKILL.md, the heading ## When to Use is used. Per Principle Rh virt/snapshots skills #7, this must be exactly ## When to Use This Skill.
  • Similarly, ## Example usage should be capitalized as ## Example Usage.
• Skill Invocation Format:
  • In collection-compliance/SKILL.md, the create-collection skill is referenced multiple times without the mandatory slash format. Per Principle Rh developer/human in the loop #4, it should be referenced as /create-collection.
• Human-in-the-Loop (HitL):
  • The /create-collection skill modifies and writes files (<pack>/.catalog/collection.yaml). Per Principle Rh virt/agent init #6, skills performing create/modify operations MUST include a ## Critical: Human-in-the-Loop Requirements section requiring explicit confirmation before writing to disk.
• Build Reminder: Since new skills were added and structural validation rules were updated, please ensure you run make validate and make validate-skill-design-changed locally before merging.

3. Code Quality Issues

• Typo in Directory Path:
  • file: .claude/skills/collection-compliance/SKILL.md:49
  • The dependency lists - create-collection skill (sibling under .cursor/skills/). This should be .claude/skills/ as .cursor/skills/ does not exist in this PR.

4. Suggestions

• Schema Completeness: In rh-developer/.catalog/collection.yaml (and others), you are using fields like documentation_section_file, mcp_section_file, and security_model_file. While catalog/schema.yaml allows this because additionalProperties: true is set at the root, you might want to explicitly define these *_file properties in the JSON schema for better IDE autocompletion and stricter validation.
• Pre-commit Hook Scope: The new .pre-commit-config.yaml runs make validate-skill-design-changed on ^(rh-[-a-z0-9]+|ocp-admin)/skills/[^/]+/SKILL\.md$. You may want to consider adding ^\.claude/skills/[^/]+/SKILL\.md$ to this regex so that your new repository-level skills are also linted for design compliance.

5. Verdict

REQUEST_CHANGES — Please fix the mandatory section headings, add the missing HitL section to the file-modifying skill, and correct the .cursor/skills/ typo. Excellent work on the catalog standardization otherwise!

---

Automated review by Gemini 3.1 Pro | Rules: CLAUDE.md, SKILL_DESIGN_PRINCIPLES.md

[dmartinol]

• Pre-commit Hook Scope: The new .pre-commit-config.yaml runs make validate-skill-design-changed on ^(rh-[-a-z0-9]+|ocp-admin)/skills/[^/]+/SKILL\.md$. You may want to consider adding ^\.claude/skills/[^/]+/SKILL\.md$ to this regex so that your new repository-level skills are also linted for design compliance.

Great hint but out of scope for the current PR.
We will track an issue to remind it.

[r2dedios]

Great job :) Just have a few questions to check