Skip to content

SKILL.md

Latest commit

 

History

History
207 lines (152 loc) · 7.3 KB

SKILL.md

File metadata and controls

207 lines (152 loc) · 7.3 KB
Raw
name overlay
description Manages the rhdh-plugin-export-overlays repository — onboards plugins to the Extensions Catalog, updates plugin versions, generates and audits Package metadata, fixes overlay build failures, triages and analyzes PRs, triggers publishes, and manages plugin workspaces. Use when working with overlays, importing plugins, generating metadata, auditing metadata, fixing metadata inconsistencies, debugging CI, checking PRs, or bumping versions.

<path_resolution> All relative paths in this skill (scripts/, references/, workflows/, templates/) are relative to this SKILL.md file's directory. Derive the skill root from the absolute path used to read this file. For example, if this file was read from /Users/me/.agents/skills/overlay/SKILL.md, then scripts/derive-metadata.py resolves to /Users/me/.agents/skills/overlay/scripts/derive-metadata.py. Always use absolute paths when invoking scripts or reading reference files. </path_resolution>

<shell_permissions> Prefer running gh api and gh search code as direct shell commands rather than via Python subprocess. Direct gh calls go through the user's command allowlist without triggering permission prompts. Python scripts that only do local work (file I/O, JSON processing, field derivation) also need no extra permissions. Only request full_network for Python scripts that internally spawn gh as a subprocess — the sandbox blocks network access from child processes. </shell_permissions>

<cli_setup> This skill uses the orchestrator CLI. Set up first:

RHDH=../rhdh/scripts/rhdh

Verify environment:

$RHDH

If needs_setup: true, run $RHDH doctor before proceeding. </cli_setup>

<essential_principles>

All plugin exports go through [rhdh-plugin-export-overlays](https://github.com/redhat-developer/rhdh-plugin-export-overlays). Each plugin lives in a workspace folder with `source.json` + `plugins-list.yaml`. CI handles the actual export - we define the configuration. Two Backstage version fields serve different purposes: - `source.json` → `repo-backstage-version` = upstream's **actual** version - `backstage.json` → `version` = our **override** for RHDH compatibility

Never confuse these. CI validates the source.json value matches upstream.

Always test with PR artifacts before merge using rhdh-local. OCI format: `oci:///

:pr___!` Success = plugin loads and attempts API calls (auth errors are expected without real credentials). When stuck, find a similar workspace and copy its patterns. AWS plugins → copy from `aws-ecs/` or `aws-codebuild/` Community plugins → copy from `backstage/` Check existing PRs for structure examples.

</essential_principles>

## Identify Task

What overlay task would you like to do?

Plugin Owner Tasks

For contributors managing their own plugin(s)

  1. Onboard a new plugin — Add upstream plugin to Extensions Catalog
  2. Update plugin version — Bump to newer upstream commit/tag
  3. Check plugin status — Verify health and compatibility
  4. Fix build failure — Debug CI/publish issues
  5. Generate or audit metadata — Add missing Package metadata or fix inconsistencies in existing metadata

Core Team Tasks

For COPE/Plugins team managing the overlay repository

  1. Triage overlay PRs — Prioritize open PRs by criticality
  2. Analyze specific PR — Check assignment, compatibility, merge readiness
  3. Trigger publish — Add /publish comment to PR(s)

Wait for response before proceeding.

### Plugin Owner Routes
Response Workflow
1, "onboard", "add", "new plugin", "import" workflows/onboard-plugin.md
2, "update", "bump", "upgrade", "version" workflows/update-plugin.md
3, "status", "check", "health" Run inline status checks
4, "fix", "debug", "failure", "error" workflows/fix-build.md
8, "metadata", "generate metadata", "add metadata", "audit", "audit metadata", "fix metadata", "check metadata", "validate metadata" workflows/generate-metadata.md

Core Team Routes

Response Workflow
5, "triage", "prioritize", "backlog" workflows/triage-prs.md
6, "analyze", "check PR", "PR #" workflows/analyze-pr.md
7, "publish", "trigger" Run inline publish trigger

After reading the workflow, follow it exactly.

<inline_status_check> For status checks, use the CLI:

$RHDH workspace list              # List all workspaces
$RHDH workspace status <name>     # Check specific workspace

Or run direct commands:

# Recent CI runs
gh run list --repo redhat-developer/rhdh-plugin-export-overlays --limit 5

# Open PRs for workspace
gh pr list --repo redhat-developer/rhdh-plugin-export-overlays --search "<name>"

</inline_status_check>

<inline_publish_trigger> For triggering publish on one or more PRs:

REPO="redhat-developer/rhdh-plugin-export-overlays"

# Single PR
gh pr comment <number> --repo $REPO --body "/publish"

# Check if publish already ran
gh pr view <number> --repo $REPO --json statusCheckRollup \
  --jq '.statusCheckRollup[] | select(.name | contains("publish"))'

Guards before triggering:

  1. PR is open (not closed/merged)
  2. No do-not-merge label
  3. Publish check not already successful

See ../rhdh/references/github-reference.md for full patterns. </inline_publish_trigger>

<reference_index> Overlay repo patterns: references/overlay-repo.md CI feedback interpretation: references/ci-feedback.md Metadata format: references/metadata-format.md PR label priorities: references/label-priority.md RHDH Local testing: references/rhdh-local.md

For GitHub/JIRA patterns: See ../rhdh/references/ </reference_index>

<workflows_index>

Plugin Owner Workflows

Workflow Purpose
onboard-plugin.md Full 6-phase process to add new plugin
update-plugin.md Bump to newer upstream version
fix-build.md Debug and resolve CI failures
generate-metadata.md Generate missing Package metadata and audit existing metadata for consistency

Core Team Workflows

Workflow Purpose
triage-prs.md Prioritize open PRs by criticality
analyze-pr.md Deep-dive on single PR (assignment, compat, readiness)
doctor.md Environment setup guidance
</workflows_index>

<templates_index>

Template Purpose
workspace-files.md source.json, plugins-list.yaml, backstage.json
</templates_index>

<success_criteria>

Plugin Owner Success

  • Plugin workspace created with correct structure
  • CODEOWNERS entry added for the workspace
  • CI passes (/publish succeeds)
  • Plugin tested locally with rhdh-local
  • PR merged to overlay repo
  • (Recommended) Activity logged via $RHDH log add

Core Team Success

  • PR backlog prioritized with actionable next steps
  • Stale PRs identified with suggested owners
  • Publish triggered on PRs needing it
  • Compatibility issues flagged before merge
  • (Recommended) Triage session logged, follow-ups tracked via $RHDH todo </success_criteria>