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.

RedTanny

Do not hardcode lifecycle:

if a New skill in an existing pack:
you can take as default value the spec.lifecycle from the parent *-plugin.yaml.
human in the loop --> you can ask if he wants to change for example
if plugin is beta so he can downgrade to development ( you cannot have a skill with beta value and plugin with development )

New pack: set the default level to development

rhartuv · 2026-09-06T07:53:45Z

Do not hardcode lifecycle:

if a New skill in an existing pack: you can take as default value the spec.lifecycle from the parent *-plugin.yaml. human in the loop --> you can ask if he wants to change for example if plugin is beta so he can downgrade to development ( you cannot have a skill with beta value and plugin with development )

New pack: set the default level to development

@RedTanny Done. Thank you

rhartuv · 2026-09-07T10:48:40Z

@r2dedios @RedTanny PTAL, Thank you

r2dedios

Just a tiny fix to apply. The rest looks great.

r2dedios · 2026-09-07T10:48:59Z

+      icon: github
+spec:
+  type: skill
+  lifecycle: beta


Suggested change

lifecycle: beta

lifecycle: development

Since the plugin lifecycle is development, this skills should have the same value

Right! Thanks. A new ticket was opened specifically to handle this, and I'll take care of it.
Jira

r2dedios

LGTM!. Let's wait for @RedTanny feedbackt oo

RedTanny

LGTM

RedTanny · 2026-09-07T11:03:33Z

+      title: Source Repository
+      icon: github
+spec:
+  type: plugin


New skill in an existing pack: copy spec.lifecycle from the parent *-plugin.yaml. Do not hardcode lifecycle: beta in assets/skill-catalog-info.yaml, the compass-manifest-maintenance workflow, or CLAUDE.md.

New pack: assets/plugin-catalog-info.yaml and the skill template must use the same default (development is the safer new-pack value).

@RedTanny I will take care of it in a separate PR for that ticket: https://redhat.atlassian.net/browse/APPENG-6307
Ok ?

@rhartuv
sure no problem

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

Closed

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 Outdated

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

RedTanny requested changes Sep 5, 2026

View reviewed changes

fix: change hardcode lifecycle

12d8efb

rhartuv requested a review from RedTanny September 7, 2026 07:05

r2dedios previously approved these changes Sep 7, 2026

View reviewed changes

fix: update network-policy-architect lifecycle

f5bc066

rhartuv dismissed r2dedios’s stale review via f5bc066 September 7, 2026 10:53

rhartuv requested a review from r2dedios September 7, 2026 10:55

r2dedios approved these changes Sep 7, 2026

View reviewed changes

RedTanny approved these changes Sep 7, 2026

View reviewed changes

rhartuv merged commit 8a0b1d5 into RHEcosystemAppEng:main Sep 7, 2026
4 checks passed


		## 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!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

RedTanny left a comment

Choose a reason for hiding this comment

Uh oh!

rhartuv commented Sep 6, 2026

Uh oh!

rhartuv commented Sep 7, 2026

Uh oh!

r2dedios left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

r2dedios left a comment

Choose a reason for hiding this comment

Uh oh!

RedTanny left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rhartuv commented Aug 20, 2026 •

edited by r2dedios

Loading

rhartuv commented Aug 20, 2026 •

edited

Loading

rhartuv commented Aug 20, 2026 •

edited

Loading