feat: add skill to author and maintain Compass manifests for agentic packs by rhartuv · Pull Request #154 · RHEcosystemAppEng/agentic-plugins

rhartuv · 2026-08-20T07:49:01Z

Summary

Add compass-manifest-maintenance Claude skill to author and maintain Compass catalog-info.yaml manifests for agentic packs.

Workflow for new/updated skills, new packs, and structural drift audits
MCP mapping reference (mcps.json keys → owned vs canonical Compass refs)
Relationship rules reference (COMPASS-1288, file touch matrix)
YAML templates for skill, plugin, and pack Location manifests
File-based validation only (no Compass MCP)
Cross-links from CLAUDE.md and agentic-contribution-skill

Add missing Compass manifest for ocp-admin/skills/network-policy-architect, closing a pre-existing catalog gap identified during PR #154 review.

Create catalog-info.yaml (AiResource, namespace: ai5-marketplace, type: skill)
Register in pack Location and declare bidirectional relations (skill ↔ plugin, skill ↔ openshift-mcp-server) per COMPASS-1288

Test plan

uv run python scripts/validate_skills_tier1.py .claude/skills/compass-manifest-maintenance/SKILL.md passes
Roster audit: rh-sre, rh-virt, rh-basic - no skills missing from Location targets
Invoke skill: “Audit rh-sre Compass manifest drift” - expect zero violations
Invoke skill: “What files would change if remediation added dependsOn on a new skill?” - expect orchestrator + target skill dependencyOf (+ MCP if applicable)
make validate passes

Closes APPENG-6131
Closes APPENG-6002
Implements #151

…packs

rhartuv · 2026-08-20T07:50:12Z

Note: ocp-admin/skills/network-policy-architect has no catalog-info.yaml (pre-existing gap). @r2dedios

r2dedios · 2026-08-20T07:55:38Z

True! Good Catch. I'm creating another task for solving this gap and assigning it to you. Good chance for testing the skill you're working on :)

rhartuv · 2026-08-20T09:59:15Z

True! Good Catch. I'm creating another task for solving this gap and assigning it to you. Good chance for testing the skill you're working on :)

https://redhat.atlassian.net/browse/APPENG-6131

dmartinol · 2026-08-20T10:33:19Z

+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).


isn't there any drift that we can prevent adding a CI validation script? (we already have many iof them in the scripts/ folder)

Makes sense. I figured this was out of scope for this PR since it's just the skill and docs, but I can add a scripts/validate_compass_manifests.py script for it. Let me know if you'd rather I include it here or open a separate ticket.

…ect skill

operetz-rh

@r2dedios @rhartuv
LGTM

r2dedios

Good work, just a few tiny things to review before merging

Additionally, what was the result of @dmartinol's feedback? Did we created another thicket for solving what he identified? If not, I think we can include that fix on this PR too

r2dedios · 2026-09-02T09:53:48Z

+
+## COMPASS-1288 bidirectional policy
+
+Compass does **not** auto-generate inverse relations for custom kinds (`AiResource`, `MCPServer`). Every relationship must be declared on **both sides**:


This is correct for now, However we are expecting Compass team to solve this issue on the future. That means we should revisit this once it is fixed.

r2dedios · 2026-09-02T09:54:22Z

+
+**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


Same here. This should be fixed in the near future

r2dedios · 2026-09-02T10:01:33Z

This info is duplicated on https://github.com/RHEcosystemAppEng/agentic-plugins/pull/154/changes#diff-ae021437cbb63300a76aeb1d8359a7a86ad0d2839100ffc602026e4141bbb582R7-R15

It might make sense to remove from CLAUDE.md and left in only in the references/relationship-rules.md

r2dedios · 2026-09-02T10:06:06Z

+
+6. **Reconcile plugin MCP deps** — plugin `dependsOn` = union of all `mcpserver:` refs across pack skill manifests.
+
+### 2. Add a new pack (Compass registration)


Suggested change

### 2. Add a new pack (Compass registration)

### 2. Register a new pack in Compass

I would change this title to avoid confussions between creating a new agentic-plugin and docuemnting a plugin for registering it in Compass

rhartuv · 2026-09-02T11:41:41Z

Good work, just a few tiny things to review before merging

Additionally, what was the result of @dmartinol's feedback? Did we created another thicket for solving what he identified? If not, I think we can include that fix on this PR too

@r2dedios Thanks.
@dmartinol hasn't decided on this yet. What's your recommendation?

