feat: add Compass catalog manifests for all agentic packs by r2dedios · Pull Request #133 · RHEcosystemAppEng/agentic-plugins

r2dedios · 2026-07-03T13:50:06Z

Summary

Register the entire agentic-plugins repository in Red Hat Compass (Backstage) with a complete hierarchy of catalog manifests covering all 7 agentic packs, 75 skills, and 7 MCP servers.

Architecture

Location (root catalog-info.yaml)
│
├── System (agentic-plugins) ── models the whole repository
│
├── Location (ocp-admin)       → AiResource(plugin) + 7 skills
├── Location (rh-sre)          → AiResource(plugin) + 13 skills
├── Location (rh-virt)         → AiResource(plugin) + 10 skills
├── Location (rh-developer)    → AiResource(plugin) + 17 skills
├── Location (rh-basic)        → AiResource(plugin) + 6 skills
├── Location (rh-ai-engineer)  → AiResource(plugin) + 11 skills
├── Location (rh-automation)   → AiResource(plugin) + 11 skills
│
└── Location (mcps)
    └── MCPServer ×7 (owned by us)

Entity inventory

Kind	spec.type	Count	Description
Location	—	9	1 root + 7 packs + 1 mcps
System	—	1	`agentic-plugins` (repo-level grouping)
AiResource	`plugin`	7	One per agentic pack
AiResource	`skill`	75	Individual skills across all packs
MCPServer	`local`/`remote`	7	Owned MCP servers
Total		99

Relationships

AiResource(plugin) → partOf → System(agentic-plugins) via spec.system
AiResource(skill) → dependsOn → AiResource(plugin) of its parent pack
AiResource(skill) → dependsOn → MCPServer (when the skill uses MCP tools)
AiResource(plugin) → dependsOn → MCPServer (pack-level MCP dependencies)
MCPServer → partOf → System(agentic-plugins) via spec.system
All entities → ownedBy → group:redhat/ecosystem-appeng

Canonical MCP server reuse

Two MCP servers already registered in Compass by their upstream teams are not duplicated — skills reference the canonical entities directly:

Canonical entity	Namespace	Owner
`red-hat-lightspeed-mcp-server`	`redhat`	`rh-lightspeed-mcp`
`security-mcp-server`	`redhat`	`lightforge-mcp-dev`

Key design decisions

AiResource over System for packs: Packs are modeled as AiResource(type: plugin) instead of System, consistent with Backstage AI resource modeling and supporting many-to-many skill↔MCP dependencies
Location delegation: Root Location only references child Locations (one per pack + one for MCPs). Each child Location indexes its own entities. No direct leaf references from root
Namespace per pack: Each pack uses its own namespace (e.g., rh-sre, ocp-admin). MCP servers use agentic-plugins namespace
Reuse canonical MCPs: Per Compass team guidance, existing MCP servers are referenced rather than re-registered

Test plan

All manifests validated against Compass validate-entity API
Entities registered and visible in Compass catalog
Entity relationships verified (dependsOn, partOf, ownedBy)
Canonical MCP server references resolve correctly
Verify System page shows contained entities (known Compass limitation for custom kinds)

Add catalog-info.yaml manifests to register the repository and ocp-admin agentic pack in Red Hat Compass (Backstage). Includes: - Root Location pointing to all agentic packs - ocp-admin pack Location aggregating skills and MCP servers - 7 AiResource entities for skills (cluster-creator, cluster-inventory, cluster-report, container-cve-validator, coreos-cve-validator, cve-recon, image-inspect) - 3 MCPServer entities (openshift-self-managed, openshift-ocm-managed, openshift-administration) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add 19 centralized MCP server manifests in ./mcps/ (flat structure) with deduplication by functional variant for shared images - Add 68 skill (AiResource) manifests across 6 new packs: rh-sre (13), rh-virt (10), rh-developer (17), rh-basic (6), rh-ai-engineer (11), rh-automation (11) - Add pack Location manifests for rh-sre, rh-virt, rh-developer, rh-basic, rh-ai-engineer, rh-automation - Update root Location to reference all 7 packs + 19 MCPs - Update ocp-admin Location: remove MCP targets, add labels - Update ocp-admin skill dependsOn refs to use default namespace - Remove old ocp-admin/mcps/ catalog-info.yaml files - Add domain-prefixed labels on all Locations: agentic-plugins.redhat.com/version and agentic-plugins.redhat.com/repo

Create a Domain entity (agentic-plugins) as the top-level parent and 7 System entities (one per pack) to provide rich grouping pages in Compass. Skills already reference their pack System via spec.system, so Backstage will auto-generate hasPart relations once these exist.

Merge 19 MCP manifests into 9 by grouping variants that share the same container image or server technology: - 4 openshift-mcp-server variants → openshift-mcp-server - 2 assisted-service-mcp variants → assisted-installer - 2 lightspeed variants → red-hat-lightspeed - 6 AAP endpoint variants → ansible-automation-platform - 5 unique MCPs unchanged Update all 75 skill dependsOn references and deduplicate where a skill previously referenced multiple variants of the same MCP.

Domain kind is not allowed for GitHub-based Location registration in Compass. Remove domain.yaml target and domain references from all System manifests to unblock registration.

Add backstage.io/techdocs-ref annotation to each pack's system.yaml pointing to the pack README.md on GitHub main branch.

Add dedicated namespace to all 9 MCPServer manifests and update all 71 skill dependsOn references accordingly.

