From c625f31177da917b377d98955e84c01a39a2cbfe Mon Sep 17 00:00:00 2001 From: rhartuv Date: Thu, 20 Aug 2026 10:29:46 +0300 Subject: [PATCH 1/5] feat: add skill to author and maintain Compass manifests for agentic packs --- .../agentic-contribution-skill/SKILL.md | 5 +- .../compass-manifest-maintenance/SKILL.md | 156 ++++++++++++++++++ .../assets/pack-location.yaml | 20 +++ .../assets/plugin-catalog-info.yaml | 42 +++++ .../assets/skill-catalog-info.yaml | 36 ++++ .../references/mcp-mapping.md | 50 ++++++ .../references/relationship-rules.md | 63 +++++++ CLAUDE.md | 7 +- 8 files changed, 373 insertions(+), 6 deletions(-) create mode 100644 .claude/skills/compass-manifest-maintenance/SKILL.md create mode 100644 .claude/skills/compass-manifest-maintenance/assets/pack-location.yaml create mode 100644 .claude/skills/compass-manifest-maintenance/assets/plugin-catalog-info.yaml create mode 100644 .claude/skills/compass-manifest-maintenance/assets/skill-catalog-info.yaml create mode 100644 .claude/skills/compass-manifest-maintenance/references/mcp-mapping.md create mode 100644 .claude/skills/compass-manifest-maintenance/references/relationship-rules.md diff --git a/.claude/skills/agentic-contribution-skill/SKILL.md b/.claude/skills/agentic-contribution-skill/SKILL.md index 1121a379..2de61c38 100644 --- a/.claude/skills/agentic-contribution-skill/SKILL.md +++ b/.claude/skills/agentic-contribution-skill/SKILL.md @@ -244,8 +244,9 @@ mkdir -p /skills//docs/ - `docs/external-resources.md` - Any external docs/links/KB articles mentioned by user 3. **Update /AGENTS.md**: Add intent routing entry 4. **Create /mcps.json**: If new MCP server needed (use `${ENV_VAR}` format) -5. **Update marketplace/rh-agentic-collection.yml** in [agentic-catalog](https://github.com/RHEcosystemAppEng/agentic-catalog): If new pack (register pack for Lola installation) -6. **Create pack structure**: If new pack (README.md, AGENTS.md, skills/ directory) +5. **Compass manifests**: Run **compass-manifest-maintenance** (`.claude/skills/compass-manifest-maintenance/`) for registered packs — skill `catalog-info.yaml`, Location targets, bidirectional `dependsOn`/`dependencyOf` on plugin and MCP manifests +6. **Update marketplace/rh-agentic-collection.yml** in [agentic-catalog](https://github.com/RHEcosystemAppEng/agentic-catalog): If new pack (register pack for Lola installation) +7. **Create pack structure**: If new pack (README.md, AGENTS.md, skills/ directory) Generate SKILL.md following the mandatory section template in SKILL_DESIGN_PRINCIPLES.md (already consulted in Phase 3). If SKILL.md becomes too long, move detailed content to `docs/` with references in main file. diff --git a/.claude/skills/compass-manifest-maintenance/SKILL.md b/.claude/skills/compass-manifest-maintenance/SKILL.md new file mode 100644 index 00000000..9e0777b9 --- /dev/null +++ b/.claude/skills/compass-manifest-maintenance/SKILL.md @@ -0,0 +1,156 @@ +--- +name: compass-manifest-maintenance +description: | + Author and maintain Compass catalog-info.yaml manifests for agentic packs (skills, plugins, Locations, MCP inverse relations). Use when: + - Adding or updating a skill and its Compass manifest + - Adding a new pack to Compass registration + - MCP usage or orchestration changed in SKILL.md + - Auditing bidirectional dependsOn/dependencyOf drift after PR #133 model + + File-based only: Read/Glob/Grep/Bash. For `.catalog/` marketplace metadata use create-collection. +model: inherit +color: magenta +license: Apache-2.0 +allowed-tools: Read Glob Grep Bash +--- + +# Compass manifest maintenance + +**Audience:** Maintainers updating `catalog-info.yaml` manifests for Red Hat Compass (Backstage) registration. + +**Goal:** Keep Compass manifests aligned with golden sources (`SKILL.md`, `mcps.json`, `AGENTS.md`) + +## Prerequisites + +- Repository root as cwd. +- Read [CLAUDE.md](../../CLAUDE.md) Compass / Backstage Manifests section. +- Read [references/relationship-rules.md](references/relationship-rules.md) and [references/mcp-mapping.md](references/mcp-mapping.md). +- Templates: [assets/](assets/). + +**Do not use** Compass MCP tools (`validate-entity`, `register-entity`, `get-catalog-entity`, `query-entity-graph`). Validation is structural (roster + inverse ref checks) and optional human Compass UI review after merge. + +## When to Use + +- New skill needs `skills//catalog-info.yaml` and Location / inverse updates. +- Skill `allowed-tools` or orchestration changed → MCP or skill `dependsOn` must change. +- New pack registered in Compass (plugin, Location, root index, `system.yaml`). +- Drift audit: skill on disk without manifest, stale `dependencyOf`, or dangling entity refs. +- After `agentic-contribution-skill` creates a skill (run before opening PR). + +**Do not use for:** `.catalog/collection.yaml` (use **create-collection**), generic Compass platform tasks, or automated Compass registration. + +## Workflow + +### 1. Add or update a skill manifest + +1. **Resolve** `` and `` — confirm `/skills//SKILL.md` exists. + +2. **Read golden sources** (precedence): + - `SKILL.md` frontmatter: `name`, `description`, `allowed-tools` + - `SKILL.md` body: `Required MCP Servers`, `/skill-name` invocations, Dependencies, validator prerequisites + - `/mcps.json` — server keys (map via [mcp-mapping.md](references/mcp-mapping.md)) + - `/AGENTS.md` — tags/disciplines hints only (not orchestration inference) + +3. **Derive `dependsOn`** for the skill manifest: + - Always: `airesource:ai5-marketplace/` + - MCP: only servers the skill **actually uses** (tool prefixes + body); see [mcp-mapping.md](references/mcp-mapping.md) + - Other skills: orchestration or documented `/other-skill` invocations in `SKILL.md` + - Script-only skills: no `mcpserver:` entries + +4. **Write** `/skills//catalog-info.yaml` from [assets/skill-catalog-info.yaml](assets/skill-catalog-info.yaml): + - `namespace: ai5-marketplace` + - `labels.distribution: external` + - `agents: []` + - `lifecycle: beta` + - `owner: group:redhat/ai5-marketplace` + - `backstage.io/source-location` → GitHub `main` branch SKILL.md URL + - `dependencyOf`: list orchestrators that `dependsOn` this skill (scan pack or update when editing orchestrator) + +5. **Update inverse manifests** ([relationship-rules.md](references/relationship-rules.md)): + - `/catalog-info.yaml` — `./skills//catalog-info.yaml` in `spec.targets` + - `/-plugin.yaml` — `dependencyOf: airesource:ai5-marketplace/` + - Each `mcpserver:` in skill `dependsOn` → matching `mcps/*.yaml` `dependencyOf` + - Each skill in skill `dependsOn` → that skill's `dependencyOf` includes orchestrator + +6. **Reconcile plugin MCP deps** — plugin `dependsOn` = union of all `mcpserver:` refs across pack skill manifests. + +### 2. Add a new pack (Compass registration) + +1. Create `/-plugin.yaml` from [assets/plugin-catalog-info.yaml](assets/plugin-catalog-info.yaml). +2. Create `/catalog-info.yaml` from [assets/pack-location.yaml](assets/pack-location.yaml). +3. Add `.//catalog-info.yaml` to root `catalog-info.yaml`. +4. Add `airesource:ai5-marketplace/` to `system.yaml` `spec.dependencyOf`. +5. Run **create-collection** for `/.catalog/` separately. + +### 3. Drift / compliance audit + +Run checks with `Glob`/`Grep`/`Bash`: + +| Check | Rule | +|-------|------| +| Roster parity | Every `skills/*/SKILL.md` has `catalog-info.yaml` and pack Location target | +| Inverse parity | Plugin `dependencyOf` = full skill set; each skill `dependsOn` includes plugin | +| MCP inverse | Each skill `mcpserver:` in `dependsOn` → MCP `dependencyOf` includes skill | +| Skill inverse | Each skill→skill `dependsOn` → target `dependencyOf` includes source | +| Dangling refs | Every ref resolves to on-disk manifest or documented canonical MCP | +| Forbidden | No `partOf`/`hasPart` on AiResource/MCPServer; no redundant `dependsOn: system:default/agentic-plugins` on plugins | +| Namespace | Refs use `ai5-marketplace` except `mcpserver:redhat/*` and `default/agentic-plugins` | + +Report violations with file path and fix per workflow §1. Do not weaken checks. + +### 4. Validate (file-based) + +1. Compare YAML against [assets/](assets/) and a known-good manifest in the same pack. +2. Re-run drift audit (§3). +3. Tier 1 on this skill if edited: `uv run python scripts/validate_skills_tier1.py .claude/skills/compass-manifest-maintenance/SKILL.md`. +4. Post-merge: maintainer may register in Compass UI manually (out of scope for this skill). + +## Self-review checklist + +- [ ] Skill manifest matches PR #133 field conventions (`agents: []`, `distribution: external`, `namespace: ai5-marketplace`). +- [ ] MCP deps derived from `SKILL.md` usage, not copied from sibling skills. +- [ ] Every new `dependsOn` has matching `dependencyOf` on the target entity. +- [ ] Pack Location lists every skill manifest path. +- [ ] Plugin `dependencyOf` lists every skill in the pack. +- [ ] No `partOf`/`hasPart` on custom kinds. + +## Dependencies + +- [CLAUDE.md](../../CLAUDE.md) — entity kinds, namespaces, reference formats +- **create-collection** — `.catalog/` marketplace metadata (sibling under `.claude/skills/`) +- [references/relationship-rules.md](references/relationship-rules.md) +- [references/mcp-mapping.md](references/mcp-mapping.md) + +## Common Issues + +- **COMPASS-1288 drift** — updated skill `dependsOn` but forgot plugin or MCP `dependencyOf`. +- **Blanket MCP deps** — declaring every MCP in `mcps.json` instead of per-skill `allowed-tools` usage. +- **Orchestration gaps** — `remediation`-style skills missing skill→skill edges or inverse `dependencyOf` on depended skills. +- **Canonical vs owned** — Lightspeed and Security use `mcpserver:redhat/...`; do not register duplicates in `mcps/`. +- **Unregistered packs** — `rh-developer`, `rh-ai-engineer`, `rh-automation` exist on disk but are not in root Location until explicitly added. + +## Example usage + +```bash +# Roster: skills on disk missing from Location (example: rh-sre) +comm -23 \ + <(find rh-sre/skills -name SKILL.md | sed 's|.*/skills/||;s|/SKILL.md||' | sort) \ + <(grep -oP 'skills/\K[^/]+(?=/catalog-info)' rh-sre/catalog-info.yaml | sort) + +# Tier 1 lint for this maintenance skill +uv run python scripts/validate_skills_tier1.py .claude/skills/compass-manifest-maintenance/SKILL.md + +# Full repo validation (no Compass CI yet) +make validate +``` + +Audit all four registered packs: + +```bash +for pack in ocp-admin rh-sre rh-virt rh-basic; do + echo "=== $pack ===" + comm -23 \ + <(find "$pack/skills" -name SKILL.md 2>/dev/null | sed 's|.*/skills/||;s|/SKILL.md||' | sort) \ + <(grep -oP 'skills/\K[^/]+(?=/catalog-info)' "$pack/catalog-info.yaml" 2>/dev/null | sort) +done +``` diff --git a/.claude/skills/compass-manifest-maintenance/assets/pack-location.yaml b/.claude/skills/compass-manifest-maintenance/assets/pack-location.yaml new file mode 100644 index 00000000..62891971 --- /dev/null +++ b/.claude/skills/compass-manifest-maintenance/assets/pack-location.yaml @@ -0,0 +1,20 @@ +# Template: /catalog-info.yaml (Location) +apiVersion: backstage.io/v1alpha1 +kind: Location +metadata: + name: + title: Agentic Pack + description: > + Points to all AI skill catalog entities in the agentic pack. + annotations: + agentic-plugins.redhat.com/version: "1.0" + agentic-plugins.redhat.com/repo: "agentic-plugins" + agentic.redhat.com/lola-module: "true" + agentic.redhat.com/lola-module-name: + agentic.redhat.com/repository: https://github.com/RHEcosystemAppEng/agentic-plugins + agentic.redhat.com/path: +spec: + targets: + - ./-plugin.yaml + - ./skills//catalog-info.yaml + # List every skill manifest under skills/ diff --git a/.claude/skills/compass-manifest-maintenance/assets/plugin-catalog-info.yaml b/.claude/skills/compass-manifest-maintenance/assets/plugin-catalog-info.yaml new file mode 100644 index 00000000..6ad07267 --- /dev/null +++ b/.claude/skills/compass-manifest-maintenance/assets/plugin-catalog-info.yaml @@ -0,0 +1,42 @@ +# Template: /-plugin.yaml +# Replace , title, description, tags, disciplines, categories, dependencyOf, dependsOn (MCP union). +apiVersion: backstage.io/v1alpha1 +kind: AiResource +metadata: + name: + namespace: ai5-marketplace + title: + description: > + + tags: + - ai-skill + - + annotations: + agentic-plugins.redhat.com/version: "1.0" + agentic-plugins.redhat.com/repo: "agentic-plugins" + agentic.redhat.com/lola-module: "true" + agentic.redhat.com/lola-module-name: + agentic.redhat.com/repository: https://github.com/RHEcosystemAppEng/agentic-plugins + agentic.redhat.com/path: + github.com/project-slug: RHEcosystemAppEng/agentic-plugins + links: + - url: https://github.com/RHEcosystemAppEng/agentic-plugins + title: Source Repository + icon: github +spec: + type: plugin + lifecycle: development + owner: group:redhat/ai5-marketplace + system: default/agentic-plugins + disciplines: + - + categories: + - + agents: [] + dependsOn: + # Union of mcpserver refs used by any skill in this pack (omit if none) + # - mcpserver:ai5-marketplace/ + # - mcpserver:redhat/ + dependencyOf: + - airesource:ai5-marketplace/ + # Every skill in the pack — bidirectional with skill dependsOn plugin diff --git a/.claude/skills/compass-manifest-maintenance/assets/skill-catalog-info.yaml b/.claude/skills/compass-manifest-maintenance/assets/skill-catalog-info.yaml new file mode 100644 index 00000000..29852449 --- /dev/null +++ b/.claude/skills/compass-manifest-maintenance/assets/skill-catalog-info.yaml @@ -0,0 +1,36 @@ +# Template: skills//catalog-info.yaml +# Replace , , title, description, tags, disciplines, categories, dependsOn. +apiVersion: backstage.io/v1alpha1 +kind: AiResource +metadata: + name: + namespace: ai5-marketplace + title: + description: > + + labels: + distribution: external + annotations: + backstage.io/source-location: >- + url:https://github.com/RHEcosystemAppEng/agentic-plugins/blob/main//skills//SKILL.md + tags: + - ai-skill + - + links: + - url: https://github.com/RHEcosystemAppEng/agentic-plugins + title: Source Repository + icon: github +spec: + type: skill + lifecycle: beta + owner: group:redhat/ai5-marketplace + disciplines: + - + categories: + - + agents: [] + dependsOn: + - airesource:ai5-marketplace/ + # Add mcpserver: and airesource: (other skills) only when SKILL.md uses them + dependencyOf: [] + # dependencyOf: list orchestration skills that dependsOn this skill (COMPASS-1288) diff --git a/.claude/skills/compass-manifest-maintenance/references/mcp-mapping.md b/.claude/skills/compass-manifest-maintenance/references/mcp-mapping.md new file mode 100644 index 00000000..9265ebc3 --- /dev/null +++ b/.claude/skills/compass-manifest-maintenance/references/mcp-mapping.md @@ -0,0 +1,50 @@ +# MCP mapping: mcps.json → Compass entity refs + +Map **only** MCP servers a skill actually uses. Derive usage from `SKILL.md` `allowed-tools`, `Required MCP Servers`, and workflow MCP tool names — not from copying another skill's manifest. + +## Owned MCP servers (registered in `mcps/`) + +| `mcps.json` key | Tool / signal hints | Compass entity ref | +|-----------------|---------------------|-------------------| +| `openshift-self-managed` | Assisted Installer self-managed API | `mcpserver:ai5-marketplace/assisted-installer` | +| `openshift-ocm-managed` | OCM / ROSA / managed clusters | `mcpserver:ai5-marketplace/assisted-installer` | +| `openshift-administration` | Kubernetes/OpenShift cluster ops (`configuration_*`, `nodes_*`, etc.) | `mcpserver:ai5-marketplace/openshift-mcp-server` | +| `openshift-virtualization` | KubeVirt VM tools | `mcpserver:ai5-marketplace/openshift-mcp-server` | +| `openshift` | Generic OpenShift MCP (other packs) | `mcpserver:ai5-marketplace/openshift-mcp-server` | +| `aap-mcp-job-management` | `controller.*`, `eda.*`, job/workflow tools | `mcpserver:ai5-marketplace/ansible-automation-platform` | +| `aap-mcp-inventory-management` | `controller.inventories_*`, `controller.hosts_*`, `controller.groups_*` | `mcpserver:ai5-marketplace/ansible-automation-platform` | + +## Canonical MCP servers (not duplicated in `mcps/`) + +| `mcps.json` key | Tool / signal hints | Compass entity ref | +|-----------------|---------------------|-------------------| +| `lightspeed-mcp` | `vulnerability__*`, `inventory__*`, `get_mcp_version` (Lightspeed) | `mcpserver:redhat/red-hat-lightspeed-mcp-server` | +| `red-hat-security` | Red Hat Security MCP / CVE advisory tools | `mcpserver:redhat/security-mcp-server` | + +## AAP tool prefix quick reference + +If `allowed-tools` includes any of these prefixes, the skill uses **ansible-automation-platform**: + +- `controller.` +- `gateway.` +- `eda.` +- `galaxy.` +- `lightspeed.aap_rag_search` + +## No MCP manifest entry + +Skills that use only scripts, `WebFetch`, or public APIs (no MCP tools in `allowed-tools` and no `Required MCP Servers`) should have **no** `mcpserver:` in `dependsOn`. Examples: ocp-admin security-validation skills (`container-cve-validator`, `coreos-cve-validator`, `cve-recon`, `image-inspect`). + +## Plugin `dependsOn` MCP list + +The pack plugin's `dependsOn` MCP entries = **union** of all `mcpserver:` refs across every skill manifest in that pack (not every key in `mcps.json`). + +## Owned MCP manifest files + +| Compass name | File | +|--------------|------| +| `openshift-mcp-server` | `mcps/openshift-mcp-server.yaml` | +| `assisted-installer` | `mcps/assisted-installer.yaml` | +| `ansible-automation-platform` | `mcps/ansible-automation-platform.yaml` | + +When a skill adds or removes an MCP `dependsOn`, update the corresponding MCP file's `dependencyOf` list. diff --git a/.claude/skills/compass-manifest-maintenance/references/relationship-rules.md b/.claude/skills/compass-manifest-maintenance/references/relationship-rules.md new file mode 100644 index 00000000..573fa288 --- /dev/null +++ b/.claude/skills/compass-manifest-maintenance/references/relationship-rules.md @@ -0,0 +1,63 @@ +# Compass relationship rules (agentic-plugins) + +## COMPASS-1288 bidirectional policy + +Compass does **not** auto-generate inverse relations for custom kinds (`AiResource`, `MCPServer`). Every relationship must be declared on **both sides**: + +| Origin | Field | Target | Inverse on target | +|--------|-------|--------|-------------------| +| Skill | `dependsOn` | Plugin | Plugin `dependencyOf` skill | +| Skill | `dependsOn` | MCP | MCP `dependencyOf` skill | +| Skill | `dependsOn` | Other skill | Other skill `dependencyOf` orchestrator | +| Plugin | `dependsOn` | MCP | MCP `dependencyOf` plugin | +| MCP | `dependsOn` | System | System `dependencyOf` MCP | + +**Exception:** Plugin and owned MCP → System use `spec.system: default/agentic-plugins`. Compass generates `partOf` automatically. Do **not** add `dependsOn: system:default/agentic-plugins` on plugins (redundant). + +## What does NOT work for custom kinds + +- `partOf` / `hasPart` on `AiResource` or `MCPServer` — stored in spec but **not** in the relation graph (validated Aug 2026). +- Use `dependsOn` / `dependencyOf` for all membership and technical dependencies. + +## Entity reference formats + +| Entity | Ref format | +|--------|------------| +| Skill | `airesource:ai5-marketplace/` | +| Pack plugin | `airesource:ai5-marketplace/` | +| Owned MCP | `mcpserver:ai5-marketplace/` | +| Canonical MCP | `mcpserver:redhat/` | +| System | `default/agentic-plugins` (in `spec.system` only) | + +All skills, plugins, and owned MCPs use `metadata.namespace: ai5-marketplace`. + +## Files to touch when adding a skill + +1. `skills//catalog-info.yaml` — new or updated entity +2. `/catalog-info.yaml` — Location `targets` entry +3. `/-plugin.yaml` — `dependencyOf` skill +4. Each `mcps/*.yaml` referenced — `dependencyOf` skill (and plugin if plugin depends on MCP) +5. Each depended-on skill manifest — `dependencyOf` orchestrator (skill→skill) +6. Reconcile plugin `dependsOn` MCP union if MCP usage changed pack-wide + +## Files to touch when adding a pack + +1. `/-plugin.yaml` +2. `/catalog-info.yaml` +3. Root `catalog-info.yaml` — add pack Location target +4. `system.yaml` — `dependencyOf` plugin entry +5. Register owned MCPs in `mcps/` if new (and `mcps/catalog-info.yaml`, `system.yaml` for MCP) + +## Orchestration skill detection + +Add skill→skill `dependsOn` when `SKILL.md` documents: + +- `Execute the `/other-skill` skill` +- Skill tool invocation of another skill in workflow +- Explicit prerequisite validator skills (`/mcp-lightspeed-validator`, etc.) + +Do **not** infer orchestration from `AGENTS.md` routing alone. + +## Registered packs (Compass Location in root) + +Currently indexed: `ocp-admin`, `rh-sre`, `rh-virt`, `rh-basic`. Packs on disk without root Location targets (`rh-developer`, `rh-ai-engineer`, `rh-automation`) are out of scope until added to root `catalog-info.yaml`. diff --git a/CLAUDE.md b/CLAUDE.md index 6790a9a9..79f3f679 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -304,10 +304,9 @@ last_updated: YYYY-MM-DD - Dependencies declaration 4. Include concrete examples and complete error handling 5. Update the pack's `AGENTS.md` intent routing table to include the new skill -6. Create `skills//catalog-info.yaml` Compass manifest (see "Adding Compass Manifests for a New Skill") -7. Add the skill's `catalog-info.yaml` as a target in the pack's `catalog-info.yaml` Location -8. Test with `Skill` tool invocation -9. Validate with `uv run python scripts/validate_skills_tier1.py /skills//SKILL.md` +6. Run **compass-manifest-maintenance** (`.claude/skills/compass-manifest-maintenance/`) to create or update Compass manifests — skill `catalog-info.yaml`, pack Location targets, plugin/MCP inverse `dependencyOf` (see "Adding Compass Manifests for a New Skill") +7. Test with `Skill` tool invocation +8. Validate with `uv run python scripts/validate_skills_tier1.py /skills//SKILL.md` **Collection-Specific Standards:** - **rh-virt**: Follow `rh-virt/SKILL_TEMPLATE.md` for enhanced quality standards including mandatory Common Issues and Example Usage sections From 89794ec6348c0b0a3f54abed6bd543377be79482 Mon Sep 17 00:00:00 2001 From: rhartuv Date: Thu, 20 Aug 2026 14:37:00 +0300 Subject: [PATCH 2/5] fix: removed the static mcp mapping tables --- .../references/mcp-mapping.md | 77 ++++++++++--------- 1 file changed, 42 insertions(+), 35 deletions(-) diff --git a/.claude/skills/compass-manifest-maintenance/references/mcp-mapping.md b/.claude/skills/compass-manifest-maintenance/references/mcp-mapping.md index 9265ebc3..1f398ec7 100644 --- a/.claude/skills/compass-manifest-maintenance/references/mcp-mapping.md +++ b/.claude/skills/compass-manifest-maintenance/references/mcp-mapping.md @@ -1,50 +1,57 @@ -# MCP mapping: mcps.json → Compass entity refs +# Deriving MCP `dependsOn` for skill manifests -Map **only** MCP servers a skill actually uses. Derive usage from `SKILL.md` `allowed-tools`, `Required MCP Servers`, and workflow MCP tool names — not from copying another skill's manifest. +Map **only** MCP servers the skill **actually uses**. Never copy a sibling manifest and never declare every key in `/mcps.json`. -## Owned MCP servers (registered in `mcps/`) +## Step 1 — Detect MCP usage in the skill -| `mcps.json` key | Tool / signal hints | Compass entity ref | -|-----------------|---------------------|-------------------| -| `openshift-self-managed` | Assisted Installer self-managed API | `mcpserver:ai5-marketplace/assisted-installer` | -| `openshift-ocm-managed` | OCM / ROSA / managed clusters | `mcpserver:ai5-marketplace/assisted-installer` | -| `openshift-administration` | Kubernetes/OpenShift cluster ops (`configuration_*`, `nodes_*`, etc.) | `mcpserver:ai5-marketplace/openshift-mcp-server` | -| `openshift-virtualization` | KubeVirt VM tools | `mcpserver:ai5-marketplace/openshift-mcp-server` | -| `openshift` | Generic OpenShift MCP (other packs) | `mcpserver:ai5-marketplace/openshift-mcp-server` | -| `aap-mcp-job-management` | `controller.*`, `eda.*`, job/workflow tools | `mcpserver:ai5-marketplace/ansible-automation-platform` | -| `aap-mcp-inventory-management` | `controller.inventories_*`, `controller.hosts_*`, `controller.groups_*` | `mcpserver:ai5-marketplace/ansible-automation-platform` | +From `/skills//SKILL.md`: -## Canonical MCP servers (not duplicated in `mcps/`) +- `allowed-tools` in frontmatter (tool names / prefixes) +- `Required MCP Servers` / `Required MCP Tools` in the body +- Workflow steps that name an MCP server key or tool -| `mcps.json` key | Tool / signal hints | Compass entity ref | -|-----------------|---------------------|-------------------| -| `lightspeed-mcp` | `vulnerability__*`, `inventory__*`, `get_mcp_version` (Lightspeed) | `mcpserver:redhat/red-hat-lightspeed-mcp-server` | -| `red-hat-security` | Red Hat Security MCP / CVE advisory tools | `mcpserver:redhat/security-mcp-server` | +If none of the above reference MCP tools → **no** `mcpserver:` in `dependsOn` (script-only, `WebFetch`, or public API skills). -## AAP tool prefix quick reference +## Step 2 — Match usage to `mcps.json` keys -If `allowed-tools` includes any of these prefixes, the skill uses **ansible-automation-platform**: +Read `/mcps.json`. Note which **server keys** the skill documents (e.g. `openshift-administration`, `lightspeed-mcp`, `aap-mcp-job-management`). -- `controller.` -- `gateway.` -- `eda.` -- `galaxy.` -- `lightspeed.aap_rag_search` +When `allowed-tools` lists tools but SKILL.md does not name a key, infer the server from context in the skill body (which MCP block documents those tools). -## No MCP manifest entry +## Step 3 — Resolve each key to a Compass entity ref -Skills that use only scripts, `WebFetch`, or public APIs (no MCP tools in `allowed-tools` and no `Required MCP Servers`) should have **no** `mcpserver:` in `dependsOn`. Examples: ocp-admin security-validation skills (`container-cve-validator`, `coreos-cve-validator`, `cve-recon`, `image-inspect`). +For each MCP the skill uses: -## Plugin `dependsOn` MCP list +### A. Owned MCP (manifest in this repo) -The pack plugin's `dependsOn` MCP entries = **union** of all `mcpserver:` refs across every skill manifest in that pack (not every key in `mcps.json`). +1. List `mcps/*.yaml` (exclude `catalog-info.yaml`). +2. Open manifests and read `metadata.name` and `metadata.namespace` (typically `ai5-marketplace`). +3. Entity ref: `mcpserver:/`. +4. **Deduplication:** Several `mcps.json` keys may share one Compass entity (same image/technology). Compare `mcps.json` entries (image URL, upstream repo in manifest `links`) to pick the correct owned manifest — do not create one ref per key if they map to the same `mcps/*.yaml`. +5. Confirm the skill’s tools appear in that manifest’s `spec.primitives` (or match the server described in SKILL.md) when ambiguous. -## Owned MCP manifest files +### B. Canonical MCP (registered upstream, not in `mcps/`) -| Compass name | File | -|--------------|------| -| `openshift-mcp-server` | `mcps/openshift-mcp-server.yaml` | -| `assisted-installer` | `mcps/assisted-installer.yaml` | -| `ansible-automation-platform` | `mcps/ansible-automation-platform.yaml` | +If the pack references an MCP that **no** file under `mcps/` covers: -When a skill adds or removes an MCP `dependsOn`, update the corresponding MCP file's `dependencyOf` list. +1. Search existing skill manifests in the same pack (or repo) for the same `mcps.json` key or the same upstream product. +2. Reuse the `mcpserver:` ref already used there (often `mcpserver:redhat/`). +3. Do **not** add a duplicate MCPServer manifest in `mcps/`. + +When unsure, grep the repo for the `mcps.json` key or tool prefix in other `catalog-info.yaml` files under the same pack. + +## Step 4 — Update inverse relations + +For each `mcpserver:` added to the skill’s `dependsOn`: + +- Add `airesource:ai5-marketplace/` to that MCP manifest’s `spec.dependencyOf` (owned MCPs only — canonical MCPs are maintained by their owners). + +## Step 5 — Plugin MCP union + +The pack plugin’s `dependsOn` MCP list = **union** of all `mcpserver:` refs across skill manifests in that pack — not the full set of keys in `mcps.json`. + +## Sanity checks + +- Fewer MCP refs than keys in `mcps.json` is normal (per-skill usage). +- More MCP refs than the skill uses is wrong (blanket template deps). +- Canonical refs (`mcpserver:redhat/...`) do not get new files under `mcps/`. From 9a809a788e2451a3c70bdc6a4a187eb90216989d Mon Sep 17 00:00:00 2001 From: rhartuv Date: Thu, 20 Aug 2026 14:51:43 +0300 Subject: [PATCH 3/5] fix: remove pr references --- .claude/skills/compass-manifest-maintenance/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/compass-manifest-maintenance/SKILL.md b/.claude/skills/compass-manifest-maintenance/SKILL.md index 9e0777b9..7c0a71ad 100644 --- a/.claude/skills/compass-manifest-maintenance/SKILL.md +++ b/.claude/skills/compass-manifest-maintenance/SKILL.md @@ -5,7 +5,7 @@ description: | - Adding or updating a skill and its Compass manifest - Adding a new pack to Compass registration - MCP usage or orchestration changed in SKILL.md - - Auditing bidirectional dependsOn/dependencyOf drift after PR #133 model + - Auditing bidirectional dependsOn/dependencyOf drift against repo Compass conventions File-based only: Read/Glob/Grep/Bash. For `.catalog/` marketplace metadata use create-collection. model: inherit @@ -107,7 +107,7 @@ Report violations with file path and fix per workflow §1. Do not weaken checks. ## Self-review checklist -- [ ] Skill manifest matches PR #133 field conventions (`agents: []`, `distribution: external`, `namespace: ai5-marketplace`). +- [ ] Skill manifest matches repo Compass conventions (`agents: []`, `labels.distribution: external`, `namespace: ai5-marketplace`, `owner: group:redhat/ai5-marketplace`). - [ ] MCP deps derived from `SKILL.md` usage, not copied from sibling skills. - [ ] Every new `dependsOn` has matching `dependencyOf` on the target entity. - [ ] Pack Location lists every skill manifest path. From a3fe4b110cba1b22f601d5131e3c593db70a238b Mon Sep 17 00:00:00 2001 From: rhartuv Date: Thu, 20 Aug 2026 15:13:38 +0300 Subject: [PATCH 4/5] fix: add missing Compass manifest for ocp-admin/network-policy-architect skill --- mcps/openshift-mcp-server.yaml | 1 + ocp-admin/catalog-info.yaml | 1 + ocp-admin/ocp-admin-plugin.yaml | 1 + .../catalog-info.yaml | 39 +++++++++++++++++++ 4 files changed, 42 insertions(+) create mode 100644 ocp-admin/skills/network-policy-architect/catalog-info.yaml diff --git a/mcps/openshift-mcp-server.yaml b/mcps/openshift-mcp-server.yaml index efd680da..a0b57ed8 100644 --- a/mcps/openshift-mcp-server.yaml +++ b/mcps/openshift-mcp-server.yaml @@ -102,6 +102,7 @@ spec: - system:default/agentic-plugins dependencyOf: - airesource:ai5-marketplace/cluster-report + - airesource:ai5-marketplace/network-policy-architect - airesource:ai5-marketplace/ocp-admin - airesource:ai5-marketplace/rh-virt - airesource:ai5-marketplace/vm-clone diff --git a/ocp-admin/catalog-info.yaml b/ocp-admin/catalog-info.yaml index adad806c..a59f882f 100644 --- a/ocp-admin/catalog-info.yaml +++ b/ocp-admin/catalog-info.yaml @@ -23,3 +23,4 @@ spec: - ./skills/coreos-cve-validator/catalog-info.yaml - ./skills/cve-recon/catalog-info.yaml - ./skills/image-inspect/catalog-info.yaml + - ./skills/network-policy-architect/catalog-info.yaml diff --git a/ocp-admin/ocp-admin-plugin.yaml b/ocp-admin/ocp-admin-plugin.yaml index ec128434..7d824969 100644 --- a/ocp-admin/ocp-admin-plugin.yaml +++ b/ocp-admin/ocp-admin-plugin.yaml @@ -47,3 +47,4 @@ spec: - airesource:ai5-marketplace/coreos-cve-validator - airesource:ai5-marketplace/cve-recon - airesource:ai5-marketplace/image-inspect + - airesource:ai5-marketplace/network-policy-architect diff --git a/ocp-admin/skills/network-policy-architect/catalog-info.yaml b/ocp-admin/skills/network-policy-architect/catalog-info.yaml new file mode 100644 index 00000000..d03aae3d --- /dev/null +++ b/ocp-admin/skills/network-policy-architect/catalog-info.yaml @@ -0,0 +1,39 @@ +apiVersion: backstage.io/v1alpha1 +kind: AiResource +metadata: + name: network-policy-architect + namespace: ai5-marketplace + title: Network Policy Architect + description: > + Design and validate Kubernetes NetworkPolicies following Zero Trust principles + (NIST SP 800-207). Two-tier analysis — architecture review then live cluster + verification — produces a verified implementation plan with apply-and-verify results. + labels: + distribution: external + annotations: + backstage.io/source-location: >- + url:https://github.com/RHEcosystemAppEng/agentic-plugins/blob/main/ocp-admin/skills/network-policy-architect/SKILL.md + tags: + - ai-skill + - openshift + - security + - network-policy + - zero-trust + links: + - url: https://github.com/RHEcosystemAppEng/agentic-plugins + title: Source Repository + icon: github +spec: + type: skill + lifecycle: beta + owner: group:redhat/ai5-marketplace + disciplines: + - security + - platform-engineering + categories: + - security + - network-segmentation + agents: [] + dependsOn: + - airesource:ai5-marketplace/ocp-admin + - mcpserver:ai5-marketplace/openshift-mcp-server From 445a70e886dfbad7b4250670d8d9d982179ae518 Mon Sep 17 00:00:00 2001 From: rhartuv Date: Sun, 23 Aug 2026 12:10:11 +0300 Subject: [PATCH 5/5] fix: fix validate skills tier2 --- .../compass-manifest-maintenance/SKILL.md | 45 ++++++++++++++++--- 1 file changed, 40 insertions(+), 5 deletions(-) diff --git a/.claude/skills/compass-manifest-maintenance/SKILL.md b/.claude/skills/compass-manifest-maintenance/SKILL.md index 7c0a71ad..adeb3334 100644 --- a/.claude/skills/compass-manifest-maintenance/SKILL.md +++ b/.claude/skills/compass-manifest-maintenance/SKILL.md @@ -8,13 +8,15 @@ description: | - Auditing bidirectional dependsOn/dependencyOf drift against repo Compass conventions File-based only: Read/Glob/Grep/Bash. For `.catalog/` marketplace metadata use create-collection. + + NOT for: `.catalog/` metadata (use create-collection) or automated Compass registration. model: inherit color: magenta license: Apache-2.0 allowed-tools: Read Glob Grep Bash --- -# Compass manifest maintenance +# /compass-manifest-maintenance Skill **Audience:** Maintainers updating `catalog-info.yaml` manifests for Red Hat Compass (Backstage) registration. @@ -22,25 +24,39 @@ allowed-tools: Read Glob Grep Bash ## Prerequisites +**Required MCP Servers:** None — file-based skill. Do not use Compass MCP tools (`validate-entity`, `register-entity`, `get-catalog-entity`, `query-entity-graph`). + - Repository root as cwd. - Read [CLAUDE.md](../../CLAUDE.md) Compass / Backstage Manifests section. - Read [references/relationship-rules.md](references/relationship-rules.md) and [references/mcp-mapping.md](references/mcp-mapping.md). - Templates: [assets/](assets/). -**Do not use** Compass MCP tools (`validate-entity`, `register-entity`, `get-catalog-entity`, `query-entity-graph`). Validation is structural (roster + inverse ref checks) and optional human Compass UI review after merge. +**Verification:** +```bash +test -f CLAUDE.md && echo "✓ repo root" || echo "✗ wrong directory" +``` + +**Human Notification Protocol:** If drift audit finds violations, report file path and fix per workflow §1. + +**Security:** Never display or expose credentials or token values. -## When to Use +## When to Use This Skill +**Use when:** - New skill needs `skills//catalog-info.yaml` and Location / inverse updates. - Skill `allowed-tools` or orchestration changed → MCP or skill `dependsOn` must change. - New pack registered in Compass (plugin, Location, root index, `system.yaml`). - Drift audit: skill on disk without manifest, stale `dependencyOf`, or dangling entity refs. - After `agentic-contribution-skill` creates a skill (run before opening PR). -**Do not use for:** `.catalog/collection.yaml` (use **create-collection**), generic Compass platform tasks, or automated Compass registration. +**Do not use when:** `.catalog/collection.yaml` (use **create-collection** instead), generic Compass platform tasks, or automated Compass registration. ## Workflow +**MCP Tool:** None — file-based; uses Read, Glob, Grep, Bash only (see `allowed-tools` in frontmatter). + +**Parameters:** N/A — no MCP tools; inputs are ``, ``, and on-disk manifest paths. + ### 1. Add or update a skill manifest 1. **Resolve** `` and `` — confirm `/skills//SKILL.md` exists. @@ -105,6 +121,11 @@ Report violations with file path and fix per workflow §1. Do not weaken checks. 3. Tier 1 on this skill if edited: `uv run python scripts/validate_skills_tier1.py .claude/skills/compass-manifest-maintenance/SKILL.md`. 4. Post-merge: maintainer may register in Compass UI manually (out of scope for this skill). +**Error Handling:** +- If skill on disk has no manifest → create from `assets/skill-catalog-info.yaml` and add Location target. +- If inverse `dependencyOf` missing on plugin or MCP → update per [relationship-rules.md](references/relationship-rules.md). +- If MCP ref cannot be resolved → grep pack manifests; do not invent new `mcpserver:` refs. + ## Self-review checklist - [ ] Skill manifest matches repo Compass conventions (`agents: []`, `labels.distribution: external`, `namespace: ai5-marketplace`, `owner: group:redhat/ai5-marketplace`). @@ -116,8 +137,22 @@ Report violations with file path and fix per workflow §1. Do not weaken checks. ## Dependencies +### Required MCP Servers + +None — file-based manifest maintenance only. + +### Required MCP Tools + +None — uses Read, Glob, Grep, Bash. + +### Related Skills + +- **create-collection** — for `.catalog/` marketplace metadata (not Compass manifests) +- **agentic-contribution-skill** — run before this skill when creating a new skill + +### Reference Documentation + - [CLAUDE.md](../../CLAUDE.md) — entity kinds, namespaces, reference formats -- **create-collection** — `.catalog/` marketplace metadata (sibling under `.claude/skills/`) - [references/relationship-rules.md](references/relationship-rules.md) - [references/mcp-mapping.md](references/mcp-mapping.md)