r2dedios · 2026-09-02T12:57:44Z

Good work, just a few tiny things to review before merging
Additionally, what was the result of @dmartinol's feedback? Did we created another thicket for solving what he identified? If not, I think we can include that fix on this PR too

@r2dedios Thanks. @dmartinol hasn't decided on this yet. What's your recommendation?

I agree with @dmartinol about the validation script. Appart of more effiente usage of the LLM, there would be a standard procedure (script) to evaluate the Compass Manifests. I also noticed the Compass MCP server has a tool for validating Compass entities, so maybe makes more sense to use it instead of another script

rhartuv · 2026-09-02T14:45:20Z

Good work, just a few tiny things to review before merging
Additionally, what was the result of @dmartinol's feedback? Did we created another thicket for solving what he identified? If not, I think we can include that fix on this PR too

@r2dedios Thanks. @dmartinol hasn't decided on this yet. What's your recommendation?

I agree with @dmartinol about the validation script. Appart of more effiente usage of the LLM, there would be a standard procedure (script) to evaluate the Compass Manifests. I also noticed the Compass MCP server has a tool for validating Compass entities, so maybe makes more sense to use it instead of another script

Agree. Added scripts/validate_compass_manifests.py and hooked it into make validate, make validate-structure, and Tier 2 CI.

feat: add skill to author and maintain Compass manifests for agentic …

c625f31

…packs

rhartuv self-assigned this Aug 20, 2026

rhartuv added the skills label Aug 20, 2026

r2dedios linked an issue Aug 20, 2026 that may be closed by this pull request

Create a skill to automate Compass catalog-info.yaml generation #151

Open

rhartuv marked this pull request as ready for review August 20, 2026 09:54

rhartuv requested review from TomerFi, dmartinol, ikrispin, nemerna and r2dedios as code owners August 20, 2026 09:54

dmartinol reviewed Aug 20, 2026

View reviewed changes

Comment thread .claude/skills/compass-manifest-maintenance/references/mcp-mapping.md Outdated

dmartinol reviewed Aug 20, 2026

View reviewed changes

rhartuv added 4 commits August 20, 2026 14:37

fix: removed the static mcp mapping tables

89794ec

fix: remove pr references

9a809a7

fix: add missing Compass manifest for ocp-admin/network-policy-archit…

a3fe4b1

…ect skill

fix: fix validate skills tier2

445a70e

operetz-rh reviewed Sep 1, 2026

View reviewed changes

Comment thread CLAUDE.md Outdated

operetz-rh reviewed Sep 1, 2026

View reviewed changes

Comment thread CLAUDE.md Outdated

fix: amount of skills

fabfd5b

operetz-rh reviewed Sep 1, 2026

View reviewed changes

Comment thread CLAUDE.md

operetz-rh previously approved these changes Sep 1, 2026

View reviewed changes

r2dedios requested changes Sep 2, 2026

View reviewed changes

fix: review fixes

62a2f6c

rhartuv dismissed operetz-rh’s stale review via 62a2f6c September 2, 2026 11:39

feat: add a script to evaluate the Compass Manifests

00389a4

rhartuv requested a review from r2dedios September 3, 2026 07:47


		## COMPASS-1288 bidirectional policy

		Compass does not auto-generate inverse relations for custom kinds (`AiResource`, `MCPServer`). Every relationship must be declared on both sides:


		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


		6. Reconcile plugin MCP deps — plugin `dependsOn` = union of all `mcpserver:` refs across pack skill manifests.

		### 2. Add a new pack (Compass registration)

	### 2. Add a new pack (Compass registration)
	### 2. Register a new pack in Compass

Uh oh!

Conversation

rhartuv commented Aug 20, 2026 • edited by r2dedios Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

rhartuv commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

r2dedios commented Aug 20, 2026

Uh oh!

rhartuv commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

dmartinol Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

rhartuv Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

operetz-rh left a comment

Choose a reason for hiding this comment

Uh oh!

r2dedios left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

r2dedios Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

r2dedios Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

r2dedios Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

r2dedios Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

rhartuv commented Sep 2, 2026

Uh oh!

r2dedios commented Sep 2, 2026

Uh oh!

rhartuv commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rhartuv commented Aug 20, 2026 •

edited by r2dedios

Loading

rhartuv commented Aug 20, 2026 •

edited

Loading

rhartuv commented Aug 20, 2026 •

edited

Loading