…tions - Create System entity for shared MCPs (rh-agentic-plugins-mcps) - Add spec.system to all 9 MCPServer manifests - Add spec.dependsOn to 7 pack Systems linking to their MCPs - Add agentic.redhat.com/* annotations to all pack Locations and Systems - Fix repo label from "redhat-agentic-plugins" to "agentic-plugins" - Remove domain.yaml (Compass rejects Domain from GitHub Locations)

Point each MCPServer to its upstream repo README: - openshift-mcp-server → openshift/openshift-mcp-server - assisted-installer → openshift-assisted/assisted-service-mcp - red-hat-lightspeed → RedHatInsights/insights-mcp - ansible-automation-platform → ansible/aap-mcp-server - ai-observability → rh-ai-quickstart/ai-observability-summarizer - rhoai → opendatahub-io/rhoai-mcp - podman → manusa/podman-mcp-server - github → github/github-mcp-server red-hat-security skipped (no public repo, hosted service).

Add airesource dependsOn entries for orchestration skills that directly invoke other skills via the Skill tool. Covers 37 dependencies across 8 skills in rh-sre, rh-developer, rh-automation, and rh-ai-engineer. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

TechDocs builder expects mkdocs.yml + docs/ in the target repo, but our techdocs-ref URLs pointed to bare README.md files causing ENOENT errors. Move upstream MCP repo URLs to metadata.links instead, where they render as navigable links without triggering the builder. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace kind: System with kind: AiResource (type: plugin) for all 7 agentic packs. Rename system.yaml to <pack>-plugin.yaml. Add disciplines, categories, agents, and lifecycle fields to each pack manifest.

Remove spec.system from all 75 skill catalog-info.yaml files and add airesource:<pack>/<pack> to spec.dependsOn instead. Also update MCP server references to use agentic-plugins namespace.

Add root System entity (agentic-plugins). Remove mcps/system.yaml and consolidate all entities under the single system. Create mcps Location, add plugin targets to pack Locations, and simplify root Location to delegate through pack and MCP Locations only.

Document entity kinds, Location hierarchy, entity relationships, namespaces, reference formats, and workflows for adding new skills and packs with their Compass manifests.

Backstage resolves unqualified spec.system references relative to the entity's own namespace. Since the System entity is in the default namespace but plugins and MCPs use their own namespaces, the partOf relation was not resolving. Use default/agentic-plugins to fix.

Compass does not auto-generate hasPart inverse relations for custom kinds (AiResource, MCPServer). Declare them explicitly so the System page shows its contained plugins and MCP servers.

Remove duplicate MCPServer entities for Red Hat Lightspeed and Red Hat Security, replacing dependsOn references with their canonical versions already registered in Compass by their respective teams: - mcpserver:agentic-plugins/red-hat-lightspeed → mcpserver:redhat/red-hat-lightspeed-mcp-server - mcpserver:agentic-plugins/red-hat-security → mcpserver:redhat/security-mcp-server Reduces our registered MCP servers from 9 to 7.

Update spec.owner across all 90 Compass manifests from group:redhat/ecosystem-appeng to group:redhat/ai5-marketplace.

r2dedios and others added 19 commits July 3, 2026 15:46

fix: remove Domain entity from Location targets

df03ed4

Domain kind is not allowed for GitHub-based Location registration in Compass. Remove domain.yaml target and domain references from all System manifests to unblock registration.

feat: add TechDocs annotation to all System manifests

3deefb1

Add backstage.io/techdocs-ref annotation to each pack's system.yaml pointing to the pack README.md on GitHub main branch.

feat: add rh-agentic-plugins-mcps namespace to MCP manifests

3bf6e63

Add dedicated namespace to all 9 MCPServer manifests and update all 71 skill dependsOn references accordingly.

refactor: convert pack System entities to AiResource plugins

7e301fc

Replace kind: System with kind: AiResource (type: plugin) for all 7 agentic packs. Rename system.yaml to <pack>-plugin.yaml. Add disciplines, categories, agents, and lifecycle fields to each pack manifest.

refactor: replace spec.system with dependsOn in skill manifests

b913638

Remove spec.system from all 75 skill catalog-info.yaml files and add airesource:<pack>/<pack> to spec.dependsOn instead. Also update MCP server references to use agentic-plugins namespace.

docs: add Compass manifest documentation to CLAUDE.md

b476511

Document entity kinds, Location hierarchy, entity relationships, namespaces, reference formats, and workflows for adding new skills and packs with their Compass manifests.

fix: add explicit hasPart relations to System entity

8c2289e

Compass does not auto-generate hasPart inverse relations for custom kinds (AiResource, MCPServer). Declare them explicitly so the System page shows its contained plugins and MCP servers.

revert: remove explicit hasPart relations (not supported by Compass)

77c4cb3

r2dedios changed the title ~~feat: add Compass catalog manifests for ocp-admin pack~~ feat: add Compass catalog manifests for all agentic packs Jul 10, 2026

chore: change owner group to ai5-marketplace

ac06903

Update spec.owner across all 90 Compass manifests from group:redhat/ecosystem-appeng to group:redhat/ai5-marketplace.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add Compass catalog manifests for all agentic packs#133

feat: add Compass catalog manifests for all agentic packs#133
r2dedios wants to merge 20 commits into
RHEcosystemAppEng:mainfrom
r2dedios:compass-skill-manifests

r2dedios commented Jul 3, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

r2dedios commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Architecture

Entity inventory

Relationships

Canonical MCP server reuse

Key design decisions

Test plan

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

r2dedios commented Jul 3, 2026 •

edited

Loading