From a67ba9993244455d22e98ad7363c61c4193822fa Mon Sep 17 00:00:00 2001 From: r2dedios Date: Thu, 2 Jul 2026 13:25:49 +0200 Subject: [PATCH 1/2] minor fixes Signed-off-by: r2dedios --- .gitignore | 1 + CLAUDE.md | 2 +- CODEOWNERS | 23 ++--- CONTRIBUTION_PROTOCOL.md | 214 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 227 insertions(+), 13 deletions(-) create mode 100644 CONTRIBUTION_PROTOCOL.md diff --git a/.gitignore b/.gitignore index db5882e..06019b7 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,7 @@ ENV/ build/ develop-eggs/ dist/ +docs downloads/ eggs/ .eggs/ diff --git a/CLAUDE.md b/CLAUDE.md index 42b3079..6f95c7d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## What This Repository Is -This is a **skills source repository** — one of potentially many that feed into the [agentic-plugins-catalog](https://github.com/RHEcosystemAppEng/agentic-plugins-catalog). It contains agentic packs with skills, MCP server configurations, AI-optimized documentation, and catalog metadata for Red Hat platforms. +This is a **skills source repository** — one of potentially many that feed into the [agentic-catalog](https://github.com/RHEcosystemAppEng/agentic-catalog). It contains AI agentic packs with skills, MCP server configurations, AI-optimized documentation, and catalog metadata for Red Hat platforms. Contributors work here to create, improve, and validate skills. An internal process periodically fetches content from this repository (and others like it) to build the unified catalog and marketplace. **This repo does not serve the marketplace directly** — it is a source of skills that the catalog aggregates. diff --git a/CODEOWNERS b/CODEOWNERS index 63b4d5f..c9f6b61 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -8,20 +8,19 @@ * @r2dedios @dmartinol @ikrispin @nemerna # Pack owners -rh-sre/ @r2dedios -rh-developer/ @r2dedios -rh-virt/ @r2dedios -ocp-admin/ @r2dedios -rh-ai-engineer/ @r2dedios -rh-automation/ @r2dedios -rh-basic/ @r2dedios -rh-support-engineer/ @r2dedios +rh-sre/ @dmartinol +rh-developer/ @ikrispin +rh-virt/ @r2dedios +ocp-admin/ @r2dedios +rh-ai-engineer/ @dmartinol +rh-automation/ @dmartinol +rh-basic/ @dmartinol +rh-support-engineer/ @dmartinol # CI, scripts, and repo-wide config .github/ @r2dedios @dmartinol scripts/ @r2dedios @dmartinol -marketplace/ @r2dedios @dmartinol catalog/ @r2dedios @dmartinol -CLAUDE.md @r2dedios -SKILL_DESIGN_PRINCIPLES.md @r2dedios -CONTRIBUTING.md @r2dedios +CLAUDE.md @r2dedios @dmartinol +SKILL_DESIGN_PRINCIPLES.md @r2dedios @dmartinol +CONTRIBUTING.md @r2dedios @dmartinol diff --git a/CONTRIBUTION_PROTOCOL.md b/CONTRIBUTION_PROTOCOL.md new file mode 100644 index 0000000..b5f649b --- /dev/null +++ b/CONTRIBUTION_PROTOCOL.md @@ -0,0 +1,214 @@ +# Contribution Protocol + +> **Draft** — This document defines the end-to-end protocol for contributing to Red Hat Agentic Collections. Covers both direct contributions and federation of external repositories. Subject to change as the process matures. + +## Two Contribution Paths + +| | Direct Contribution | Federation | +|---|---|---| +| **Your code lives in** | This repository | Your repository | +| **Compliance level** | Strict (Tier 1 + Tier 2 mandatory) | Tier 1 mandatory, Tier 2 recommended | +| **Entry point** | `/agentic-contribution-skill` in Claude Code | PR adding module to marketplace YAML | +| **Review process** | PR with automated CI + maintainer review | PR with `federation` label → automated CI + maintainer review | +| **PR auto-assigned to** | Pack owner via CODEOWNERS | Maintainers | +| **You control** | Nothing after merge (maintainers own it) | Your repo, your pace, your releases | +| **Catalog appearance** | Immediate after merge | After registration PR merges + next build | + +Choose **direct contribution** when you want your skill to be part of the official collection with full maintainer support. Choose **federation** when you want to keep ownership of your code and release independently. + +--- + +## Path 1: Direct Contribution + +For adding skills or packs directly to this repository. + +### Process + +``` +Fork & clone → /agentic-contribution-skill → PR → CI validation → CODEOWNERS review → Merge +``` + +### Step 1: Setup + +1. Fork the repository on GitHub +2. Clone your fork locally +3. Open the project in Claude Code + +### Step 2: Create or Import + +Run `/agentic-contribution-skill` and choose a mode: + +- **Create**: Answer discovery questions → skill is generated, validated, and placed in the right pack +- **Import**: Point to an existing SKILL.md → the skill is analyzed, adapted to repo standards, and placed in the right pack + +The skill handles: +- Pack selection based on content analysis +- Structure and section generation following [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) +- CLAUDE.md intent routing update +- Tier 1 + Tier 2 validation +- Git workflow (branch, commit, push) + +### Step 3: Submit PR + +The skill can create the PR for you, or you can do it manually. The PR template includes: +- Contribution method (skill or manual) +- Pack-persona alignment justification +- Compliance checklist + +### Step 4: CI Validation + +Automated checks run on every PR: + +| Check | What it validates | Blocks merge? | +|-------|-------------------|---------------| +| `compliance-check` | Pack structure + collection compliance | Yes | +| `skill-spec-report` | Tier 1: agentskills.io spec (frontmatter, naming, line limits) | Yes (on errors) | +| `/skill-code-review` | AI review against CLAUDE.md + design principles | No (maintainer-triggered) | +| `/skill-security-scan` | Security scan (injection, exfiltration, supply chain) | No (maintainer-triggered) | + +### Step 5: Review & Merge + +1. GitHub auto-assigns the pack owner as reviewer (via [CODEOWNERS](CODEOWNERS)) +2. Pack owner reviews the PR +3. Feedback addressed if needed +4. Approval and merge +5. Skill available in the catalog after next build + +### Validation Commands + +The skill runs these automatically, but you can run them manually: + +```bash +# Tier 1: agentskills.io spec +./scripts/run-skill-linter.sh /skills// + +# Tier 2: design principles +make validate-skill-design-changed + +# Full repo validation +make validate +``` + +### Pre-commit Hooks + +If you have pre-commit installed, these hooks run locally before each commit: + +| Hook | What it validates | +|------|-------------------| +| `gitleaks` | No secrets in committed files | +| `make-validate` | Pack structure + collection compliance | +| `validate-skill-design-changed` | Tier 2: design principles | +| `skill-spec-linter` | Tier 1: agentskills.io spec | + +### Requirements + +- All skills must pass Tier 1 + Tier 2 validation +- Skills must fit a pack's persona (the skill suggests the right pack) +- No hardcoded credentials (`${ENV_VAR}` format only) +- Human-in-the-loop confirmation for destructive operations +- CLAUDE.md intent routing must be updated + +--- + +## Path 2: Federation + +For referencing skills from external repositories in the Agentic Collections catalog. + +### Process + +``` +Contributor opens PR → Federation CI validates → Maintainer reviews (+ /federation-review) → Merge +``` + +### Step 1: Open a Federation PR + +Open a PR that adds a new module entry to `marketplace/rh-agentic-collection.yml` with your external repository URL. Add the `federation` label to the PR. Fill in the "Federation request" section of the PR template. + +### Step 2: Automated CI + +The Federation Validation workflow runs automatically on PRs with the `federation` label. It validates only new or changed federated modules against: Lola module schema, Tier 1, Tier 2, MCP pinning, and credential scan. + +### Step 3: Maintainer Review + +Maintainers review the PR and may use `/federation-review` in Claude Code to check license compatibility and verify the module loads in Lola. + +### Step 4: Ongoing Maintenance + +- **Version updates**: Open a PR updating the SHA/tag in marketplace YAML +- **Re-validation**: Federated skills are validated on each catalog build +- **Removal**: If the external repo becomes unavailable or skills stop passing validation, the federation entry may be removed after notification + +### Requirements + +**Mandatory:** +- Skills follow SKILL.md format with valid YAML frontmatter (`name`, `description`, `license`) +- Skills pass Tier 1 validation (agentskills.io spec) +- Repository is public and accessible +- Stable ref provided (commit SHA or release tag) or default branch +- Compatible license (Apache-2.0 recommended) + +**Recommended:** +- Skills pass Tier 2 validation (design principles) +- Repository includes `mcps.json` if skills depend on MCP servers +- Skills include Common Issues and Example Usage sections +- Repository has its own CI for skill validation + +### Responsibilities + +**Federated repo owner:** +- Maintain skill quality and validation compliance +- Provide stable refs (don't force-push tagged commits) +- Update skills when notified of standard changes + +**Agentic Collections maintainers:** +- Validate federated skills on registration and catalog builds +- Notify owners of validation failures +- Remove stale entries after reasonable notice + +### What Federation Does NOT Include + +- Federated skills are not modified by this repository +- Federation does not grant write access to this repository +- Federation does not imply endorsement — it means skills meet minimum quality standards + +--- + +## Review Assignment + +PR reviews are auto-assigned via [CODEOWNERS](CODEOWNERS): + +| Files touched | Reviewer | +|---|---| +| `rh-sre/` | Pack owner (see CODEOWNERS) | +| `rh-virt/` | Pack owner (see CODEOWNERS) | +| `ocp-admin/` | Pack owner (see CODEOWNERS) | +| *(other packs)* | Pack owner (see CODEOWNERS) | +| `.github/`, `scripts/`, `marketplace/` | Maintainers | +| Federation PRs (`marketplace/` only) | Maintainers | + +To make CODEOWNERS review mandatory, enable "Require review from Code Owners" in branch protection settings for the `main` branch. + +--- + +## Pack-Persona Reference + +Skills must fit into an existing pack or justify a new one: + +| Pack | Persona | Scope | +|------|---------|-------| +| `rh-sre` | Site Reliability Engineers | CVE, compliance, RHEL automation | +| `rh-developer` | Application Developers | Deployment, builds, Helm | +| `rh-virt` | Virtualization Admins | VM lifecycle, snapshots, migrations | +| `ocp-admin` | OpenShift Administrators | Cluster management, monitoring | +| `rh-ai-engineer` | AI/ML Engineers | Model serving, inference | +| `rh-automation` | Automation Leads | Ansible AAP governance | +| `rh-basic` | General Red Hat Users | Diagnostics, lifecycle | +| `rh-support-engineer` | Support Engineers | Troubleshooting | + +For direct contributions, `/agentic-contribution-skill` suggests the right pack automatically. For federation, explain pack fit in the issue. + +--- + +## Questions? + +- [GitHub Issues](https://github.com/RHEcosystemAppEng/agentic-plugins/issues) From 97f5caa2c1df1ffee83393b0cb198738e54986aa Mon Sep 17 00:00:00 2001 From: r2dedios Date: Thu, 2 Jul 2026 14:34:09 +0200 Subject: [PATCH 2/2] Updated PR content with comments feedback Signed-off-by: r2dedios --- .gitignore | 1 - CLAUDE.md | 2 +- CODEOWNERS | 8 +- CONTRIBUTION_PROTOCOL.md | 214 --------------------------------------- 4 files changed, 5 insertions(+), 220 deletions(-) delete mode 100644 CONTRIBUTION_PROTOCOL.md diff --git a/.gitignore b/.gitignore index 06019b7..db5882e 100644 --- a/.gitignore +++ b/.gitignore @@ -32,7 +32,6 @@ ENV/ build/ develop-eggs/ dist/ -docs downloads/ eggs/ .eggs/ diff --git a/CLAUDE.md b/CLAUDE.md index 6f95c7d..3f3dbf1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## What This Repository Is -This is a **skills source repository** — one of potentially many that feed into the [agentic-catalog](https://github.com/RHEcosystemAppEng/agentic-catalog). It contains AI agentic packs with skills, MCP server configurations, AI-optimized documentation, and catalog metadata for Red Hat platforms. +This is a **skills source repository** — one of potentially many that feed into the [agentic-catalog](https://github.com/RHEcosystemAppEng/agentic-catalog). It contains agentic packs with skills, MCP server configurations, AI-optimized documentation, and catalog metadata for Red Hat platforms. Contributors work here to create, improve, and validate skills. An internal process periodically fetches content from this repository (and others like it) to build the unified catalog and marketplace. **This repo does not serve the marketplace directly** — it is a source of skills that the catalog aggregates. diff --git a/CODEOWNERS b/CODEOWNERS index c9f6b61..8a67b55 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -12,10 +12,10 @@ rh-sre/ @dmartinol rh-developer/ @ikrispin rh-virt/ @r2dedios ocp-admin/ @r2dedios -rh-ai-engineer/ @dmartinol -rh-automation/ @dmartinol -rh-basic/ @dmartinol -rh-support-engineer/ @dmartinol +rh-ai-engineer/ @ikrispin +rh-automation/ @nemerna +rh-basic/ @r2dedios +rh-support-engineer/ # CI, scripts, and repo-wide config .github/ @r2dedios @dmartinol diff --git a/CONTRIBUTION_PROTOCOL.md b/CONTRIBUTION_PROTOCOL.md deleted file mode 100644 index b5f649b..0000000 --- a/CONTRIBUTION_PROTOCOL.md +++ /dev/null @@ -1,214 +0,0 @@ -# Contribution Protocol - -> **Draft** — This document defines the end-to-end protocol for contributing to Red Hat Agentic Collections. Covers both direct contributions and federation of external repositories. Subject to change as the process matures. - -## Two Contribution Paths - -| | Direct Contribution | Federation | -|---|---|---| -| **Your code lives in** | This repository | Your repository | -| **Compliance level** | Strict (Tier 1 + Tier 2 mandatory) | Tier 1 mandatory, Tier 2 recommended | -| **Entry point** | `/agentic-contribution-skill` in Claude Code | PR adding module to marketplace YAML | -| **Review process** | PR with automated CI + maintainer review | PR with `federation` label → automated CI + maintainer review | -| **PR auto-assigned to** | Pack owner via CODEOWNERS | Maintainers | -| **You control** | Nothing after merge (maintainers own it) | Your repo, your pace, your releases | -| **Catalog appearance** | Immediate after merge | After registration PR merges + next build | - -Choose **direct contribution** when you want your skill to be part of the official collection with full maintainer support. Choose **federation** when you want to keep ownership of your code and release independently. - ---- - -## Path 1: Direct Contribution - -For adding skills or packs directly to this repository. - -### Process - -``` -Fork & clone → /agentic-contribution-skill → PR → CI validation → CODEOWNERS review → Merge -``` - -### Step 1: Setup - -1. Fork the repository on GitHub -2. Clone your fork locally -3. Open the project in Claude Code - -### Step 2: Create or Import - -Run `/agentic-contribution-skill` and choose a mode: - -- **Create**: Answer discovery questions → skill is generated, validated, and placed in the right pack -- **Import**: Point to an existing SKILL.md → the skill is analyzed, adapted to repo standards, and placed in the right pack - -The skill handles: -- Pack selection based on content analysis -- Structure and section generation following [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) -- CLAUDE.md intent routing update -- Tier 1 + Tier 2 validation -- Git workflow (branch, commit, push) - -### Step 3: Submit PR - -The skill can create the PR for you, or you can do it manually. The PR template includes: -- Contribution method (skill or manual) -- Pack-persona alignment justification -- Compliance checklist - -### Step 4: CI Validation - -Automated checks run on every PR: - -| Check | What it validates | Blocks merge? | -|-------|-------------------|---------------| -| `compliance-check` | Pack structure + collection compliance | Yes | -| `skill-spec-report` | Tier 1: agentskills.io spec (frontmatter, naming, line limits) | Yes (on errors) | -| `/skill-code-review` | AI review against CLAUDE.md + design principles | No (maintainer-triggered) | -| `/skill-security-scan` | Security scan (injection, exfiltration, supply chain) | No (maintainer-triggered) | - -### Step 5: Review & Merge - -1. GitHub auto-assigns the pack owner as reviewer (via [CODEOWNERS](CODEOWNERS)) -2. Pack owner reviews the PR -3. Feedback addressed if needed -4. Approval and merge -5. Skill available in the catalog after next build - -### Validation Commands - -The skill runs these automatically, but you can run them manually: - -```bash -# Tier 1: agentskills.io spec -./scripts/run-skill-linter.sh /skills// - -# Tier 2: design principles -make validate-skill-design-changed - -# Full repo validation -make validate -``` - -### Pre-commit Hooks - -If you have pre-commit installed, these hooks run locally before each commit: - -| Hook | What it validates | -|------|-------------------| -| `gitleaks` | No secrets in committed files | -| `make-validate` | Pack structure + collection compliance | -| `validate-skill-design-changed` | Tier 2: design principles | -| `skill-spec-linter` | Tier 1: agentskills.io spec | - -### Requirements - -- All skills must pass Tier 1 + Tier 2 validation -- Skills must fit a pack's persona (the skill suggests the right pack) -- No hardcoded credentials (`${ENV_VAR}` format only) -- Human-in-the-loop confirmation for destructive operations -- CLAUDE.md intent routing must be updated - ---- - -## Path 2: Federation - -For referencing skills from external repositories in the Agentic Collections catalog. - -### Process - -``` -Contributor opens PR → Federation CI validates → Maintainer reviews (+ /federation-review) → Merge -``` - -### Step 1: Open a Federation PR - -Open a PR that adds a new module entry to `marketplace/rh-agentic-collection.yml` with your external repository URL. Add the `federation` label to the PR. Fill in the "Federation request" section of the PR template. - -### Step 2: Automated CI - -The Federation Validation workflow runs automatically on PRs with the `federation` label. It validates only new or changed federated modules against: Lola module schema, Tier 1, Tier 2, MCP pinning, and credential scan. - -### Step 3: Maintainer Review - -Maintainers review the PR and may use `/federation-review` in Claude Code to check license compatibility and verify the module loads in Lola. - -### Step 4: Ongoing Maintenance - -- **Version updates**: Open a PR updating the SHA/tag in marketplace YAML -- **Re-validation**: Federated skills are validated on each catalog build -- **Removal**: If the external repo becomes unavailable or skills stop passing validation, the federation entry may be removed after notification - -### Requirements - -**Mandatory:** -- Skills follow SKILL.md format with valid YAML frontmatter (`name`, `description`, `license`) -- Skills pass Tier 1 validation (agentskills.io spec) -- Repository is public and accessible -- Stable ref provided (commit SHA or release tag) or default branch -- Compatible license (Apache-2.0 recommended) - -**Recommended:** -- Skills pass Tier 2 validation (design principles) -- Repository includes `mcps.json` if skills depend on MCP servers -- Skills include Common Issues and Example Usage sections -- Repository has its own CI for skill validation - -### Responsibilities - -**Federated repo owner:** -- Maintain skill quality and validation compliance -- Provide stable refs (don't force-push tagged commits) -- Update skills when notified of standard changes - -**Agentic Collections maintainers:** -- Validate federated skills on registration and catalog builds -- Notify owners of validation failures -- Remove stale entries after reasonable notice - -### What Federation Does NOT Include - -- Federated skills are not modified by this repository -- Federation does not grant write access to this repository -- Federation does not imply endorsement — it means skills meet minimum quality standards - ---- - -## Review Assignment - -PR reviews are auto-assigned via [CODEOWNERS](CODEOWNERS): - -| Files touched | Reviewer | -|---|---| -| `rh-sre/` | Pack owner (see CODEOWNERS) | -| `rh-virt/` | Pack owner (see CODEOWNERS) | -| `ocp-admin/` | Pack owner (see CODEOWNERS) | -| *(other packs)* | Pack owner (see CODEOWNERS) | -| `.github/`, `scripts/`, `marketplace/` | Maintainers | -| Federation PRs (`marketplace/` only) | Maintainers | - -To make CODEOWNERS review mandatory, enable "Require review from Code Owners" in branch protection settings for the `main` branch. - ---- - -## Pack-Persona Reference - -Skills must fit into an existing pack or justify a new one: - -| Pack | Persona | Scope | -|------|---------|-------| -| `rh-sre` | Site Reliability Engineers | CVE, compliance, RHEL automation | -| `rh-developer` | Application Developers | Deployment, builds, Helm | -| `rh-virt` | Virtualization Admins | VM lifecycle, snapshots, migrations | -| `ocp-admin` | OpenShift Administrators | Cluster management, monitoring | -| `rh-ai-engineer` | AI/ML Engineers | Model serving, inference | -| `rh-automation` | Automation Leads | Ansible AAP governance | -| `rh-basic` | General Red Hat Users | Diagnostics, lifecycle | -| `rh-support-engineer` | Support Engineers | Troubleshooting | - -For direct contributions, `/agentic-contribution-skill` suggests the right pack automatically. For federation, explain pack fit in the issue. - ---- - -## Questions? - -- [GitHub Issues](https://github.com/RHEcosystemAppEng/agentic-plugins/issues)