From 34139fb0cfc9644d15c216f669f288b8f0fb89b1 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Tue, 3 Mar 2026 15:46:47 +0100 Subject: [PATCH 1/9] introduced lola package manager Signed-off-by: Daniele Martinoli --- .claude-plugin/marketplace.json | 125 ---------------- .github/copilot-instructions.md | 133 ++++++++++++++++++ .github/pull_request_template.md | 2 +- .github/workflows/README.md | 4 +- .gitleaks.toml | 2 +- CLAUDE.md | 10 +- Makefile | 2 +- README.md | 47 +++++-- SECURITY.md | 6 +- SKILL_DESIGN_PRINCIPLES.md | 4 +- docs/README.md | 2 +- docs/app.js | 109 ++++++++------ docs/index.html | 19 ++- docs/styles.css | 133 ++++++++++++++++++ marketplace/rh-agentic-collection.yml | 66 +++++++++ ocp-admin/.claude-plugin/plugin.json | 13 -- rh-developer/.claude-plugin/plugin.json | 13 -- rh-developer/{.mcp.json => mcps.json} | 0 rh-sre/.claude-plugin/plugin.json | 13 -- rh-sre/README.md | 8 +- .../testing/aap-integration-test-guide.md | 2 +- rh-sre/{.mcp.json => mcps.json} | 0 rh-sre/skills/cve-impact/SKILL.md | 2 +- rh-sre/skills/cve-validation/SKILL.md | 2 +- .../skills/mcp-lightspeed-validator/SKILL.md | 2 +- rh-sre/skills/playbook-generator/SKILL.md | 2 +- .../.claude-plugin/plugin.json | 13 -- rh-virt/.claude-plugin/plugin.json | 13 -- rh-virt/README.md | 6 +- rh-virt/SKILL_TEMPLATE.md | 4 +- rh-virt/{.mcp.json => mcps.json} | 0 rh-virt/skills/vm-clone/SKILL.md | 42 +++++- rh-virt/skills/vm-create/SKILL.md | 53 ++++++- rh-virt/skills/vm-delete/SKILL.md | 64 ++++++++- rh-virt/skills/vm-inventory/SKILL.md | 66 ++++++++- rh-virt/skills/vm-lifecycle-manager/SKILL.md | 63 ++++++++- rh-virt/skills/vm-rebalance/SKILL.md | 28 +++- rh-virt/skills/vm-snapshot-delete/SKILL.md | 2 +- rh-virt/skills/vm-snapshot-list/SKILL.md | 4 +- scripts/generate_mcp_data.py | 19 ++- scripts/validate_skill_design.py | 74 +++++++++- scripts/validate_structure.py | 29 ++-- 42 files changed, 880 insertions(+), 321 deletions(-) delete mode 100644 .claude-plugin/marketplace.json create mode 100644 .github/copilot-instructions.md create mode 100644 marketplace/rh-agentic-collection.yml delete mode 100644 ocp-admin/.claude-plugin/plugin.json delete mode 100644 rh-developer/.claude-plugin/plugin.json rename rh-developer/{.mcp.json => mcps.json} (100%) delete mode 100644 rh-sre/.claude-plugin/plugin.json rename rh-sre/{.mcp.json => mcps.json} (100%) delete mode 100644 rh-support-engineer/.claude-plugin/plugin.json delete mode 100644 rh-virt/.claude-plugin/plugin.json rename rh-virt/{.mcp.json => mcps.json} (100%) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json deleted file mode 100644 index ed854f2e..00000000 --- a/.claude-plugin/marketplace.json +++ /dev/null @@ -1,125 +0,0 @@ -{ - "name": "redhat-agentic-collections", - "owner": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "metadata": { - "version": "1.0.0", - "description": "Validated Agentic Collections from Red Hat Ecosystem Engineering" - }, - "plugins": [ - { - "name": "rh-sre", - "description": "Site Reliability Engineering Agentic Collection", - "version": "1.0.0", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["sre", "red-hat", "platforms", "products", "automation"], - "source": "./rh-sre", - "category": "sre", - "skills": "./skills" - }, - { - "name": "rh-developer", - "description": "Developer Agentic Collection", - "version": "1.0.0", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["developer", "openshift", "rhel", "s2i", "containerization", "deployment", "helm", "podman"], - "source": "./rh-developer", - "category": "developer", - "skills": "./skills" - }, - { - "name": "openshift-virtualization", - "description": "OpenShift Virtualization Agentic Collection", - "version": "1.0.0", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["red-hat", "kubevirt", "openshift", "virtualization"], - "source": "./rh-virt", - "category": "virtualization", - "skills": "./skills" - }, - { - "name": "ocp-admin", - "description": "Red Hat OpenShift Administration Agentic Skills Collection", - "version": "1.0.0", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["red-hat", "openshift", "administration", "management"], - "source": "./ocp-admin", - "category": "openshift", - "skills": "./skills" - }, - { - "name": "rh-ai-engineer", - "description": "Red Hat OpenShift AI Engineering Agentic Collection", - "version": "1.0.0", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["ai-engineer", "openshift-ai", "rhoai", "kserve", "vllm", "nvidia-nim", "model-serving", "inference", "gpu"], - "source": "./rh-ai-engineer", - "category": "ai-engineering", - "skills": "./skills" - }, - { - "name": "rh-support-engineer", - "description": "Technical support and troubleshooting tools for Red Hat products and platforms.", - "version": "1.0.0", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["red-hat", "support", "troubleshooting", "engineering"], - "source": "./rh-support-engineer", - "category": "support", - "skills": "./skills" - }, - { - "name": "rh-automation", - "description": "Ansible Automation Platform governance, execution safety, and forensic troubleshooting tools for Red Hat automation engineers.", - "version": "1.0.0", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["ansible", "aap", "automation", "red-hat", "governance", "troubleshooting", "execution"], - "source": "./rh-automation", - "category": "automation", - "skills": "./skills" - } - ] -} \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..5fd25cfa --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,133 @@ +# Copilot Instructions for agentic-collections + +## Repository Overview + +This repository contains **agentic collections** — persona-specific plugin packs that automate interactions with Red Hat platforms. Each pack ships skills, agents, and MCP server configurations for AI marketplaces (Claude Code, Cursor, ChatGPT). + +## Repository Structure + +``` +agentic-collections/ +├── rh-sre/ # Site Reliability Engineering (reference implementation) +├── rh-developer/ # Developer tools +├── ocp-admin/ # OpenShift administration +├── rh-support-engineer/ # Technical support +├── rh-virt/ # Virtualization management +├── docs/ # Generated documentation site (do not edit data.json manually) +├── scripts/ # Python build/validate/generate scripts +└── Makefile # Main developer commands +``` + +### Inside each pack + +``` +/ +├── README.md +├── .claude-plugin/plugin.json # Optional: name, version, description, author, license +├── mcps.json # MCP server configs — credentials via env vars ONLY +├── agents/.md # Workflow orchestrators (YAML frontmatter required) +└── skills//SKILL.md # Task executors (YAML frontmatter required) +``` + +## Build, Validate, and Test + +All tooling uses [uv](https://github.com/astral-sh/uv). Install it once: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +| Command | Purpose | +|---|---| +| `make install` | Install Python deps | +| `make validate` | Validate pack/skill/agent structure (runs in CI) | +| `make generate` | Rebuild `docs/data.json` | +| `make test` | validate + generate + verify checks | +| `make serve` | Local site at http://localhost:8000 | + +**CI runs `make install && make validate` on every PR.** Always run `make validate` after editing skills, agents, or `mcps.json` files to catch errors before pushing. + +Packs known to the validator are listed in `scripts/validate_structure.py` (`PACK_DIRS`). Add new packs there when creating them. + +## Key File Formats + +### Skills — `skills//SKILL.md` + +Must start with valid YAML frontmatter. Root-level fields: `name`, `description`, `model`, `color`. Use `metadata` for custom fields (author, priority). See SKILL_DESIGN_PRINCIPLES.md for the 2026 Agentic Skills structure. + +```yaml +--- +name: skill-name +description: | + Concise when-to-use description with 3-5 examples. + Keep under 500 tokens. +model: inherit +color: blue +metadata: + author: "team-name" +--- +``` + +### Agents — `agents/.md` + +Same YAML frontmatter requirement (`name` + `description`). Agents orchestrate skills; they do not call MCP tools directly. + +### `mcps.json` + +```json +{ + "mcpServers": { + "server-name": { + "command": "podman", + "args": ["run", "--rm", "-i", "..."], + "env": { "SECRET": "${SECRET}" }, + "description": "...", + "security": { "isolation": "container", "network": "local", "credentials": "env-only" } + } + } +} +``` + +**NEVER hardcode credentials.** Always use `${ENV_VAR}` references. Gitleaks runs as a pre-commit hook and in CI. + +## Design Principles (from SKILL_DESIGN_PRINCIPLES.md) + +1. **Skills encapsulate tools** — never call MCP tools directly; always go through a skill. +2. **Agents orchestrate skills** — complex workflows delegate to specialized skills. +3. **Document consultation is an action** — actually read reference docs with the Read tool before claiming to have consulted them. +4. **Precise parameters** — specify exact tool parameters (names, formats, examples) so first-attempt tool calls succeed. +5. **Human-in-the-loop for critical ops** — require explicit confirmation before playbook execution or destructive actions. +6. **Never print credential values** — only report whether env vars are set/unset, never their contents. +7. **Dependencies section in every skill** — list required MCP servers, tools, related skills, and reference docs. + +## Adding a New Pack + +1. Create `/` directory with `README.md`. +2. Add `skills/` and optionally `agents/`, `mcps.json`, `.claude-plugin/plugin.json`. +3. Add the new pack name to `PACK_DIRS` in `scripts/validate_structure.py`. +4. Run `make validate && make generate` to regenerate docs locally for testing; do **not** commit `docs/data.json` (it is generated during deployment). + +## Adding a New Skill + +1. Create `skills//SKILL.md` with valid YAML frontmatter. +2. Follow the mandatory section order: Prerequisites → When to Use → Workflow → Dependencies → (Human-in-the-Loop if needed) → Example Usage. +3. Run `make validate` to confirm no errors. + +See `rh-virt/SKILL_TEMPLATE.md` for the canonical skill template and `rh-sre` as the full reference implementation. + +## Security + +- Gitleaks protects against accidental secret commits. +- Install pre-commit hook: `scripts/install-hooks.sh` +- Manual scan: `gitleaks detect --source . --verbose` +- See `SECURITY.md` and `.gitleaks.toml` for details. + +## Common Errors and Workarounds + +| Error | Cause | Fix | +|---|---|---| +| `Missing YAML frontmatter` | SKILL.md or agent .md missing `---` block | Add frontmatter with `name` and `description` | +| `Invalid JSON in mcps.json` | Syntax error or comments in JSON | JSON does not support comments; remove them | +| `Pack directory does not exist` | New pack not listed in validator | Add to `PACK_DIRS` in `scripts/validate_structure.py` | +| `uv: command not found` | uv not installed | `curl -LsSf https://astral.sh/uv/install.sh | sh` | +| Gitleaks blocks commit | Credential-like value in file | Use `${ENV_VAR}` references instead of literal values | diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 07978d49..9a075548 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -17,7 +17,7 @@ - [ ] New agent - [ ] New pack - [ ] Update existing skill / agent -- [ ] MCP server config (`.mcp.json`) +- [ ] MCP server config (`mcps.json`) - [ ] Docs / README - [ ] CI / tooling diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 8211a3d8..4787751e 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -157,7 +157,7 @@ The workflow will: **Repository structure validation (`make validate`):** - ✅ Collection directory structure and naming conventions -- ✅ Required files presence (README.md, .mcp.json, etc.) +- ✅ Required files presence (README.md, mcps.json, etc.) - ✅ Plugin metadata completeness - ✅ MCP server configurations @@ -199,7 +199,7 @@ The workflow will fail and provide: 3. Reference to SKILL_DESIGN_PRINCIPLES.md **Common validation errors**: -- Missing required collection files (README.md, .mcp.json) +- Missing required collection files (README.md, mcps.json) - Invalid MCP server configuration syntax - Skills not following design principles (see SKILL_DESIGN_PRINCIPLES.md) - Missing documentation in collections diff --git a/.gitleaks.toml b/.gitleaks.toml index 218e6c54..4099a911 100644 --- a/.gitleaks.toml +++ b/.gitleaks.toml @@ -11,7 +11,7 @@ useDefault = true # Custom rules for project-specific patterns [[rules]] id = "mcp-hardcoded-credentials" -description = "Hardcoded credentials in .mcp.json files (must use ${ENV_VAR} pattern)" +description = "Hardcoded credentials in mcps.json files (must use ${ENV_VAR} pattern)" regex = '''["'](?:LIGHTSPEED_CLIENT_ID|LIGHTSPEED_CLIENT_SECRET|API_KEY|SECRET|TOKEN|PASSWORD)["']\s*:\s*["'][^"']{8,}["']''' path = '''\.mcp\.json$''' tags = ["mcp", "credentials"] diff --git a/CLAUDE.md b/CLAUDE.md index 54689450..6b7c03ac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,6 +19,8 @@ agentic-collections/ ### Agentic Pack Architecture +Packs follow the [Lola](https://github.com/RedHatProductSecurity/lola) package manager format. Install via `lola install -f ` from the marketplace. + Each pack follows this structure: ``` / @@ -26,7 +28,7 @@ Each pack follows this structure: ├── README.md # Pack description, persona, target marketplaces ├── .claude-plugin/ # Claude Code plugin metadata │ └── plugin.json # Name, version, description, author, license -├── .mcp.json # MCP server configurations (uses env vars for credentials) +├── mcps.json # MCP server configurations (uses env vars for credentials) ├── skills/ # Specialized task executors (including orchestration skills) │ └── / │ └── SKILL.md # Skill definition with YAML frontmatter @@ -72,7 +74,7 @@ Each pack follows this structure: ### MCP Server Integration -MCP servers are configured in `/.mcp.json`: +MCP servers are configured in `/mcps.json`: ```json { "mcpServers": { @@ -154,7 +156,7 @@ last_updated: YYYY-MM-DD 3. Add `CLAUDE.md` with persona, skill-first rule, intent routing table, MCP servers, and global rules (see [rh-ai-engineer/CLAUDE.md](rh-ai-engineer/CLAUDE.md) for reference) 4. Create `skills/` directory 5. Optional: Add `.claude-plugin/plugin.json` for Claude Code -6. Optional: Add `.mcp.json` for MCP server integrations +6. Optional: Add `mcps.json` for MCP server integrations 7. Update main `README.md` table with link ### Adding a Skill @@ -244,7 +246,7 @@ When creating new collections, follow the pattern that best matches your needs: ### Security & Configuration 5. **Environment variables for secrets** - Never hardcode credentials 6. **Never expose credential values** - Check env vars are set, but NEVER print their values in output -7. **MCP server integration** - Use `.mcp.json` with environment variable references +7. **MCP server integration** - Use `mcps.json` with environment variable references ### Documentation & Quality 8. **Official sources only** - Document all sources in SOURCES.md diff --git a/Makefile b/Makefile index e060f031..ada5a582 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ help: @echo "" @echo "Available targets:" @echo " install - Install Python dependencies (requires uv)" - @echo " validate - Validate pack structure (plugin.json, .mcp.json, frontmatter)" + @echo " validate - Validate pack structure (plugin.json, mcps.json, frontmatter)" @echo " validate-skill-design - Validate all skills (use PACK=rh-sre for a specific pack)" @echo " validate-skill-design-changed - Validate only changed skills (staged + unstaged, for local dev)" @echo " generate - Generate docs/data.json" diff --git a/README.md b/README.md index f6c7f16f..f47ac1a4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,37 @@ # Red Hat Agentic Collections -**Production-ready AI skills and automation for Red Hat platforms** - Install specialized plugins for SREs, developers, platform administrators, and AI engineers working with RHEL, OpenShift, and Red Hat automation platforms. +**Production-ready AI skills and automation for Red Hat platforms** — install specialized plugins for SREs, developers, platform administrators, and AI engineers working with RHEL, OpenShift, and Red Hat automation platforms. + +## Installation (Lola package manager) + +Install collections using [Lola](https://github.com/RedHatProductSecurity/lola), the AI skills package manager. **Installation applies to the current folder only** — run commands from your project directory. + +### One-time setup: add marketplace + +```bash +lola market add rh-agentic-collections https://raw.githubusercontent.com/RHEcosystemAppEng/agentic-collections/main/marketplace/rh-agentic-collection.yml +``` + +### Install individual module + +```bash +lola install -f rh-sre +``` + +### Install all modules at once + +```bash +for m in ocp-admin rh-developer rh-sre rh-support-engineer rh-virt; do lola install -f $m; done +``` + +### Install to a specific assistant only + +Use the `-a` option to target Claude Code or Cursor: + +```bash +lola install -f rh-sre -a claude-code # Claude Code only +lola install -f rh-sre -a cursor # Cursor only +``` [![Validate Agentic Collections](https://github.com/RHEcosystemAppEng/agentic-collections/actions/workflows/compliance-check.yml/badge.svg)](https://github.com/RHEcosystemAppEng/agentic-collections/actions/workflows/compliance-check.yml) [![Skill Specification Linter](https://github.com/RHEcosystemAppEng/agentic-collections/actions/workflows/skill-spec-report.yml/badge.svg)](https://github.com/RHEcosystemAppEng/agentic-collections/actions/workflows/skill-spec-report.yml) @@ -153,7 +184,7 @@ Generate and view documentation locally: # Install dependencies (first time only) make install -# Validate pack structure (plugin.json, .mcp.json, frontmatter) +# Validate pack structure (plugin.json, mcps.json, frontmatter) make validate # Validate skills against Design Principles (SKILL_DESIGN_PRINCIPLES.md) @@ -219,7 +250,7 @@ scripts/install-hooks.sh - **API keys**: OpenAI, GitHub, AWS, Google Cloud - **Private keys**: SSH, SSL/TLS certificates -- **Hardcoded credentials** in `.mcp.json` files +- **Hardcoded credentials** in `mcps.json` files - **Database connection strings** with passwords - **JWT tokens** and authentication secrets @@ -262,7 +293,7 @@ To add a new MCP server to an agentic pack and display it on the documentation s ### Step 1: Add MCP Configuration to Pack -Add the server configuration to `/.mcp.json`: +Add the server configuration to `/mcps.json`: ```json { @@ -326,7 +357,7 @@ make generate ``` This will: -1. Parse the `.mcp.json` file from your pack +1. Parse the `mcps.json` file from your pack 2. Merge it with custom data from `docs/mcp.json` 3. Update `docs/data.json` with the new server @@ -348,7 +379,7 @@ Visit http://localhost:8000 and verify: ### Step 5: Commit and Deploy ```bash -git add /.mcp.json docs/mcp.json docs/data.json +git add /mcps.json docs/mcp.json docs/data.json git commit -m "feat: add MCP server to " git push ``` @@ -357,7 +388,7 @@ The documentation site will automatically update via GitHub Actions. ### Example: Adding Red Hat Lightspeed MCP Server -**File: `rh-sre/.mcp.json`** +**File: `rh-sre/mcps.json`** ```json { "mcpServers": { @@ -405,7 +436,7 @@ The documentation site will automatically update via GitHub Actions. **Server not appearing:** - Run `make validate` to check for JSON syntax errors -- Verify `.mcp.json` file is in the pack directory +- Verify `mcps.json` file is in the pack directory - Check that pack directory is listed in `scripts/generate_pack_data.py` PACK_DIRS **Tools not showing:** diff --git a/SECURITY.md b/SECURITY.md index 3f5f107b..358e2147 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -48,7 +48,7 @@ const apiKey = "ghp_1234567890abcdefghij"; const apiKey = process.env.GITHUB_TOKEN; ``` -### .mcp.json Requirements +### mcps.json Requirements **MCP Configuration Rule** (per [CLAUDE.md line 125](CLAUDE.md#L125)): @@ -109,7 +109,7 @@ Gitleaks scans for: - **Database URLs**: Connection strings with embedded passwords - **JWT Tokens**: eyJ... format tokens - **Generic Secrets**: password, api_key, secret, token assignments -- **MCP Hardcoded Values**: `.mcp.json` files without ${VAR} pattern +- **MCP Hardcoded Values**: `mcps.json` files without ${VAR} pattern ### Manual Scanning @@ -335,7 +335,7 @@ After an incident: - **Repository Guidelines**: [CLAUDE.md](CLAUDE.md) - Line 125 documents MCP credential requirements - **.gitignore**: Pre-configured to exclude common secret files (.env, *.key, *.pem) -- **MCP Example**: [rh-sre/.mcp.json](rh-sre/.mcp.json) - Reference implementation with ${VAR} pattern +- **MCP Example**: [rh-sre/mcps.json](rh-sre/mcps.json) - Reference implementation with ${VAR} pattern - **Gitleaks Configuration**: [.gitleaks.toml](.gitleaks.toml) - Project-specific rules ### External Resources diff --git a/SKILL_DESIGN_PRINCIPLES.md b/SKILL_DESIGN_PRINCIPLES.md index 3d791d2e..fe81e1ea 100644 --- a/SKILL_DESIGN_PRINCIPLES.md +++ b/SKILL_DESIGN_PRINCIPLES.md @@ -2,7 +2,7 @@ Repository-specific design principles for creating skills and agents in agentic collections. Referenced from [CLAUDE.md](CLAUDE.md). -**Scope**: Tier 2 requirements - repository enhancements beyond base agentskills.io specification (Tier 1 validated by linter). +**Scope**: Tier 2 requirements - repository enhancements beyond base agentskills.io specification (Tier 1 validated by linter). Packs follow the Lola module format; see [CLAUDE.md](CLAUDE.md) for layout. --- @@ -302,7 +302,7 @@ test -n "$API_SECRET" && echo "✓ API_SECRET is set" || echo "✗ Not set" **Environment Variables:** `VAR` - What it controls **Verification Steps:** -1. Check `server-name` in `.mcp.json` +1. Check `server-name` in `mcps.json` 2. Verify `VAR` is set (without exposing value) 3. If missing → Human Notification Protocol diff --git a/docs/README.md b/docs/README.md index df966a3d..6a0aa97d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,7 +31,7 @@ This script parses all agentic collections and MCP configurations. ## Manual Updates To manually update the site: -1. Modify pack configurations (plugin.json, .mcp.json, skills, agents) +1. Modify pack configurations (plugin.json, mcps.json, skills, agents) 2. Run `make generate` from the root directory 3. Commit the updated `docs/data.json` 4. Push to trigger GitHub Pages deployment diff --git a/docs/app.js b/docs/app.js index 3467c043..714335b7 100644 --- a/docs/app.js +++ b/docs/app.js @@ -60,6 +60,13 @@ async function init() { // Setup search document.getElementById('searchInput').addEventListener('input', handleSearch); + // Setup install banner copy button + const installCopyBtn = document.getElementById('install-copy-btn'); + const installCommand = document.getElementById('install-command'); + if (installCopyBtn && installCommand) { + installCopyBtn.addEventListener('click', () => copyToClipboard(installCommand.textContent, installCopyBtn)); + } + // Setup modal close handlers setupModals(); @@ -418,6 +425,15 @@ function toggleSection(sectionId) { section.classList.toggle('collapsed'); } +function toggleInstallCallout() { + const callout = document.getElementById('install-callout'); + const toggle = callout?.querySelector('.install-callout-toggle'); + const body = document.getElementById('install-callout-body'); + if (!callout || !toggle || !body) return; + callout.classList.toggle('collapsed'); + toggle.setAttribute('aria-expanded', callout.classList.contains('collapsed') ? 'false' : 'true'); +} + /** * Show pack details modal (XSS-safe) */ @@ -542,7 +558,7 @@ function showPackDetails(packName) { const body = document.createElement('div'); body.className = 'modal-body'; - // Installation section + // Installation section (Lola package manager) const installSection = document.createElement('div'); installSection.className = 'modal-section'; @@ -551,48 +567,53 @@ function showPackDetails(packName) { installHeader.textContent = 'INSTALLATION'; installSection.appendChild(installHeader); - // Claude installation - const claudeLabel = document.createElement('div'); - claudeLabel.className = 'modal-section-label'; - claudeLabel.textContent = 'Claude Code:'; - claudeLabel.style.marginTop = '1rem'; - installSection.appendChild(claudeLabel); - - const claudeCodeWrapper = document.createElement('div'); - claudeCodeWrapper.className = 'install-code-wrapper'; - - const claudePre = document.createElement('pre'); - const claudeCode = document.createElement('code'); - // Get plugin name from plugin.json or use pack name as fallback - const pluginName = pack.plugin.name || pack.name; - claudeCode.textContent = `claude plugin marketplace remove redhat-agentic-collections -claude plugin marketplace add https://github.com/RHEcosystemAppEng/agentic-collections -claude plugin install ${pluginName}`; - claudePre.appendChild(claudeCode); - claudeCodeWrapper.appendChild(claudePre); - - const claudeCopyBtn = document.createElement('button'); - claudeCopyBtn.className = 'copy-button'; - claudeCopyBtn.textContent = 'Copy'; - claudeCopyBtn.onclick = () => copyToClipboard(claudeCode.textContent, claudeCopyBtn); - claudeCodeWrapper.appendChild(claudeCopyBtn); - - installSection.appendChild(claudeCodeWrapper); - - // Cursor installation - const cursorLabel = document.createElement('div'); - cursorLabel.className = 'modal-section-label'; - cursorLabel.textContent = 'Cursor:'; - cursorLabel.style.marginTop = '1.5rem'; - installSection.appendChild(cursorLabel); - - const cursorNote = document.createElement('div'); - cursorNote.style.color = 'var(--text-muted)'; - cursorNote.style.fontSize = '0.9rem'; - cursorNote.style.fontStyle = 'italic'; - cursorNote.style.marginTop = '0.5rem'; - cursorNote.textContent = 'Coming soon - Cursor support is planned for future releases'; - installSection.appendChild(cursorNote); + const lolaNote = document.createElement('div'); + lolaNote.style.color = 'var(--text-muted)'; + lolaNote.style.fontSize = '0.85rem'; + lolaNote.style.marginBottom = '0.75rem'; + lolaNote.textContent = 'Lola. Applies to current folder only.'; + installSection.appendChild(lolaNote); + + const moduleName = pack.name; + + const codeWrapper = document.createElement('div'); + codeWrapper.className = 'install-code-wrapper'; + + const installPre = document.createElement('pre'); + const installCode = document.createElement('code'); + installCode.textContent = `lola market add rh-agentic-collections https://raw.githubusercontent.com/RHEcosystemAppEng/agentic-collections/main/marketplace/rh-agentic-collection.yml +lola install -f ${moduleName}`; + installPre.appendChild(installCode); + codeWrapper.appendChild(installPre); + + const copyBtn = document.createElement('button'); + copyBtn.className = 'copy-button'; + copyBtn.textContent = 'Copy'; + copyBtn.onclick = () => copyToClipboard(installCode.textContent, copyBtn); + codeWrapper.appendChild(copyBtn); + + installSection.appendChild(codeWrapper); + + const optNote = document.createElement('div'); + optNote.style.color = 'var(--text-muted)'; + optNote.style.fontSize = '0.8rem'; + optNote.style.marginTop = '0.5rem'; + optNote.textContent = 'Add -a claude-code or -a cursor to target one assistant.'; + installSection.appendChild(optNote); + + const lolaLink = document.createElement('div'); + lolaLink.style.marginTop = '0.5rem'; + lolaLink.style.fontSize = '0.85rem'; + const lolaAnchor = document.createElement('a'); + lolaAnchor.href = 'https://github.com/RedHatProductSecurity/lola'; + lolaAnchor.target = '_blank'; + lolaAnchor.textContent = 'Lola →'; + lolaAnchor.style.color = 'var(--primary)'; + lolaAnchor.style.textDecoration = 'none'; + lolaAnchor.onmouseover = () => { lolaAnchor.style.textDecoration = 'underline'; }; + lolaAnchor.onmouseout = () => { lolaAnchor.style.textDecoration = 'none'; }; + lolaLink.appendChild(lolaAnchor); + installSection.appendChild(lolaLink); body.appendChild(installSection); @@ -961,7 +982,7 @@ function showMCPDetails(serverName, packName) { headerTop.appendChild(titleGroup); header.appendChild(headerTop); - // Description from .mcp.json or pack name + // Description from mcps.json or pack name const desc = document.createElement('div'); desc.className = 'modal-description'; if (server.description) { diff --git a/docs/index.html b/docs/index.html index 75b52027..4d005fea 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,7 +4,7 @@ Agentic Skills packs - +
@@ -44,6 +44,21 @@

Red Hat Agentic Catalog

+ +
@@ -87,6 +102,6 @@

- + diff --git a/docs/styles.css b/docs/styles.css index 470859bd..bc4c4b1a 100644 --- a/docs/styles.css +++ b/docs/styles.css @@ -167,6 +167,122 @@ header { background: var(--bg-card); } +/* Red Hat Ecosystem Catalog–style: light gray with subtle teal dot pattern */ +.install-callout { + display: block; + padding: 1rem 2rem; + background-color: #f5f5f5; + background-image: radial-gradient(circle, rgba(0, 137, 123, 0.08) 1px, transparent 1px); + background-size: 12px 12px; + border-top: 1px solid var(--border); + border-left: 4px solid var(--primary); + font-size: 0.9rem; + color: var(--text-secondary); + min-height: 3rem; +} + +.install-callout-toggle { + display: flex; + align-items: center; + justify-content: space-between; + flex-wrap: wrap; + gap: 0.5rem; + cursor: pointer; + user-select: none; + min-height: 1.5rem; +} + +.install-callout-toggle:hover { + color: var(--text-primary); +} + +.install-callout-arrow { + display: inline-block; + font-size: 0.75rem; + margin-right: 0.25rem; + transition: transform var(--transition-speed); +} + +.install-callout:not(.collapsed) .install-callout-arrow { + transform: rotate(90deg); +} + +.install-callout-body { + margin-top: 1rem; + padding-top: 0.5rem; + border-top: 1px solid var(--border); +} + +.install-callout.collapsed .install-callout-body { + display: none; +} + +.install-callout-label { + flex: 1; + font-weight: 600; + color: var(--text-primary); +} + +.install-callout-link { + color: var(--primary); + text-decoration: none; + font-size: 0.9rem; + font-weight: 500; +} + +.install-callout-link:hover { + text-decoration: underline; +} + +.install-callout-command { + display: flex; + align-items: flex-start; + gap: 0.75rem; + margin-bottom: 0.5rem; +} + +.install-callout-command pre { + flex: 1; + min-width: 0; + margin: 0; + padding: 0.5rem 0.75rem; + background: var(--bg-code); + border-radius: 6px; + overflow-x: auto; +} + +.install-callout-command code { + font-size: 0.85rem; + word-break: break-all; +} + +.install-callout-note { + margin: 0; + font-size: 0.85rem; + color: var(--text-muted); +} + +.install-callout-note code { + padding: 0.15rem 0.4rem; + background: var(--bg-code); + border-radius: 4px; + font-size: 0.8rem; +} + +.install-callout a { + color: var(--primary); + text-decoration: none; +} + +.install-callout a:hover { + text-decoration: underline; +} + +.install-callout .copy-button { + position: static; + flex-shrink: 0; +} + #searchInput { width: 100%; padding: 1rem 1.5rem; @@ -785,6 +901,23 @@ footer a:hover { padding: 1rem; } + .install-callout { + padding: 1rem; + } + + .install-callout-toggle { + gap: 0.25rem; + } + + .install-callout-command { + flex-direction: column; + align-items: stretch; + } + + .install-callout .copy-button { + align-self: flex-start; + } + .grid { grid-template-columns: 1fr; } diff --git a/marketplace/rh-agentic-collection.yml b/marketplace/rh-agentic-collection.yml new file mode 100644 index 00000000..140ef1b8 --- /dev/null +++ b/marketplace/rh-agentic-collection.yml @@ -0,0 +1,66 @@ +name: "RH Agentic Collections Marketplace" +description: "Official curated collection of RH Agentic Collections modules" +url: "https://github.com/RHEcosystemAppEng/agentic-collections" +version: "0.0.1" + +modules: + - name: "ocp-admin" + description: "Automation capabilities for OpenShift Container Platform cluster management, workload orchestration, security policies, and operational tasks." + version: "0.0.1" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + path: "ocp-admin" + tags: + - "red-hat" + - "openshift" + - "administration" + - "management" + + - name: "rh-developer" + description: "Plugins for building and deploying applications on Red Hat platforms." + version: "0.0.1" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + path: "rh-developer" + tags: + - "developer" + - "openshift" + - "rhel" + - "s2i" + - "containerization" + - "deployment" + - "helm" + - "podman" + + - name: "rh-sre" + description: "Site reliability engineering tools and automation for managing Red Hat platforms and infrastructure." + version: "0.0.1" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + path: "rh-sre" + tags: + - "sre" + - "red-hat" + - "platforms" + - "products" + - "automation" + + - name: "rh-support-engineer" + description: "Technical support and troubleshooting tools for Red Hat products and platforms." + version: "0.0.1" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + path: "rh-support-engineer" + tags: + - "red-hat" + - "support" + - "troubleshooting" + - "engineering" + + - name: "rh-virt" + description: "Virtual machine management and automation for OpenShift Virtualization and KubeVirt workloads." + version: "0.0.1" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + path: "rh-virt" + tags: + - "red-hat" + - "kubevirt" + - "openshift" + - "virtualization" + - "virt" \ No newline at end of file diff --git a/ocp-admin/.claude-plugin/plugin.json b/ocp-admin/.claude-plugin/plugin.json deleted file mode 100644 index 895a01ed..00000000 --- a/ocp-admin/.claude-plugin/plugin.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "name": "openshift-administration", - "version": "1.0.0", - "description": "Automation capabilities for OpenShift Container Platform cluster management, workload orchestration, security policies, and operational tasks.", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["red-hat", "openshift", "administration", "management"] -} diff --git a/rh-developer/.claude-plugin/plugin.json b/rh-developer/.claude-plugin/plugin.json deleted file mode 100644 index 5232eb81..00000000 --- a/rh-developer/.claude-plugin/plugin.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "name": "rh-developer", - "version": "1.0.0", - "description": "Plugins for building and deploying applications on Red Hat platforms.", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["developer", "openshift", "rhel", "s2i", "containerization", "deployment", "helm", "podman"] -} diff --git a/rh-developer/.mcp.json b/rh-developer/mcps.json similarity index 100% rename from rh-developer/.mcp.json rename to rh-developer/mcps.json diff --git a/rh-sre/.claude-plugin/plugin.json b/rh-sre/.claude-plugin/plugin.json deleted file mode 100644 index 3731cfd2..00000000 --- a/rh-sre/.claude-plugin/plugin.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "name": "rh-sre", - "version": "1.0.0", - "description": "Site reliability engineering tools and automation for managing Red Hat platforms and infrastructure.", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["sre", "red-hat", "platforms", "products", "automation"] -} diff --git a/rh-sre/README.md b/rh-sre/README.md index 941b7f56..35ec8a31 100644 --- a/rh-sre/README.md +++ b/rh-sre/README.md @@ -283,7 +283,7 @@ Validate Red Hat Lightspeed MCP server configuration and connectivity. - Other skills need to verify lightspeed-mcp availability **What it does:** -- Checks MCP server configuration in .mcp.json +- Checks MCP server configuration in mcps.json - Verifies environment variables (CLIENT_ID, CLIENT_SECRET) - Tests server connectivity and tool availability - Reports validation status (PASSED/PARTIAL/FAILED) @@ -413,7 +413,7 @@ See [docs/INDEX.md](docs/INDEX.md) for the complete documentation map. ## MCP Server Integrations -The pack integrates with three MCP servers (configured in `.mcp.json`): +The pack integrates with three MCP servers (configured in `mcps.json`): ### 1. **lightspeed-mcp** - Red Hat Lightspeed Platform - CVE data and vulnerability management @@ -493,7 +493,7 @@ All MCP servers run locally in containers for security: ## Configuration -MCP servers are configured in `.mcp.json`: +MCP servers are configured in `mcps.json`: ```json { @@ -602,7 +602,7 @@ rh-sre/ ├── README.md # This file ├── .claude-plugin/ │ └── plugin.json # Plugin metadata -├── .mcp.json # MCP server configurations +├── mcps.json # MCP server configurations ├── skills/ │ ├── remediation/SKILL.md # Orchestration skill (end-to-end CVE remediation) │ ├── fleet-inventory/SKILL.md diff --git a/rh-sre/docs/testing/aap-integration-test-guide.md b/rh-sre/docs/testing/aap-integration-test-guide.md index 6c122770..bc6d7f84 100644 --- a/rh-sre/docs/testing/aap-integration-test-guide.md +++ b/rh-sre/docs/testing/aap-integration-test-guide.md @@ -41,7 +41,7 @@ This guide provides a comprehensive testing plan for the AAP MCP integration, co - SSH access configured with credentials in AAP 4. **MCP Configuration**: - - `rh-sre/.mcp.json` configured with AAP MCP servers + - `rh-sre/mcps.json` configured with AAP MCP servers - `lightspeed-mcp` configured and working - All environment variables set diff --git a/rh-sre/.mcp.json b/rh-sre/mcps.json similarity index 100% rename from rh-sre/.mcp.json rename to rh-sre/mcps.json diff --git a/rh-sre/skills/cve-impact/SKILL.md b/rh-sre/skills/cve-impact/SKILL.md index 64af589e..2f671a03 100644 --- a/rh-sre/skills/cve-impact/SKILL.md +++ b/rh-sre/skills/cve-impact/SKILL.md @@ -407,4 +407,4 @@ This skill primarily uses: - `inventory__find_host_by_name` (inventory toolset) - Resolve hostname to system UUID before get_system_cves - `get_host_details` (inventory toolset) - Get detailed system information (optional) -All tools are provided by the lightspeed-mcp MCP server configured in `.mcp.json`. +All tools are provided by the lightspeed-mcp MCP server configured in `mcps.json`. diff --git a/rh-sre/skills/cve-validation/SKILL.md b/rh-sre/skills/cve-validation/SKILL.md index 710a2248..abb906f7 100644 --- a/rh-sre/skills/cve-validation/SKILL.md +++ b/rh-sre/skills/cve-validation/SKILL.md @@ -339,7 +339,7 @@ This skill uses: **Do NOT use** `vulnerability__explain_cves` in this skill—it requires `system_uuid` which may not be available at validation time. Use `get_cve` only. -All tools are provided by the lightspeed-mcp MCP server configured in `.mcp.json`. +All tools are provided by the lightspeed-mcp MCP server configured in `mcps.json`. ## Integration with Other Skills diff --git a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md index e4247985..86bc1334 100644 --- a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md +++ b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md @@ -32,7 +32,7 @@ When the tool call fails, include: - **Expired credentials**: Red Hat Console tokens may have expired - **Server not running**: MCP server/container may be stopped - **Network**: Firewall or proxy blocking console.redhat.com -- **Configuration**: .mcp.json misconfigured or server not registered +- **Configuration**: mcps.json misconfigured or server not registered **Troubleshooting:** 1. Verify env vars: LIGHTSPEED_CLIENT_ID, LIGHTSPEED_CLIENT_SECRET (never echo values) diff --git a/rh-sre/skills/playbook-generator/SKILL.md b/rh-sre/skills/playbook-generator/SKILL.md index 066012d3..b811fe69 100644 --- a/rh-sre/skills/playbook-generator/SKILL.md +++ b/rh-sre/skills/playbook-generator/SKILL.md @@ -366,7 +366,7 @@ Proceeding with standard playbook (without pod eviction). Add pod eviction manua This skill uses: - `remediations__create_vuln_playbook` (from lightspeed-mcp) - Generate playbook from Red Hat Lightspeed. Returns YAML **as is**—do not modify. -All MCP tools are provided by the lightspeed-mcp server configured in `.mcp.json`. +All MCP tools are provided by the lightspeed-mcp server configured in `mcps.json`. ## Integration with Other Skills diff --git a/rh-support-engineer/.claude-plugin/plugin.json b/rh-support-engineer/.claude-plugin/plugin.json deleted file mode 100644 index c0ce1ae0..00000000 --- a/rh-support-engineer/.claude-plugin/plugin.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "name": "rh-support-engineer", - "version": "1.0.0", - "description": "Technical support and troubleshooting tools for Red Hat products and platforms.", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["red-hat", "support", "troubleshooting", "engineering"] -} diff --git a/rh-virt/.claude-plugin/plugin.json b/rh-virt/.claude-plugin/plugin.json deleted file mode 100644 index 3d0dd091..00000000 --- a/rh-virt/.claude-plugin/plugin.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "name": "openshift-virtualization", - "version": "1.0.0", - "description": "Virtual machine management and automation for OpenShift Virtualization and KubeVirt workloads.", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": ["red-hat", "kubevirt", "openshift", "virtualization"] -} diff --git a/rh-virt/README.md b/rh-virt/README.md index c8869697..3d739d6a 100644 --- a/rh-virt/README.md +++ b/rh-virt/README.md @@ -214,7 +214,7 @@ Clone existing virtual machines for testing, scaling, or creating VM templates. ## MCP Server Integration -The pack integrates with the OpenShift MCP server (configured in `.mcp.json`), which provides two toolsets for comprehensive cluster and virtualization management: +The pack integrates with the OpenShift MCP server (configured in `mcps.json`), which provides two toolsets for comprehensive cluster and virtualization management: ### **openshift-virtualization** - OpenShift MCP Server @@ -413,7 +413,7 @@ Agent: "✓ Workaround Applied Successfully ## Configuration -MCP server is configured in `.mcp.json`: +MCP server is configured in `mcps.json`: ```json { @@ -513,7 +513,7 @@ rh-virt/ ├── README.md # This file ├── .claude-plugin/ │ └── plugin.json # Plugin metadata -├── .mcp.json # MCP server configuration +├── mcps.json # MCP server configuration ├── docs/ # AI-optimized knowledge base │ └── troubleshooting/ # VM error diagnosis and workarounds (categorized by error type) │ ├── INDEX.md # Navigation hub for troubleshooting docs diff --git a/rh-virt/SKILL_TEMPLATE.md b/rh-virt/SKILL_TEMPLATE.md index eb29425a..bbcc57b9 100644 --- a/rh-virt/SKILL_TEMPLATE.md +++ b/rh-virt/SKILL_TEMPLATE.md @@ -124,7 +124,7 @@ metadata: # Optional: Custom fields (2026 Agentic Skills standard **Before executing, verify MCP server availability:** 1. **Check MCP Server Configuration** - - Verify `openshift-virtualization` exists in `.mcp.json` + - Verify `openshift-virtualization` exists in `mcps.json` - If missing → Report to user with setup instructions 2. **Check Environment Variables** @@ -143,7 +143,7 @@ When prerequisites fail: ❌ Cannot execute : MCP server 'openshift-virtualization' is not available 📋 Setup Instructions: -1. Add openshift-virtualization to .mcp.json +1. Add openshift-virtualization to mcps.json 2. Set KUBECONFIG environment variable: export KUBECONFIG="/path/to/kubeconfig" 3. Restart Claude Code to reload MCP servers diff --git a/rh-virt/.mcp.json b/rh-virt/mcps.json similarity index 100% rename from rh-virt/.mcp.json rename to rh-virt/mcps.json diff --git a/rh-virt/skills/vm-clone/SKILL.md b/rh-virt/skills/vm-clone/SKILL.md index 09ad791f..b86f4781 100644 --- a/rh-virt/skills/vm-clone/SKILL.md +++ b/rh-virt/skills/vm-clone/SKILL.md @@ -41,16 +41,48 @@ Clone existing virtual machines in OpenShift Virtualization, creating new VMs wi ### Prerequisite Verification -**Before executing:** -1. Verify `openshift-virtualization` in `.mcp.json`, `KUBECONFIG` set (never expose value) -2. Optional: Verify RBAC permissions for VirtualMachine, PVC/DataVolume creation +**Before executing, verify MCP server availability:** + +1. **Check MCP Server Configuration** + - Verify `openshift-virtualization` exists in `mcps.json` + - If missing → Report to user with setup instructions + +2. **Check Environment Variables** + - Verify `KUBECONFIG` is set (check presence only, never expose value) + - If missing → Report to user + +3. **Check RBAC Permissions** (optional verification) + - Verify ServiceAccount can create VirtualMachine resources + - Verify ServiceAccount can create PVC/DataVolume resources **When prerequisites fail:** ``` ❌ Cannot execute vm-clone: MCP server 'openshift-virtualization' is not available -Setup: Add openshift-virtualization to .mcp.json (see https://github.com/openshift/openshift-mcp-server) -Set KUBECONFIG environment variable, restart Claude Code +📋 Setup Instructions: +1. Add openshift-virtualization to mcps.json: + { + "mcpServers": { + "openshift-virtualization": { + "command": "podman", + "args": [ + "run", + "--rm", + "-i", + "--network=host", + "--userns=keep-id:uid=65532,gid=65532", + "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", + "--entrypoint", "/app/kubernetes-mcp-server", + "quay.io/ecosystem-appeng/openshift-mcp-server:latest", + "--kubeconfig", "/kubeconfig", + "--toolsets", "core,kubevirt" + ], + "env": { + "KUBECONFIG": "${KUBECONFIG}" + } + } + } + } Options: "setup" (configure now), "skip" (skip skill), "abort" (stop workflow) ``` diff --git a/rh-virt/skills/vm-create/SKILL.md b/rh-virt/skills/vm-create/SKILL.md index ac78ed8c..84f1be50 100644 --- a/rh-virt/skills/vm-create/SKILL.md +++ b/rh-virt/skills/vm-create/SKILL.md @@ -46,15 +46,58 @@ Create virtual machines in OpenShift Virtualization using the `vm_create` tool f **Before executing, verify MCP server availability:** -1. Check `openshift-virtualization` exists in `.mcp.json` → If missing, report setup instructions -2. Verify `KUBECONFIG` is set (check presence only, never expose value) → If missing, report to user +1. **Check MCP Server Configuration** + - Verify `openshift-virtualization` exists in `mcps.json` + - If missing → Report to user with setup instructions + +2. **Check Environment Variables** + - Verify `KUBECONFIG` is set (check presence only, never expose value) + - If missing → Report to user **Human Notification Protocol (when prerequisites fail):** ``` -❌ Cannot execute vm-create: MCP server 'openshift-virtualization' not available -📋 Setup: Add to .mcp.json, set KUBECONFIG env var, restart Claude Code -🔗 Docs: https://github.com/openshift/openshift-mcp-server +❌ Cannot execute vm-create: MCP server 'openshift-virtualization' is not available + +📋 Setup Instructions: +1. Add openshift-virtualization to mcps.json: + { + "mcpServers": { + "openshift-virtualization": { + "command": "podman", + "args": [ + "run", + "--rm", + "-i", + "--network=host", + "--userns=keep-id:uid=65532,gid=65532", + "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", + "--entrypoint", "/app/kubernetes-mcp-server", + "quay.io/ecosystem-appeng/openshift-mcp-server:latest", + "--kubeconfig", "/kubeconfig", + "--toolsets", "core,kubevirt" + ], + "env": { + "KUBECONFIG": "${KUBECONFIG}" + } + } + } + } + +2. Set KUBECONFIG environment variable: + export KUBECONFIG="/path/to/your/kubeconfig" + +3. Restart Claude Code to reload MCP servers + +🔗 Documentation: https://github.com/openshift/openshift-mcp-server + +❓ How would you like to proceed? +Options: +- "setup" - Help configure the MCP server now +- "skip" - Skip this skill +- "abort" - Stop workflow + +Please respond with your choice. ``` ⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values. diff --git a/rh-virt/skills/vm-delete/SKILL.md b/rh-virt/skills/vm-delete/SKILL.md index ee231a9a..359007bc 100644 --- a/rh-virt/skills/vm-delete/SKILL.md +++ b/rh-virt/skills/vm-delete/SKILL.md @@ -45,13 +45,67 @@ Permanently delete virtual machines and their associated resources (storage, Dat **Before executing:** -1. Check `openshift-virtualization` exists in `.mcp.json` → If missing, report setup -2. Verify `KUBECONFIG` is set (presence only, never expose value) → If missing, report -3. Check RBAC permissions (optional) → Verify delete permissions for VirtualMachine and PVC +1. **Check MCP Server Configuration** + - Verify `openshift-virtualization` exists in `mcps.json` + - If missing → Report to user with setup instructions -**Human Notification Protocol:** `❌ Cannot execute vm-delete: MCP server not available. Setup: Add to .mcp.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` +2. **Check Environment Variables** + - Verify `KUBECONFIG` is set (presence only, never expose value) + - If missing → Report to user -⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. +3. **Check RBAC Permissions** (optional verification) + - Verify ServiceAccount can delete VirtualMachine resources + - Verify ServiceAccount can delete PVC/DataVolume resources + +**Human Notification Protocol:** + +When prerequisites fail: + +``` +❌ Cannot execute vm-delete: MCP server 'openshift-virtualization' is not available + +📋 Setup Instructions: +1. Add openshift-virtualization to mcps.json: + { + "mcpServers": { + "openshift-virtualization": { + "command": "podman", + "args": [ + "run", + "--rm", + "-i", + "--network=host", + "--userns=keep-id:uid=65532,gid=65532", + "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", + "--entrypoint", "/app/kubernetes-mcp-server", + "quay.io/ecosystem-appeng/openshift-mcp-server:latest", + "--kubeconfig", "/kubeconfig", + "--toolsets", "core,kubevirt" + ], + "env": { + "KUBECONFIG": "${KUBECONFIG}" + } + } + } + } + +2. Set KUBECONFIG environment variable: + export KUBECONFIG="/path/to/your/kubeconfig" + +3. Restart Claude Code to reload MCP servers + +🔗 Documentation: https://github.com/openshift/openshift-mcp-server + +❓ How would you like to proceed? +Options: +- "setup" - Help configure the MCP server now +- "skip" - Skip this skill +- "abort" - Stop workflow + +Please respond with your choice. +``` + +⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values in output. ## When to Use This Skill diff --git a/rh-virt/skills/vm-inventory/SKILL.md b/rh-virt/skills/vm-inventory/SKILL.md index 32873b81..54357156 100644 --- a/rh-virt/skills/vm-inventory/SKILL.md +++ b/rh-virt/skills/vm-inventory/SKILL.md @@ -45,15 +45,71 @@ List and inspect virtual machines in OpenShift Virtualization clusters. This ski **Before executing:** -1. Check `openshift-virtualization` exists in `.mcp.json` → If missing, report setup -2. Verify `KUBECONFIG` is set (presence only, never expose value) → If missing, report +1. **Check MCP Server Configuration** + - Verify `openshift-virtualization` exists in `mcps.json` + - If missing → Report to user with setup instructions + +2. **Check Environment Variables** + - Verify `KUBECONFIG` is set (presence only, never expose value) + - If missing → Report to user + 3. (Optional) Test basic connectivity to cluster → If fails, report connection error -**Human Notification Protocol:** `❌ Cannot execute vm-inventory: MCP server not available. Setup: Add to .mcp.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` +**Human Notification Protocol:** + +When prerequisites fail: + +``` +❌ Cannot execute vm-inventory: MCP server 'openshift-virtualization' is not available + +📋 Setup Instructions: +1. Add openshift-virtualization to mcps.json: + { + "mcpServers": { + "openshift-virtualization": { + "command": "podman", + "args": [ + "run", + "--rm", + "-i", + "--network=host", + "--userns=keep-id:uid=65532,gid=65532", + "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", + "--entrypoint", "/app/kubernetes-mcp-server", + "quay.io/ecosystem-appeng/openshift-mcp-server:latest", + "--kubeconfig", "/kubeconfig", + "--toolsets", "core,kubevirt" + ], + "env": { + "KUBECONFIG": "${KUBECONFIG}" + } + } + } + } + +2. Set KUBECONFIG environment variable: + export KUBECONFIG="/path/to/your/kubeconfig" + +3. Restart Claude Code to reload MCP servers + +🔗 Documentation: https://github.com/openshift/openshift-mcp-server + +❓ How would you like to proceed? +Options: +- "setup" - Help configure the MCP server now +- "cli" - Use OpenShift CLI commands as fallback (requires KUBECONFIG) +- "skip" - Skip this skill +- "abort" - Stop workflow + +Please respond with your choice. +``` -⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. +⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values in output. -**Note on Fallback**: If MCP server unavailable but KUBECONFIG set, offer CLI fallback with user confirmation. +**Note on Fallback Behavior**: +- If MCP server is unavailable but KUBECONFIG is set, the skill CAN proceed with CLI commands +- Always offer the user the choice between setup (MCP) or CLI fallback +- CLI fallback requires explicit user confirmation before executing any commands ## When to Use This Skill diff --git a/rh-virt/skills/vm-lifecycle-manager/SKILL.md b/rh-virt/skills/vm-lifecycle-manager/SKILL.md index cf4e0da4..20ca2bad 100644 --- a/rh-virt/skills/vm-lifecycle-manager/SKILL.md +++ b/rh-virt/skills/vm-lifecycle-manager/SKILL.md @@ -40,12 +40,67 @@ Control virtual machine power state in OpenShift Virtualization using the `vm_li **Before executing:** -1. Check `openshift-virtualization` exists in `.mcp.json` → If missing, report setup -2. Verify `KUBECONFIG` is set (presence only, never expose value) → If missing, report +1. **Check MCP Server Configuration** + - Verify `openshift-virtualization` exists in `mcps.json` + - If missing → Report to user with setup instructions -**Human Notification Protocol:** `❌ Cannot execute vm-lifecycle-manager: MCP server not available. Setup: Add to .mcp.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` +2. **Check Environment Variables** + - Verify `KUBECONFIG` is set (presence only, never expose value) + - If missing → Report to user -⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. +3. **Verify VM Exists** (optional quick check) + - Confirm target VM exists in specified namespace + - If VM not found → Report error to user + +**Human Notification Protocol:** + +When prerequisites fail: + +``` +❌ Cannot execute vm-lifecycle-manager: MCP server 'openshift-virtualization' is not available + +📋 Setup Instructions: +1. Add openshift-virtualization to mcps.json: + { + "mcpServers": { + "openshift-virtualization": { + "command": "podman", + "args": [ + "run", + "--rm", + "-i", + "--network=host", + "--userns=keep-id:uid=65532,gid=65532", + "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", + "--entrypoint", "/app/kubernetes-mcp-server", + "quay.io/ecosystem-appeng/openshift-mcp-server:latest", + "--kubeconfig", "/kubeconfig", + "--toolsets", "core,kubevirt" + ], + "env": { + "KUBECONFIG": "${KUBECONFIG}" + } + } + } + } + +2. Set KUBECONFIG environment variable: + export KUBECONFIG="/path/to/your/kubeconfig" + +3. Restart Claude Code to reload MCP servers + +🔗 Documentation: https://github.com/openshift/openshift-mcp-server + +❓ How would you like to proceed? +Options: +- "setup" - Help configure the MCP server now +- "skip" - Skip this skill +- "abort" - Stop workflow + +Please respond with your choice. +``` + +⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values in output. ## When to Use This Skill diff --git a/rh-virt/skills/vm-rebalance/SKILL.md b/rh-virt/skills/vm-rebalance/SKILL.md index 4bc6c8ff..57275731 100644 --- a/rh-virt/skills/vm-rebalance/SKILL.md +++ b/rh-virt/skills/vm-rebalance/SKILL.md @@ -48,13 +48,31 @@ Orchestrate VM migrations across OpenShift cluster nodes for load balancing, mai **Before executing:** -1. Check `openshift-virtualization` exists in `.mcp.json` → If missing, report setup -2. Verify `KUBECONFIG` is set (presence only, never expose value) → If missing, report -3. For live migration: Check PVC access mode is ReadWriteMany (RWX) via `resources_get` +1. **Check MCP Server** - Verify `openshift-virtualization` exists in `mcps.json` +2. **Check Environment** - Verify `KUBECONFIG` is set (check presence only, never expose value) +3. **Check Capability** (for live migration): + - Use `resources_get` to check PVC access mode is ReadWriteMany (RWX) + - Verify VM has running VirtualMachineInstance -**Human Notification Protocol:** `❌ Cannot execute vm-rebalance: MCP server not available. Setup: Add to .mcp.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` +**Human Notification Protocol:** -⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. +When prerequisites fail: + +``` +❌ Cannot execute vm-rebalance: MCP server 'openshift-virtualization' is not available + +📋 Setup Instructions: +1. Add openshift-virtualization to mcps.json +2. Set KUBECONFIG environment variable +3. Ensure ServiceAccount has required permissions +4. Restart Claude Code to reload MCP servers + +🔗 Documentation: https://github.com/openshift/openshift-mcp-server + +Options: "setup" | "skip" | "abort" +``` + +⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values in output. ## When to Use This Skill diff --git a/rh-virt/skills/vm-snapshot-delete/SKILL.md b/rh-virt/skills/vm-snapshot-delete/SKILL.md index 14f2fb49..a5ae9360 100644 --- a/rh-virt/skills/vm-snapshot-delete/SKILL.md +++ b/rh-virt/skills/vm-snapshot-delete/SKILL.md @@ -42,7 +42,7 @@ Permanently delete virtual machine snapshots in OpenShift Virtualization. Deleti **Before executing, verify MCP server availability:** 1. **Check MCP Server Configuration** - - Verify `openshift-virtualization` exists in `.mcp.json` + - Verify `openshift-virtualization` exists in `mcps.json` - If missing → Report to user with setup instructions 2. **Check Environment Variables** diff --git a/rh-virt/skills/vm-snapshot-list/SKILL.md b/rh-virt/skills/vm-snapshot-list/SKILL.md index 3f199f8f..2ffde5e7 100644 --- a/rh-virt/skills/vm-snapshot-list/SKILL.md +++ b/rh-virt/skills/vm-snapshot-list/SKILL.md @@ -41,7 +41,7 @@ List virtual machine snapshots in OpenShift Virtualization. This read-only skill **Before executing, verify MCP server availability:** 1. **Check MCP Server Configuration** - - Verify `openshift-virtualization` exists in `.mcp.json` + - Verify `openshift-virtualization` exists in `mcps.json` - If missing → Report to user with setup instructions 2. **Check Environment Variables** @@ -56,7 +56,7 @@ When prerequisites fail: ❌ Cannot execute vm-snapshot-list: MCP server 'openshift-virtualization' is not available 📋 Setup Instructions: -1. Add openshift-virtualization to .mcp.json +1. Add openshift-virtualization to mcps.json 2. Set KUBECONFIG environment variable 3. Restart Claude Code to reload MCP servers diff --git a/scripts/generate_mcp_data.py b/scripts/generate_mcp_data.py index 7aff4f2f..1374f864 100644 --- a/scripts/generate_mcp_data.py +++ b/scripts/generate_mcp_data.py @@ -1,9 +1,10 @@ #!/usr/bin/env python3 """ -Parse .mcp.json files and extract MCP server configurations. +Parse mcps.json files and extract MCP server configurations. """ import json +import sys import re from pathlib import Path from typing import Dict, List, Any @@ -11,6 +12,9 @@ # List of agentic packs to parse PACK_DIRS = ['rh-sre', 'rh-developer', 'ocp-admin', 'rh-support-engineer', 'rh-virt', 'rh-ai-engineer', 'rh-automation'] +MCP_FILENAME = "mcps.json" +MCP_DEPRECATED = ".mcp.json" + def extract_env_vars(env_dict: Dict[str, str]) -> List[str]: """ @@ -62,8 +66,9 @@ def extract_header_env_vars(headers: Dict[str, str]) -> List[str]: def parse_mcp_file(pack_dir: str) -> List[Dict[str, Any]]: """ - Parse .mcp.json file from a pack directory. + Parse mcps.json file from a pack directory. Supports both command-based and HTTP-based MCP servers. + Errors if deprecated .mcp.json exists (must be renamed to mcps.json). Args: pack_dir: Name of the pack directory @@ -71,7 +76,13 @@ def parse_mcp_file(pack_dir: str) -> List[Dict[str, Any]]: Returns: List of MCP server configurations """ - mcp_file = Path(pack_dir) / '.mcp.json' + pack_path = Path(pack_dir) + deprecated_path = pack_path / MCP_DEPRECATED + mcp_file = pack_path / MCP_FILENAME + + if deprecated_path.exists(): + print(f"Error: {pack_dir}/{MCP_DEPRECATED} is deprecated; rename to {MCP_FILENAME}", file=sys.stderr) + sys.exit(1) if not mcp_file.exists(): return [] @@ -153,7 +164,7 @@ def load_custom_mcp_data() -> Dict[str, Any]: def generate_mcp_data() -> List[Dict[str, Any]]: """ Generate MCP server data for all agentic packs. - Merges data from .mcp.json files with custom data from docs/mcp.json. + Merges data from mcps.json files with custom data from docs/mcp.json. Returns: List of MCP server dictionaries diff --git a/scripts/validate_skill_design.py b/scripts/validate_skill_design.py index 6bef12fb..fc6bb063 100644 --- a/scripts/validate_skill_design.py +++ b/scripts/validate_skill_design.py @@ -3,6 +3,7 @@ Validate skills against SKILL_DESIGN_PRINCIPLES.md. Design principles checked: + DP0: Pack layout (Lola format) - mcps.json only, error if .mcp.json exists DP1: Document Consultation - correct format (Action: Read, Output to user) DP2: Parameter order - Document Consultation before MCP Tool/Parameters DP3: Conciseness - description length, "Use when" examples @@ -18,6 +19,7 @@ from __future__ import annotations import argparse +import json import re import sys from dataclasses import dataclass, field @@ -84,6 +86,40 @@ # Anti-pattern context: if echo $VAR appears near these, it may be documenting the wrong way ANTI_PATTERN_MARKERS = ["WRONG", "NEVER", "❌", "don't", "do not", "exposes credentials"] +# Pack layout (Lola format) +MCP_FILENAME = "mcps.json" +MCP_DEPRECATED = ".mcp.json" + + +def validate_pack_layout(pack_dir: Path) -> list[str]: + """ + DP0: Pack layout (Lola format). + Error if .mcp.json exists; validate mcps.json structure if present. + """ + errors = [] + deprecated = pack_dir / MCP_DEPRECATED + mcp_file = pack_dir / MCP_FILENAME + + if deprecated.exists(): + errors.append( + f"DP0: deprecated {MCP_DEPRECATED} found; rename to {MCP_FILENAME}" + ) + return errors + + if not mcp_file.exists(): + return errors + + try: + data = json.loads(mcp_file.read_text(encoding="utf-8")) + if "mcpServers" not in data: + errors.append(f"DP0: {MCP_FILENAME} missing 'mcpServers' key") + elif not isinstance(data.get("mcpServers"), dict): + errors.append(f"DP0: {MCP_FILENAME} 'mcpServers' must be an object") + except Exception as e: + errors.append(f"DP0: Invalid {MCP_FILENAME}: {e}") + + return errors + @dataclass class ValidationResult: @@ -444,16 +480,38 @@ def main() -> int: if (pack_path / "skills").exists(): skill_files.extend((pack_path / "skills").glob("*/SKILL.md")) + all_errors: list[tuple[Path, str]] = [] + all_warnings: list[tuple[Path, str]] = [] + + # Collect pack dirs for layout validation (all pack dirs from args, plus from skill paths) + pack_dirs: set[Path] = set() + for p in args.paths: + path = Path(p) + if path.is_dir() and path.exists(): + pack_dirs.add(path) + for sf in skill_files: + if sf.parent.parent.name == "skills": + pack_dirs.add(sf.parent.parent.parent) + + # DP0: Pack layout (Lola format) + for pack_dir in sorted(pack_dirs): + if pack_dir.exists(): + layout_errors = validate_pack_layout(pack_dir) + for err in layout_errors: + all_errors.append((pack_dir, err)) + if not skill_files: + if all_errors: + print("❌ Pack layout validation failed:") + for path, err in all_errors: + print(f" • {path}: {err}") + return 1 print("No SKILL.md files found to validate.") return 0 print("🔍 Validating skills against Design Principles...") print() - all_errors: list[tuple[Path, str]] = [] - all_warnings: list[tuple[Path, str]] = [] - for skill_path in sorted(skill_files): result = validate_skill(skill_path) rel_path = skill_path.relative_to(Path.cwd()) if skill_path.is_relative_to(Path.cwd()) else skill_path @@ -473,7 +531,15 @@ def main() -> int: else: print(f" {rel_path}: ✓") - print() + # Report pack layout errors first if any + if all_errors and any(e.startswith("DP0:") for _, e in all_errors): + layout_errs = [(p, e) for p, e in all_errors if e.startswith("DP0:")] + print() + print("Pack layout (Lola format):") + for path, err in layout_errs: + rel = path.relative_to(Path.cwd()) if path.is_relative_to(Path.cwd()) else path + print(f" {rel}: ❌ {err}") + print() if all_errors or (args.warnings_as_errors and all_warnings): print("❌ Validation failed") diff --git a/scripts/validate_structure.py b/scripts/validate_structure.py index 1b8c6077..7b81a685 100644 --- a/scripts/validate_structure.py +++ b/scripts/validate_structure.py @@ -53,9 +53,14 @@ def validate_plugin_json(pack_dir: str) -> List[str]: return errors +MCP_FILENAME = "mcps.json" +MCP_DEPRECATED = ".mcp.json" + + def validate_mcp_json(pack_dir: str) -> List[str]: """ - Validate .mcp.json structure. + Validate mcps.json structure. + Errors if deprecated .mcp.json exists (must be renamed to mcps.json). Args: pack_dir: Pack directory name @@ -64,10 +69,18 @@ def validate_mcp_json(pack_dir: str) -> List[str]: List of error messages (empty if valid) """ errors = [] - mcp_path = Path(pack_dir) / '.mcp.json' + pack_path = Path(pack_dir) + deprecated_path = pack_path / MCP_DEPRECATED + mcp_path = pack_path / MCP_FILENAME + + if deprecated_path.exists(): + errors.append( + f"{pack_dir}: deprecated {MCP_DEPRECATED} found; rename to {MCP_FILENAME}" + ) + return errors if not mcp_path.exists(): - # .mcp.json is optional + # mcps.json is optional return errors try: @@ -76,14 +89,14 @@ def validate_mcp_json(pack_dir: str) -> List[str]: # Check for mcpServers key if 'mcpServers' not in data: - errors.append(f"{pack_dir}: .mcp.json missing 'mcpServers' key") + errors.append(f"{pack_dir}: {MCP_FILENAME} missing 'mcpServers' key") elif not isinstance(data['mcpServers'], dict): - errors.append(f"{pack_dir}: .mcp.json 'mcpServers' must be an object") + errors.append(f"{pack_dir}: {MCP_FILENAME} 'mcpServers' must be an object") except json.JSONDecodeError as e: - errors.append(f"{pack_dir}: Invalid JSON in .mcp.json: {e}") + errors.append(f"{pack_dir}: Invalid JSON in {MCP_FILENAME}: {e}") except Exception as e: - errors.append(f"{pack_dir}: Error reading .mcp.json: {e}") + errors.append(f"{pack_dir}: Error reading {MCP_FILENAME}: {e}") return errors @@ -165,7 +178,7 @@ def validate_pack(pack_dir: str) -> List[str]: # Validate plugin.json errors.extend(validate_plugin_json(pack_dir)) - # Validate .mcp.json + # Validate mcps.json errors.extend(validate_mcp_json(pack_dir)) # Validate CLAUDE.md From 6a6730f8176a8cd2fc8e84a9b410a5ec98ba3d79 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Tue, 3 Mar 2026 15:56:00 +0100 Subject: [PATCH 2/9] rebased and updated ocp-admin Signed-off-by: Daniele Martinoli --- ocp-admin/{.mcp.json => mcps.json} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ocp-admin/{.mcp.json => mcps.json} (100%) diff --git a/ocp-admin/.mcp.json b/ocp-admin/mcps.json similarity index 100% rename from ocp-admin/.mcp.json rename to ocp-admin/mcps.json From 74fae2cc308f4ea72cc72ab11c4d70eb90efc923 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Tue, 3 Mar 2026 16:23:51 +0100 Subject: [PATCH 3/9] restored concise form Signed-off-by: Daniele Martinoli --- rh-virt/skills/vm-clone/SKILL.md | 48 ++------------- rh-virt/skills/vm-create/SKILL.md | 60 ++---------------- rh-virt/skills/vm-delete/SKILL.md | 65 ++------------------ rh-virt/skills/vm-inventory/SKILL.md | 62 ++----------------- rh-virt/skills/vm-lifecycle-manager/SKILL.md | 64 ++----------------- rh-virt/skills/vm-rebalance/SKILL.md | 29 ++------- 6 files changed, 27 insertions(+), 301 deletions(-) diff --git a/rh-virt/skills/vm-clone/SKILL.md b/rh-virt/skills/vm-clone/SKILL.md index b86f4781..a480ce3b 100644 --- a/rh-virt/skills/vm-clone/SKILL.md +++ b/rh-virt/skills/vm-clone/SKILL.md @@ -41,51 +41,11 @@ Clone existing virtual machines in OpenShift Virtualization, creating new VMs wi ### Prerequisite Verification -**Before executing, verify MCP server availability:** +**Before executing:** +1. Verify `openshift-virtualization` in `mcps.json`, `KUBECONFIG` set (never expose value) +2. Optional: Verify RBAC permissions for VirtualMachine, PVC/DataVolume creation -1. **Check MCP Server Configuration** - - Verify `openshift-virtualization` exists in `mcps.json` - - If missing → Report to user with setup instructions - -2. **Check Environment Variables** - - Verify `KUBECONFIG` is set (check presence only, never expose value) - - If missing → Report to user - -3. **Check RBAC Permissions** (optional verification) - - Verify ServiceAccount can create VirtualMachine resources - - Verify ServiceAccount can create PVC/DataVolume resources - -**When prerequisites fail:** -``` -❌ Cannot execute vm-clone: MCP server 'openshift-virtualization' is not available - -📋 Setup Instructions: -1. Add openshift-virtualization to mcps.json: - { - "mcpServers": { - "openshift-virtualization": { - "command": "podman", - "args": [ - "run", - "--rm", - "-i", - "--network=host", - "--userns=keep-id:uid=65532,gid=65532", - "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", - "--entrypoint", "/app/kubernetes-mcp-server", - "quay.io/ecosystem-appeng/openshift-mcp-server:latest", - "--kubeconfig", "/kubeconfig", - "--toolsets", "core,kubevirt" - ], - "env": { - "KUBECONFIG": "${KUBECONFIG}" - } - } - } - } - -Options: "setup" (configure now), "skip" (skip skill), "abort" (stop workflow) -``` +**Human Notification Protocol:** `❌ Cannot execute vm-clone: MCP server 'openshift-virtualization' is not available. Setup: Add to mcps.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` ⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. diff --git a/rh-virt/skills/vm-create/SKILL.md b/rh-virt/skills/vm-create/SKILL.md index 84f1be50..02929f1f 100644 --- a/rh-virt/skills/vm-create/SKILL.md +++ b/rh-virt/skills/vm-create/SKILL.md @@ -44,63 +44,13 @@ Create virtual machines in OpenShift Virtualization using the `vm_create` tool f ### Prerequisite Verification -**Before executing, verify MCP server availability:** +**Before executing:** +1. Check `openshift-virtualization` exists in `mcps.json` → If missing, report setup instructions +2. Verify `KUBECONFIG` is set (check presence only, never expose value) → If missing, report to user -1. **Check MCP Server Configuration** - - Verify `openshift-virtualization` exists in `mcps.json` - - If missing → Report to user with setup instructions +**Human Notification Protocol:** `❌ Cannot execute vm-create: MCP server 'openshift-virtualization' not available. Setup: Add to mcps.json, set KUBECONFIG env var, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` -2. **Check Environment Variables** - - Verify `KUBECONFIG` is set (check presence only, never expose value) - - If missing → Report to user - -**Human Notification Protocol (when prerequisites fail):** - -``` -❌ Cannot execute vm-create: MCP server 'openshift-virtualization' is not available - -📋 Setup Instructions: -1. Add openshift-virtualization to mcps.json: - { - "mcpServers": { - "openshift-virtualization": { - "command": "podman", - "args": [ - "run", - "--rm", - "-i", - "--network=host", - "--userns=keep-id:uid=65532,gid=65532", - "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", - "--entrypoint", "/app/kubernetes-mcp-server", - "quay.io/ecosystem-appeng/openshift-mcp-server:latest", - "--kubeconfig", "/kubeconfig", - "--toolsets", "core,kubevirt" - ], - "env": { - "KUBECONFIG": "${KUBECONFIG}" - } - } - } - } - -2. Set KUBECONFIG environment variable: - export KUBECONFIG="/path/to/your/kubeconfig" - -3. Restart Claude Code to reload MCP servers - -🔗 Documentation: https://github.com/openshift/openshift-mcp-server - -❓ How would you like to proceed? -Options: -- "setup" - Help configure the MCP server now -- "skip" - Skip this skill -- "abort" - Stop workflow - -Please respond with your choice. -``` - -⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values. +⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. ## When to Use This Skill diff --git a/rh-virt/skills/vm-delete/SKILL.md b/rh-virt/skills/vm-delete/SKILL.md index 359007bc..146e020b 100644 --- a/rh-virt/skills/vm-delete/SKILL.md +++ b/rh-virt/skills/vm-delete/SKILL.md @@ -44,68 +44,13 @@ Permanently delete virtual machines and their associated resources (storage, Dat ### Prerequisite Verification **Before executing:** +1. Check `openshift-virtualization` exists in `mcps.json` → If missing, report setup +2. Verify `KUBECONFIG` is set (presence only, never expose value) → If missing, report +3. Check RBAC permissions (optional) → Verify delete permissions for VirtualMachine and PVC -1. **Check MCP Server Configuration** - - Verify `openshift-virtualization` exists in `mcps.json` - - If missing → Report to user with setup instructions +**Human Notification Protocol:** `❌ Cannot execute vm-delete: MCP server not available. Setup: Add to mcps.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` -2. **Check Environment Variables** - - Verify `KUBECONFIG` is set (presence only, never expose value) - - If missing → Report to user - -3. **Check RBAC Permissions** (optional verification) - - Verify ServiceAccount can delete VirtualMachine resources - - Verify ServiceAccount can delete PVC/DataVolume resources - -**Human Notification Protocol:** - -When prerequisites fail: - -``` -❌ Cannot execute vm-delete: MCP server 'openshift-virtualization' is not available - -📋 Setup Instructions: -1. Add openshift-virtualization to mcps.json: - { - "mcpServers": { - "openshift-virtualization": { - "command": "podman", - "args": [ - "run", - "--rm", - "-i", - "--network=host", - "--userns=keep-id:uid=65532,gid=65532", - "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", - "--entrypoint", "/app/kubernetes-mcp-server", - "quay.io/ecosystem-appeng/openshift-mcp-server:latest", - "--kubeconfig", "/kubeconfig", - "--toolsets", "core,kubevirt" - ], - "env": { - "KUBECONFIG": "${KUBECONFIG}" - } - } - } - } - -2. Set KUBECONFIG environment variable: - export KUBECONFIG="/path/to/your/kubeconfig" - -3. Restart Claude Code to reload MCP servers - -🔗 Documentation: https://github.com/openshift/openshift-mcp-server - -❓ How would you like to proceed? -Options: -- "setup" - Help configure the MCP server now -- "skip" - Skip this skill -- "abort" - Stop workflow - -Please respond with your choice. -``` - -⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values in output. +⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. ## When to Use This Skill diff --git a/rh-virt/skills/vm-inventory/SKILL.md b/rh-virt/skills/vm-inventory/SKILL.md index 54357156..3c21fffc 100644 --- a/rh-virt/skills/vm-inventory/SKILL.md +++ b/rh-virt/skills/vm-inventory/SKILL.md @@ -44,67 +44,13 @@ List and inspect virtual machines in OpenShift Virtualization clusters. This ski ### Prerequisite Verification **Before executing:** - -1. **Check MCP Server Configuration** - - Verify `openshift-virtualization` exists in `mcps.json` - - If missing → Report to user with setup instructions - -2. **Check Environment Variables** - - Verify `KUBECONFIG` is set (presence only, never expose value) - - If missing → Report to user - +1. Check `openshift-virtualization` exists in `mcps.json` → If missing, report setup +2. Verify `KUBECONFIG` is set (presence only, never expose value) → If missing, report 3. (Optional) Test basic connectivity to cluster → If fails, report connection error -**Human Notification Protocol:** - -When prerequisites fail: - -``` -❌ Cannot execute vm-inventory: MCP server 'openshift-virtualization' is not available - -📋 Setup Instructions: -1. Add openshift-virtualization to mcps.json: - { - "mcpServers": { - "openshift-virtualization": { - "command": "podman", - "args": [ - "run", - "--rm", - "-i", - "--network=host", - "--userns=keep-id:uid=65532,gid=65532", - "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", - "--entrypoint", "/app/kubernetes-mcp-server", - "quay.io/ecosystem-appeng/openshift-mcp-server:latest", - "--kubeconfig", "/kubeconfig", - "--toolsets", "core,kubevirt" - ], - "env": { - "KUBECONFIG": "${KUBECONFIG}" - } - } - } - } - -2. Set KUBECONFIG environment variable: - export KUBECONFIG="/path/to/your/kubeconfig" - -3. Restart Claude Code to reload MCP servers - -🔗 Documentation: https://github.com/openshift/openshift-mcp-server - -❓ How would you like to proceed? -Options: -- "setup" - Help configure the MCP server now -- "cli" - Use OpenShift CLI commands as fallback (requires KUBECONFIG) -- "skip" - Skip this skill -- "abort" - Stop workflow - -Please respond with your choice. -``` +**Human Notification Protocol:** `❌ Cannot execute vm-inventory: MCP server not available. Setup: Add to mcps.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` -⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values in output. +⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. **Note on Fallback Behavior**: - If MCP server is unavailable but KUBECONFIG is set, the skill CAN proceed with CLI commands diff --git a/rh-virt/skills/vm-lifecycle-manager/SKILL.md b/rh-virt/skills/vm-lifecycle-manager/SKILL.md index 20ca2bad..b2644754 100644 --- a/rh-virt/skills/vm-lifecycle-manager/SKILL.md +++ b/rh-virt/skills/vm-lifecycle-manager/SKILL.md @@ -39,68 +39,12 @@ Control virtual machine power state in OpenShift Virtualization using the `vm_li ### Prerequisite Verification **Before executing:** +1. Check `openshift-virtualization` exists in `mcps.json` → If missing, report setup +2. Verify `KUBECONFIG` is set (presence only, never expose value) → If missing, report -1. **Check MCP Server Configuration** - - Verify `openshift-virtualization` exists in `mcps.json` - - If missing → Report to user with setup instructions +**Human Notification Protocol:** `❌ Cannot execute vm-lifecycle-manager: MCP server not available. Setup: Add to mcps.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` -2. **Check Environment Variables** - - Verify `KUBECONFIG` is set (presence only, never expose value) - - If missing → Report to user - -3. **Verify VM Exists** (optional quick check) - - Confirm target VM exists in specified namespace - - If VM not found → Report error to user - -**Human Notification Protocol:** - -When prerequisites fail: - -``` -❌ Cannot execute vm-lifecycle-manager: MCP server 'openshift-virtualization' is not available - -📋 Setup Instructions: -1. Add openshift-virtualization to mcps.json: - { - "mcpServers": { - "openshift-virtualization": { - "command": "podman", - "args": [ - "run", - "--rm", - "-i", - "--network=host", - "--userns=keep-id:uid=65532,gid=65532", - "-v", "${KUBECONFIG}:/kubeconfig:ro,Z", - "--entrypoint", "/app/kubernetes-mcp-server", - "quay.io/ecosystem-appeng/openshift-mcp-server:latest", - "--kubeconfig", "/kubeconfig", - "--toolsets", "core,kubevirt" - ], - "env": { - "KUBECONFIG": "${KUBECONFIG}" - } - } - } - } - -2. Set KUBECONFIG environment variable: - export KUBECONFIG="/path/to/your/kubeconfig" - -3. Restart Claude Code to reload MCP servers - -🔗 Documentation: https://github.com/openshift/openshift-mcp-server - -❓ How would you like to proceed? -Options: -- "setup" - Help configure the MCP server now -- "skip" - Skip this skill -- "abort" - Stop workflow - -Please respond with your choice. -``` - -⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values in output. +⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. ## When to Use This Skill diff --git a/rh-virt/skills/vm-rebalance/SKILL.md b/rh-virt/skills/vm-rebalance/SKILL.md index 57275731..4be75554 100644 --- a/rh-virt/skills/vm-rebalance/SKILL.md +++ b/rh-virt/skills/vm-rebalance/SKILL.md @@ -47,32 +47,13 @@ Orchestrate VM migrations across OpenShift cluster nodes for load balancing, mai ### Prerequisite Verification **Before executing:** +1. Check `openshift-virtualization` exists in `mcps.json` → If missing, report setup +2. Verify `KUBECONFIG` is set (presence only, never expose value) → If missing, report +3. For live migration: Check PVC access mode is ReadWriteMany (RWX) via `resources_get` -1. **Check MCP Server** - Verify `openshift-virtualization` exists in `mcps.json` -2. **Check Environment** - Verify `KUBECONFIG` is set (check presence only, never expose value) -3. **Check Capability** (for live migration): - - Use `resources_get` to check PVC access mode is ReadWriteMany (RWX) - - Verify VM has running VirtualMachineInstance +**Human Notification Protocol:** `❌ Cannot execute vm-rebalance: MCP server not available. Setup: Add to mcps.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server` -**Human Notification Protocol:** - -When prerequisites fail: - -``` -❌ Cannot execute vm-rebalance: MCP server 'openshift-virtualization' is not available - -📋 Setup Instructions: -1. Add openshift-virtualization to mcps.json -2. Set KUBECONFIG environment variable -3. Ensure ServiceAccount has required permissions -4. Restart Claude Code to reload MCP servers - -🔗 Documentation: https://github.com/openshift/openshift-mcp-server - -Options: "setup" | "skip" | "abort" -``` - -⚠️ **SECURITY**: Never display actual KUBECONFIG path or credential values in output. +⚠️ **SECURITY**: Never display KUBECONFIG path or credential values. ## When to Use This Skill From 1971719bf17610b96579b81079a289e830ca27c3 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Fri, 10 Apr 2026 11:38:42 +0200 Subject: [PATCH 4/9] remove copilot instructions --- .github/copilot-instructions.md | 133 ------------------ .github/gemini-review-prompt.md | 2 +- .gitleaks.toml | 2 +- ocp-admin/README.md | 20 +-- ocp-admin/docs/credentials-management.md | 4 +- ocp-admin/docs/troubleshooting.md | 4 +- ocp-admin/skills/cluster-creator/SKILL.md | 2 +- ocp-admin/skills/cluster-inventory/SKILL.md | 2 +- ocp-admin/skills/cluster-report/SKILL.md | 6 +- rh-ai-engineer/{.mcp.json => mcps.json} | 0 .../skills/references/skill-conventions.md | 2 +- rh-automation/CLAUDE.md | 2 +- rh-automation/README.md | 2 +- rh-automation/{.mcp.json => mcps.json} | 0 .../skills/aap-mcp-validator/SKILL.md | 4 +- rh-developer/README.md | 2 +- rh-sre/CLAUDE.md | 2 +- scripts/validate_structure.py | 2 +- 18 files changed, 29 insertions(+), 162 deletions(-) delete mode 100644 .github/copilot-instructions.md rename rh-ai-engineer/{.mcp.json => mcps.json} (100%) rename rh-automation/{.mcp.json => mcps.json} (100%) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 5fd25cfa..00000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,133 +0,0 @@ -# Copilot Instructions for agentic-collections - -## Repository Overview - -This repository contains **agentic collections** — persona-specific plugin packs that automate interactions with Red Hat platforms. Each pack ships skills, agents, and MCP server configurations for AI marketplaces (Claude Code, Cursor, ChatGPT). - -## Repository Structure - -``` -agentic-collections/ -├── rh-sre/ # Site Reliability Engineering (reference implementation) -├── rh-developer/ # Developer tools -├── ocp-admin/ # OpenShift administration -├── rh-support-engineer/ # Technical support -├── rh-virt/ # Virtualization management -├── docs/ # Generated documentation site (do not edit data.json manually) -├── scripts/ # Python build/validate/generate scripts -└── Makefile # Main developer commands -``` - -### Inside each pack - -``` -/ -├── README.md -├── .claude-plugin/plugin.json # Optional: name, version, description, author, license -├── mcps.json # MCP server configs — credentials via env vars ONLY -├── agents/.md # Workflow orchestrators (YAML frontmatter required) -└── skills//SKILL.md # Task executors (YAML frontmatter required) -``` - -## Build, Validate, and Test - -All tooling uses [uv](https://github.com/astral-sh/uv). Install it once: - -```bash -curl -LsSf https://astral.sh/uv/install.sh | sh -``` - -| Command | Purpose | -|---|---| -| `make install` | Install Python deps | -| `make validate` | Validate pack/skill/agent structure (runs in CI) | -| `make generate` | Rebuild `docs/data.json` | -| `make test` | validate + generate + verify checks | -| `make serve` | Local site at http://localhost:8000 | - -**CI runs `make install && make validate` on every PR.** Always run `make validate` after editing skills, agents, or `mcps.json` files to catch errors before pushing. - -Packs known to the validator are listed in `scripts/validate_structure.py` (`PACK_DIRS`). Add new packs there when creating them. - -## Key File Formats - -### Skills — `skills//SKILL.md` - -Must start with valid YAML frontmatter. Root-level fields: `name`, `description`, `model`, `color`. Use `metadata` for custom fields (author, priority). See SKILL_DESIGN_PRINCIPLES.md for the 2026 Agentic Skills structure. - -```yaml ---- -name: skill-name -description: | - Concise when-to-use description with 3-5 examples. - Keep under 500 tokens. -model: inherit -color: blue -metadata: - author: "team-name" ---- -``` - -### Agents — `agents/.md` - -Same YAML frontmatter requirement (`name` + `description`). Agents orchestrate skills; they do not call MCP tools directly. - -### `mcps.json` - -```json -{ - "mcpServers": { - "server-name": { - "command": "podman", - "args": ["run", "--rm", "-i", "..."], - "env": { "SECRET": "${SECRET}" }, - "description": "...", - "security": { "isolation": "container", "network": "local", "credentials": "env-only" } - } - } -} -``` - -**NEVER hardcode credentials.** Always use `${ENV_VAR}` references. Gitleaks runs as a pre-commit hook and in CI. - -## Design Principles (from SKILL_DESIGN_PRINCIPLES.md) - -1. **Skills encapsulate tools** — never call MCP tools directly; always go through a skill. -2. **Agents orchestrate skills** — complex workflows delegate to specialized skills. -3. **Document consultation is an action** — actually read reference docs with the Read tool before claiming to have consulted them. -4. **Precise parameters** — specify exact tool parameters (names, formats, examples) so first-attempt tool calls succeed. -5. **Human-in-the-loop for critical ops** — require explicit confirmation before playbook execution or destructive actions. -6. **Never print credential values** — only report whether env vars are set/unset, never their contents. -7. **Dependencies section in every skill** — list required MCP servers, tools, related skills, and reference docs. - -## Adding a New Pack - -1. Create `/` directory with `README.md`. -2. Add `skills/` and optionally `agents/`, `mcps.json`, `.claude-plugin/plugin.json`. -3. Add the new pack name to `PACK_DIRS` in `scripts/validate_structure.py`. -4. Run `make validate && make generate` to regenerate docs locally for testing; do **not** commit `docs/data.json` (it is generated during deployment). - -## Adding a New Skill - -1. Create `skills//SKILL.md` with valid YAML frontmatter. -2. Follow the mandatory section order: Prerequisites → When to Use → Workflow → Dependencies → (Human-in-the-Loop if needed) → Example Usage. -3. Run `make validate` to confirm no errors. - -See `rh-virt/SKILL_TEMPLATE.md` for the canonical skill template and `rh-sre` as the full reference implementation. - -## Security - -- Gitleaks protects against accidental secret commits. -- Install pre-commit hook: `scripts/install-hooks.sh` -- Manual scan: `gitleaks detect --source . --verbose` -- See `SECURITY.md` and `.gitleaks.toml` for details. - -## Common Errors and Workarounds - -| Error | Cause | Fix | -|---|---|---| -| `Missing YAML frontmatter` | SKILL.md or agent .md missing `---` block | Add frontmatter with `name` and `description` | -| `Invalid JSON in mcps.json` | Syntax error or comments in JSON | JSON does not support comments; remove them | -| `Pack directory does not exist` | New pack not listed in validator | Add to `PACK_DIRS` in `scripts/validate_structure.py` | -| `uv: command not found` | uv not installed | `curl -LsSf https://astral.sh/uv/install.sh | sh` | -| Gitleaks blocks commit | Credential-like value in file | Use `${ENV_VAR}` references instead of literal values | diff --git a/.github/gemini-review-prompt.md b/.github/gemini-review-prompt.md index d2822af5..0d81f8cd 100644 --- a/.github/gemini-review-prompt.md +++ b/.github/gemini-review-prompt.md @@ -18,7 +18,7 @@ Check the diff against the project rules injected in PROJECT RULES REFERENCE (fr - **Skill invocation**: use `/skill-name` slash format, never call MCP tools directly - **Human-in-the-Loop**: required for create/delete/modify/restore/execute ops, not for read-only - **New packs**: must add pack name to `PACK_DIRS` in `scripts/validate_structure.py`; `docs/data.json` must NOT be committed -- **Build reminder**: if skills, agents, or `.mcp.json` changed, remind author to run `make validate` +- **Build reminder**: if skills, agents, or `mcps.json` changed, remind author to run `make validate` ### 3. Code Quality Issues Any bugs, security concerns, logic errors, or broken links (with file:line references). diff --git a/.gitleaks.toml b/.gitleaks.toml index 4099a911..4647c00e 100644 --- a/.gitleaks.toml +++ b/.gitleaks.toml @@ -13,7 +13,7 @@ useDefault = true id = "mcp-hardcoded-credentials" description = "Hardcoded credentials in mcps.json files (must use ${ENV_VAR} pattern)" regex = '''["'](?:LIGHTSPEED_CLIENT_ID|LIGHTSPEED_CLIENT_SECRET|API_KEY|SECRET|TOKEN|PASSWORD)["']\s*:\s*["'][^"']{8,}["']''' -path = '''\.mcp\.json$''' +path = '''\.(mcp|mcps)\.json$''' tags = ["mcp", "credentials"] [[rules]] diff --git a/ocp-admin/README.md b/ocp-admin/README.md index 4fef67ac..6fc99e79 100644 --- a/ocp-admin/README.md +++ b/ocp-admin/README.md @@ -59,7 +59,7 @@ claude plugin list ### Important: MCP Server Configuration -**⚠️ CRITICAL**: The `.mcp.json` file in this plugin is for **reference only**. MCP servers are **NOT automatically installed** by Claude Code plugins. +**⚠️ CRITICAL**: The `mcps.json` file in this plugin is for **reference only**. MCP servers are **NOT automatically installed** by Claude Code plugins. **You must manually configure MCP servers** in your Claude Code settings using **one of these methods**: @@ -68,7 +68,7 @@ claude plugin list 1. Open Claude Code 2. Type `/mcp` to open MCP Server Manager 3. Click "Add Server" for each server below -4. Copy the configuration from `.mcp.json` +4. Copy the configuration from `mcps.json` #### Option B: Manual Settings Configuration @@ -81,10 +81,10 @@ Add the MCP servers to your settings file: { "mcpServers": { "openshift-self-managed": { - // ... copy from .mcp.json + // ... copy from mcps.json }, "openshift-ocm-managed": { - // ... copy from .mcp.json + // ... copy from mcps.json } } } @@ -131,9 +131,9 @@ source ~/.bashrc ### 3. Configure MCP Servers in Claude Code -Copy the **entire configuration** from `ocp-admin/.mcp.json` to your Claude Code settings: +Copy the **entire configuration** from `ocp-admin/mcps.json` to your Claude Code settings: -**From**: `ocp-admin/.mcp.json` (reference) +**From**: `ocp-admin/mcps.json` (reference) **To**: `~/.claude/settings.json` (active configuration) **Full Configuration** (copy this to your settings): @@ -398,7 +398,7 @@ Provides access to Red Hat Assisted Installer API for cluster lifecycle operatio - **Versions**: list_versions, list_operator_bundles - **Operators**: add_operator_bundle_to_cluster -**Configuration** (in `.mcp.json`): +**Configuration** (in `mcps.json`): ```json { "mcpServers": { @@ -447,7 +447,7 @@ Provides access to Kubernetes/OpenShift cluster operations for multi-cluster man - **Namespaces**: namespaces_list, projects_list - **Events**: events_list -**Configuration** (in `.mcp.json`): +**Configuration** (in `mcps.json`): ```json { "mcpServers": { @@ -587,7 +587,7 @@ The pack includes 17 comprehensive reference documents covering all aspects of O **Solutions**: 1. Verify `uv` is installed: `uv --version` 2. Check OFFLINE_TOKEN is set: `echo "OFFLINE_TOKEN is ${OFFLINE_TOKEN:+set}"` -3. Verify path in `.mcp.json` points to your local `assisted-service-mcp` clone +3. Verify path in `mcps.json` points to your local `assisted-service-mcp` clone 4. Test manually: ```bash cd /path/to/assisted-service-mcp @@ -644,7 +644,7 @@ ocp-admin/ ├── README.md # This file ├── .claude-plugin/ │ └── plugin.json # Plugin metadata -├── .mcp.json # MCP server configurations +├── mcps.json # MCP server configurations ├── docs/ # Comprehensive reference documentation (17 files) │ ├── INDEX.md # Master documentation navigation │ ├── input-validation-guide.md diff --git a/ocp-admin/docs/credentials-management.md b/ocp-admin/docs/credentials-management.md index f5c2f0eb..8a043692 100644 --- a/ocp-admin/docs/credentials-management.md +++ b/ocp-admin/docs/credentials-management.md @@ -211,7 +211,7 @@ export KUBECONFIG=~/.kube/cluster-name.config Uses `KUBECONFIG` environment variable for authentication. -**.mcp.json configuration**: +**mcps.json configuration**: ```json { "mcpServers": { @@ -423,7 +423,7 @@ kubectl config current-context # Verify context **Solutions**: - Export `KUBECONFIG` before starting Claude Code -- Verify `.mcp.json` includes `"KUBECONFIG": "${KUBECONFIG}"` +- Verify `mcps.json` includes `"KUBECONFIG": "${KUBECONFIG}"` - Restart Claude Code ### Context Not Switching diff --git a/ocp-admin/docs/troubleshooting.md b/ocp-admin/docs/troubleshooting.md index 83d98482..500bf1ea 100644 --- a/ocp-admin/docs/troubleshooting.md +++ b/ocp-admin/docs/troubleshooting.md @@ -118,7 +118,7 @@ If OFFLINE_TOKEN is missing or invalid: **Security Best Practices**: - ✓ Set OFFLINE_TOKEN in shell profile (`.bashrc`, `.zshrc`) for persistence -- ✓ Use environment variable reference `${OFFLINE_TOKEN}` in `.mcp.json` +- ✓ Use environment variable reference `${OFFLINE_TOKEN}` in `mcps.json` - ✓ Never commit `.env` files containing tokens to version control - ✗ NEVER echo or print the token value in commands - ✗ NEVER include token in code, scripts, or documentation examples @@ -160,7 +160,7 @@ If OFFLINE_TOKEN is missing or invalid: ``` 2. **Verify environment variable is passed to container**: - - Ensure `.mcp.json` has `"env": {"OFFLINE_TOKEN": "${OFFLINE_TOKEN}"}` + - Ensure `mcps.json` has `"env": {"OFFLINE_TOKEN": "${OFFLINE_TOKEN}"}` - Ensure shell session has `OFFLINE_TOKEN` exported before starting Claude Code 3. **Test manual container execution**: diff --git a/ocp-admin/skills/cluster-creator/SKILL.md b/ocp-admin/skills/cluster-creator/SKILL.md index 012512ba..bbb768da 100644 --- a/ocp-admin/skills/cluster-creator/SKILL.md +++ b/ocp-admin/skills/cluster-creator/SKILL.md @@ -67,7 +67,7 @@ This skill uses `openshift-self-managed` MCP server exclusively. This server con - **OSD** (OpenShift Dedicated) - Use `openshift-ocm-managed` MCP server **Verification**: -1. Check `openshift-self-managed` in `.mcp.json` +1. Check `openshift-self-managed` in `mcps.json` 2. Verify `OFFLINE_TOKEN` set: `test -n "$OFFLINE_TOKEN"` 3. Test connection: Call `list_versions` to verify MCP server responsive diff --git a/ocp-admin/skills/cluster-inventory/SKILL.md b/ocp-admin/skills/cluster-inventory/SKILL.md index 34e03a59..53fc6f58 100644 --- a/ocp-admin/skills/cluster-inventory/SKILL.md +++ b/ocp-admin/skills/cluster-inventory/SKILL.md @@ -56,7 +56,7 @@ List and inspect OpenShift clusters across all types (OCP, SNO, ROSA, ARO, OSD). **Environment Variables**: `OFFLINE_TOKEN` - Red Hat authentication token **Verification Steps**: -1. Verify both MCP servers exist in `.mcp.json` +1. Verify both MCP servers exist in `mcps.json` 2. Check `OFFLINE_TOKEN` is set: `test -n "$OFFLINE_TOKEN" && echo "✓" || echo "✗"` 3. If missing → Stop and report error with setup instructions diff --git a/ocp-admin/skills/cluster-report/SKILL.md b/ocp-admin/skills/cluster-report/SKILL.md index 4fdce7d3..704953bc 100644 --- a/ocp-admin/skills/cluster-report/SKILL.md +++ b/ocp-admin/skills/cluster-report/SKILL.md @@ -70,7 +70,7 @@ This skill uses `openshift-administration` MCP server exclusively. This server p - **NEVER** manually reconstruct data already available in MCP output **Verification**: -1. Check `openshift-administration` in `.mcp.json` +1. Check `openshift-administration` in `mcps.json` 2. Verify `KUBECONFIG` set: `test -n "$KUBECONFIG"` 3. Test connection: Call `configuration_contexts_list` to verify MCP server responsive @@ -97,7 +97,7 @@ This skill uses `openshift-administration` MCP server exclusively. This server p **If MCP server unavailable**: 1. Stop immediately 2. Display: "Cannot execute skill: openshift-administration MCP server not configured" -3. Display: "Setup: Configure openshift-administration in .mcp.json (see README.md#environment-setup)" +3. Display: "Setup: Configure openshift-administration in mcps.json (see README.md#environment-setup)" 4. Ask: "How to proceed? (setup/skip/abort)" 5. Wait for user input @@ -122,7 +122,7 @@ Collect all context names and server URLs. Do NOT present results to the user ye **Error Handling**: - If no contexts found: Stop and instruct user to verify KUBECONFIG points to a valid file with cluster contexts -- If tool call fails: Report MCP server connectivity issue, suggest checking `.mcp.json` configuration +- If tool call fails: Report MCP server connectivity issue, suggest checking `mcps.json` configuration #### Step 1b: Verify OpenShift Clusters diff --git a/rh-ai-engineer/.mcp.json b/rh-ai-engineer/mcps.json similarity index 100% rename from rh-ai-engineer/.mcp.json rename to rh-ai-engineer/mcps.json diff --git a/rh-ai-engineer/skills/references/skill-conventions.md b/rh-ai-engineer/skills/references/skill-conventions.md index 74676198..d822fa74 100644 --- a/rh-ai-engineer/skills/references/skill-conventions.md +++ b/rh-ai-engineer/skills/references/skill-conventions.md @@ -89,7 +89,7 @@ Before executing any skill, verify MCP server availability: **OpenShift MCP Server** (universally required): - Source: https://github.com/openshift/openshift-mcp-server - Required env var: `KUBECONFIG` -- Setup: Add to `.mcp.json`, set `KUBECONFIG`, restart Claude Code +- Setup: Add to `mcps.json`, set `KUBECONFIG`, restart Claude Code ## Common Prerequisites diff --git a/rh-automation/CLAUDE.md b/rh-automation/CLAUDE.md index a627d599..2e93308d 100644 --- a/rh-automation/CLAUDE.md +++ b/rh-automation/CLAUDE.md @@ -55,7 +55,7 @@ Six HTTP MCP servers are configured for this pack. Skills wrap these — do not - **aap-mcp-system-monitoring** (Required for full governance readiness) — Instance groups, activity stream, mesh topology, platform status. - **aap-mcp-user-management** (Required for full governance readiness) — Users, teams, organizations, roles, RBAC. -Environment variables `AAP_MCP_SERVER` and `AAP_API_TOKEN` are defined in `.mcp.json` using `${...}` placeholders only; never expose secret values in chat output. +Environment variables `AAP_MCP_SERVER` and `AAP_API_TOKEN` are defined in `mcps.json` using `${...}` placeholders only; never expose secret values in chat output. ## Global Rules diff --git a/rh-automation/README.md b/rh-automation/README.md index 68e58508..f41f2a4d 100644 --- a/rh-automation/README.md +++ b/rh-automation/README.md @@ -100,7 +100,7 @@ See [docs/INDEX.md](docs/INDEX.md) for the complete documentation map and [docs/ ``` rh-automation/ -├── .mcp.json # 6 AAP MCP servers +├── mcps.json # 6 AAP MCP servers ├── skills/ │ ├── governance-assessor/ # UC1: Orchestrates governance audit │ ├── governance-executor/ # UC2: Orchestrates governed execution diff --git a/rh-automation/.mcp.json b/rh-automation/mcps.json similarity index 100% rename from rh-automation/.mcp.json rename to rh-automation/mcps.json diff --git a/rh-automation/skills/aap-mcp-validator/SKILL.md b/rh-automation/skills/aap-mcp-validator/SKILL.md index bf853a2a..a8bd060a 100644 --- a/rh-automation/skills/aap-mcp-validator/SKILL.md +++ b/rh-automation/skills/aap-mcp-validator/SKILL.md @@ -114,7 +114,7 @@ If any server fails: ## Dependencies ### Required MCP Servers -- All 6 AAP MCP servers (as configured in `.mcp.json`) +- All 6 AAP MCP servers (as configured in `mcps.json`) ### Required MCP Tools - `job_templates_list` (from aap-mcp-job-management) @@ -128,7 +128,7 @@ If any server fails: - All skills requiring AAP MCP access (this skill validates connectivity before they run) ### Reference Documentation -- AAP MCP server configuration in `.mcp.json` +- AAP MCP server configuration in `mcps.json` ## Example Usage diff --git a/rh-developer/README.md b/rh-developer/README.md index f7711f1f..6fa6622d 100644 --- a/rh-developer/README.md +++ b/rh-developer/README.md @@ -45,7 +45,7 @@ A Claude Code plugin for building and deploying applications on Red Hat platform - **github** - Repository browsing and code analysis - **lightspeed** - Red Hat Insights data (vulnerability, advisor, inventory, planning) — optional -> **Container UID mapping**: The openshift MCP server uses `--userns=keep-id:uid=65532,gid=65532` to map the host user to the container's non-root UID (65532). This allows the container to read `chmod 600` files like `KUBECONFIG` without weakening file permissions. **macOS users**: Podman runs inside a VM on macOS — this flag may cause startup failures. If the MCP server fails to start, remove the `--userns` line from `.mcp.json`. +> **Container UID mapping**: The openshift MCP server uses `--userns=keep-id:uid=65532,gid=65532` to map the host user to the container's non-root UID (65532). This allows the container to read `chmod 600` files like `KUBECONFIG` without weakening file permissions. **macOS users**: Podman runs inside a VM on macOS — this flag may cause startup failures. If the MCP server fails to start, remove the `--userns` line from `mcps.json`. ## Supported Languages diff --git a/rh-sre/CLAUDE.md b/rh-sre/CLAUDE.md index 0f3dd266..432f74d5 100644 --- a/rh-sre/CLAUDE.md +++ b/rh-sre/CLAUDE.md @@ -52,7 +52,7 @@ Three MCP server families are configured for this pack. Skills wrap these — do - **aap-mcp-job-management** (Required for execution paths) — AAP job templates, projects, job runs. - **aap-mcp-inventory-management** (Required for execution paths) — AAP inventories and hosts. -Environment variables are defined in `.mcp.json` using `${...}` placeholders only; never expose secret values in chat output. +Environment variables are defined in `mcps.json` using `${...}` placeholders only; never expose secret values in chat output. ## Global Rules diff --git a/scripts/validate_structure.py b/scripts/validate_structure.py index 7b81a685..ebc34930 100644 --- a/scripts/validate_structure.py +++ b/scripts/validate_structure.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """ -Validate agentic collection pack structure (plugin.json, .mcp.json, CLAUDE.md). +Validate agentic collection pack structure (plugin.json, mcps.json, CLAUDE.md). Skill-level validation (frontmatter, sections, security) is handled by validate-skills.sh and run-skill-linter.sh. From a3483a0f04ee8a39b256d15b9615067079ea2e0a Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Fri, 10 Apr 2026 12:15:49 +0200 Subject: [PATCH 5/9] update repository URLs in rh-agentic-collection.yml to point to the forked version Signed-off-by: Daniele Martinoli --- marketplace/rh-agentic-collection.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/marketplace/rh-agentic-collection.yml b/marketplace/rh-agentic-collection.yml index 140ef1b8..e70dd6ca 100644 --- a/marketplace/rh-agentic-collection.yml +++ b/marketplace/rh-agentic-collection.yml @@ -1,13 +1,13 @@ name: "RH Agentic Collections Marketplace" description: "Official curated collection of RH Agentic Collections modules" -url: "https://github.com/RHEcosystemAppEng/agentic-collections" +url: "https://github.com/dmartinol/agentic-collections-fork" version: "0.0.1" modules: - name: "ocp-admin" description: "Automation capabilities for OpenShift Container Platform cluster management, workload orchestration, security policies, and operational tasks." version: "0.0.1" - repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + repository: "https://github.com/dmartinol/agentic-collections-fork" path: "ocp-admin" tags: - "red-hat" @@ -18,7 +18,7 @@ modules: - name: "rh-developer" description: "Plugins for building and deploying applications on Red Hat platforms." version: "0.0.1" - repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + repository: "https://github.com/dmartinol/agentic-collections-fork" path: "rh-developer" tags: - "developer" @@ -33,7 +33,7 @@ modules: - name: "rh-sre" description: "Site reliability engineering tools and automation for managing Red Hat platforms and infrastructure." version: "0.0.1" - repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + repository: "https://github.com/dmartinol/agentic-collections-fork" path: "rh-sre" tags: - "sre" @@ -45,7 +45,7 @@ modules: - name: "rh-support-engineer" description: "Technical support and troubleshooting tools for Red Hat products and platforms." version: "0.0.1" - repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + repository: "https://github.com/dmartinol/agentic-collections-fork" path: "rh-support-engineer" tags: - "red-hat" @@ -56,7 +56,7 @@ modules: - name: "rh-virt" description: "Virtual machine management and automation for OpenShift Virtualization and KubeVirt workloads." version: "0.0.1" - repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + repository: "https://github.com/dmartinol/agentic-collections-fork" path: "rh-virt" tags: - "red-hat" From cd17b322ac05cb373ade78c7510bad156238ed96 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Fri, 10 Apr 2026 20:25:23 +0200 Subject: [PATCH 6/9] update README, marketplace, and scripts to include new rh-ai-engineer and rh-automation modules; adjust repository URLs and improve pack data generation Signed-off-by: Daniele Martinoli --- README.md | 2 +- docs/plugins.json | 3 ++ marketplace/rh-agentic-collection.yml | 53 ++++++++++++++++++--------- scripts/generate_mcp_data.py | 5 +-- scripts/generate_pack_data.py | 6 ++- 5 files changed, 47 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index f47ac1a4..e8d4ad27 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ lola install -f rh-sre ### Install all modules at once ```bash -for m in ocp-admin rh-developer rh-sre rh-support-engineer rh-virt; do lola install -f $m; done +for m in ocp-admin rh-ai-engineer rh-automation rh-developer rh-sre rh-virt; do lola install -f $m; done ``` ### Install to a specific assistant only diff --git a/docs/plugins.json b/docs/plugins.json index cefba8b0..43974e2b 100644 --- a/docs/plugins.json +++ b/docs/plugins.json @@ -11,6 +11,9 @@ "ocp-admin": { "title": "Red Hat OpenShift Administration Agentic Skills Collection" }, + "rh-ai-engineer": { + "title": "Red Hat OpenShift AI Engineering Agentic Collection" + }, "rh-support-engineer": { "title": "Red Hat Support Engineer Agentic Skills Collection" }, diff --git a/marketplace/rh-agentic-collection.yml b/marketplace/rh-agentic-collection.yml index e70dd6ca..cff9dde8 100644 --- a/marketplace/rh-agentic-collection.yml +++ b/marketplace/rh-agentic-collection.yml @@ -1,13 +1,13 @@ -name: "RH Agentic Collections Marketplace" -description: "Official curated collection of RH Agentic Collections modules" -url: "https://github.com/dmartinol/agentic-collections-fork" +name: "redhat-agentic-collections" +description: "Validated Agentic Collections from Red Hat Ecosystem Engineering" +url: "https://github.com/RHEcosystemAppEng/agentic-collections" version: "0.0.1" modules: - name: "ocp-admin" description: "Automation capabilities for OpenShift Container Platform cluster management, workload orchestration, security policies, and operational tasks." version: "0.0.1" - repository: "https://github.com/dmartinol/agentic-collections-fork" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "ocp-admin" tags: - "red-hat" @@ -18,7 +18,7 @@ modules: - name: "rh-developer" description: "Plugins for building and deploying applications on Red Hat platforms." version: "0.0.1" - repository: "https://github.com/dmartinol/agentic-collections-fork" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "rh-developer" tags: - "developer" @@ -33,7 +33,7 @@ modules: - name: "rh-sre" description: "Site reliability engineering tools and automation for managing Red Hat platforms and infrastructure." version: "0.0.1" - repository: "https://github.com/dmartinol/agentic-collections-fork" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "rh-sre" tags: - "sre" @@ -41,26 +41,45 @@ modules: - "platforms" - "products" - "automation" - - - name: "rh-support-engineer" - description: "Technical support and troubleshooting tools for Red Hat products and platforms." + + - name: "rh-ai-engineer" + description: "Red Hat OpenShift AI Engineering Agentic Collection" version: "0.0.1" - repository: "https://github.com/dmartinol/agentic-collections-fork" - path: "rh-support-engineer" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + path: "rh-ai-engineer" tags: - - "red-hat" - - "support" - - "troubleshooting" - - "engineering" + - "ai-engineer" + - "openshift-ai" + - "rhoai" + - "kserve" + - "vllm" + - "nvidia-nim" + - "model-serving" + - "inference" + - "gpu" - name: "rh-virt" description: "Virtual machine management and automation for OpenShift Virtualization and KubeVirt workloads." version: "0.0.1" - repository: "https://github.com/dmartinol/agentic-collections-fork" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "rh-virt" tags: - "red-hat" - "kubevirt" - "openshift" - "virtualization" - - "virt" \ No newline at end of file + - "virt" + + - name: "rh-automation" + description: "Ansible Automation Platform governance, execution safety, and forensic troubleshooting tools for Red Hat automation engineers." + version: "0.0.1" + repository: "https://github.com/RHEcosystemAppEng/agentic-collections" + path: "rh-automation" + tags: + - "ansible" + - "aap" + - "automation" + - "red-hat" + - "governance" + - "troubleshooting" + - "execution" diff --git a/scripts/generate_mcp_data.py b/scripts/generate_mcp_data.py index 1374f864..45c67e6e 100644 --- a/scripts/generate_mcp_data.py +++ b/scripts/generate_mcp_data.py @@ -9,8 +9,7 @@ from pathlib import Path from typing import Dict, List, Any -# List of agentic packs to parse -PACK_DIRS = ['rh-sre', 'rh-developer', 'ocp-admin', 'rh-support-engineer', 'rh-virt', 'rh-ai-engineer', 'rh-automation'] +from generate_pack_data import DOCS_PACK_DIRS MCP_FILENAME = "mcps.json" MCP_DEPRECATED = ".mcp.json" @@ -174,7 +173,7 @@ def generate_mcp_data() -> List[Dict[str, Any]]: # Load custom data (repository URLs and tool descriptions) custom_data = load_custom_mcp_data() - for pack_dir in PACK_DIRS: + for pack_dir in DOCS_PACK_DIRS: pack_path = Path(pack_dir) if not pack_path.exists(): diff --git a/scripts/generate_pack_data.py b/scripts/generate_pack_data.py index 4c351be7..5fdf4312 100644 --- a/scripts/generate_pack_data.py +++ b/scripts/generate_pack_data.py @@ -13,6 +13,10 @@ # List of agentic packs to parse PACK_DIRS = ['rh-sre', 'rh-developer', 'ocp-admin', 'rh-support-engineer', 'rh-virt', 'rh-ai-engineer', 'rh-automation'] +# Packs omitted from docs/data.json and the static documentation site +DOCS_EXCLUDED_PACKS = frozenset({'rh-support-engineer'}) +DOCS_PACK_DIRS = [d for d in PACK_DIRS if d not in DOCS_EXCLUDED_PACKS] + def parse_yaml_frontmatter(file_path: Path) -> Dict[str, Any]: """ @@ -280,7 +284,7 @@ def generate_pack_data() -> List[Dict[str, Any]]: # Load plugin title mappings from docs/plugins.json plugin_titles = load_plugin_titles() - for pack_dir in PACK_DIRS: + for pack_dir in DOCS_PACK_DIRS: pack_path = Path(pack_dir) if not pack_path.exists(): From 86d1acf3d2849d02ee54b0a77a0b560a577b2d23 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 13 Apr 2026 11:12:43 +0200 Subject: [PATCH 7/9] refactor documentation and scripts to clarify optional plugin.json usage; update validation and README instructions for pack structure and MCP configurations Signed-off-by: Daniele Martinoli --- CLAUDE.md | 25 ++++++++--------- Makefile | 2 +- README.md | 51 +++++++++++++++-------------------- SKILL_DESIGN_PRINCIPLES.md | 8 +++++- docs/README.md | 2 +- ocp-admin/README.md | 4 +-- rh-sre/README.md | 4 +-- rh-virt/README.md | 4 +-- scripts/generate_pack_data.py | 2 +- scripts/validate_structure.py | 6 ++--- 10 files changed, 53 insertions(+), 55 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6b7c03ac..f0ff01a3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,18 +26,18 @@ Each pack follows this structure: / ├── CLAUDE.md # Claude Code instruction routing (persona, skills, rules) ├── README.md # Pack description, persona, target marketplaces -├── .claude-plugin/ # Claude Code plugin metadata -│ └── plugin.json # Name, version, description, author, license -├── mcps.json # MCP server configurations (uses env vars for credentials) -├── skills/ # Specialized task executors (including orchestration skills) +├── mcps.json # MCP server configurations (uses env vars for credentials) +├── skills/ # Specialized task executors (including orchestration skills) │ └── / -│ └── SKILL.md # Skill definition with YAML frontmatter -└── docs/ # AI-optimized knowledge base (rh-sre only currently) - ├── INDEX.md # Documentation map and AI discovery guide - ├── SOURCES.md # Official Red Hat source attributions - └── .ai-index/ # Semantic indexing for token optimization +│ └── SKILL.md # Skill definition with YAML frontmatter +└── docs/ # AI-optimized knowledge base (rh-sre only currently) + ├── INDEX.md # Documentation map and AI discovery guide + ├── SOURCES.md # Official Red Hat source attributions + └── .ai-index/ # Semantic indexing for token optimization ``` +Optional (not required for Lola): `.claude-plugin/plugin.json` — Claude Code plugin metadata if you publish this pack through the Claude Code plugin format in addition to Lola. + ## Working with Agentic Collections ### Skills @@ -155,9 +155,10 @@ last_updated: YYYY-MM-DD 2. Add `README.md` with description, persona, marketplaces 3. Add `CLAUDE.md` with persona, skill-first rule, intent routing table, MCP servers, and global rules (see [rh-ai-engineer/CLAUDE.md](rh-ai-engineer/CLAUDE.md) for reference) 4. Create `skills/` directory -5. Optional: Add `.claude-plugin/plugin.json` for Claude Code -6. Optional: Add `mcps.json` for MCP server integrations -7. Update main `README.md` table with link +5. Add `mcps.json` when the pack integrates MCP servers (use `${VAR}` for secrets) +6. Register the pack in [`marketplace/rh-agentic-collection.yml`](marketplace/rh-agentic-collection.yml) so `lola install -f ` can resolve it +7. Optional: Add `.claude-plugin/plugin.json` only if publishing via Claude Code’s plugin mechanism +8. Update main `README.md` table with link ### Adding a Skill diff --git a/Makefile b/Makefile index ada5a582..5c5092ec 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ help: @echo "" @echo "Available targets:" @echo " install - Install Python dependencies (requires uv)" - @echo " validate - Validate pack structure (plugin.json, mcps.json, frontmatter)" + @echo " validate - Validate pack structure (mcps.json, CLAUDE.md, frontmatter; plugin.json if present)" @echo " validate-skill-design - Validate all skills (use PACK=rh-sre for a specific pack)" @echo " validate-skill-design-changed - Validate only changed skills (staged + unstaged, for local dev)" @echo " generate - Generate docs/data.json" diff --git a/README.md b/README.md index e8d4ad27..15fdc1ef 100644 --- a/README.md +++ b/README.md @@ -184,7 +184,7 @@ Generate and view documentation locally: # Install dependencies (first time only) make install -# Validate pack structure (plugin.json, mcps.json, frontmatter) +# Validate pack structure (mcps.json, CLAUDE.md, frontmatter; plugin.json if present) make validate # Validate skills against Design Principles (SKILL_DESIGN_PRINCIPLES.md) @@ -468,22 +468,24 @@ cd /path/to/agentic-collections /plugin install rh-sre@redhat-agentic-collections ``` -### Validate Marketplace +### Validate packs (recommended) ```bash -# Validate marketplace.json and all plugins -claude plugin validate . +# Structure, mcps.json, CLAUDE.md, skill frontmatter; validates plugin.json only when present +make validate +``` + +### Optional: Claude Code plugin CLI + +If you use the Claude Code `/plugin` marketplace workflow against a local checkout: +```bash +claude plugin validate . # Or from within Claude Code /plugin validate . ``` -This will check: -- ✅ Marketplace.json schema compliance -- ✅ All plugin.json files syntax -- ✅ YAML frontmatter in skills -- ✅ Duplicate names -- ✅ Invalid paths +That CLI checks marketplace/plugin manifests for that workflow, including `plugin.json` when present under `.claude-plugin/`. --- @@ -504,26 +506,15 @@ We welcome contributions! Here's how to add or improve skills: ``` 5. Update the pack's `CLAUDE.md` intent routing table -### Adding a New Plugin - -1. Create plugin directory: `/` -2. Add `.claude-plugin/plugin.json` with metadata -3. Add `skills/` directory -4. Add `CLAUDE.md` with persona and skill routing (see [rh-ai-engineer/CLAUDE.md](rh-ai-engineer/CLAUDE.md)) -5. Add `README.md` with plugin description -6. Update marketplace.json: - ```json - { - "name": "your-plugin", - "description": "Plugin description", - "version": "1.0.0", - "author": {...}, - "source": "./your-plugin", - "category": "your-category", - "skills": "./skills" - } - ``` -7. Validate: `make validate && claude plugin validate .` +### Adding a New Plugin (pack) + +1. Create pack directory: `/` +2. Add `README.md`, `CLAUDE.md`, and `skills/` (see [CLAUDE.md](CLAUDE.md)) +3. Add `mcps.json` when the pack uses MCP servers +4. Register the module in [`marketplace/rh-agentic-collection.yml`](marketplace/rh-agentic-collection.yml) (add a `modules:` entry with `name`, `path`, `repository`, `version`, etc.) +5. Optional: Add `.claude-plugin/plugin.json` only if you also publish through Claude Code’s plugin format (not required for Lola) +6. Validate: `make validate` +7. Optional: `claude plugin validate .` if you use the Claude Code plugin CLI locally ### Pull Request Guidelines diff --git a/SKILL_DESIGN_PRINCIPLES.md b/SKILL_DESIGN_PRINCIPLES.md index fe81e1ea..7c5888df 100644 --- a/SKILL_DESIGN_PRINCIPLES.md +++ b/SKILL_DESIGN_PRINCIPLES.md @@ -2,7 +2,13 @@ Repository-specific design principles for creating skills and agents in agentic collections. Referenced from [CLAUDE.md](CLAUDE.md). -**Scope**: Tier 2 requirements - repository enhancements beyond base agentskills.io specification (Tier 1 validated by linter). Packs follow the Lola module format; see [CLAUDE.md](CLAUDE.md) for layout. +**Scope**: Tier 2 requirements - repository enhancements beyond base agentskills.io specification (Tier 1 validated by linter). + +**Distribution (Lola):** Packs are installed with the [Lola](https://github.com/RedHatProductSecurity/lola) package manager from the registry in [`marketplace/rh-agentic-collection.yml`](marketplace/rh-agentic-collection.yml). Layout and install flow are documented in [CLAUDE.md](CLAUDE.md) and the root [README.md](README.md). + +**MCP configuration:** Use `/mcps.json` for MCP server definitions (never hardcode secrets; use `${VAR}` references). The deprecated filename `.mcp.json` is not used in this repository. + +**Optional Claude Code manifest:** `.claude-plugin/plugin.json` is optional—only needed for Claude Code–specific plugin publishing. It is not required for Lola installation or for Tier 2 skill content compliance. --- diff --git a/docs/README.md b/docs/README.md index 6a0aa97d..aff6265b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,7 +31,7 @@ This script parses all agentic collections and MCP configurations. ## Manual Updates To manually update the site: -1. Modify pack configurations (plugin.json, mcps.json, skills, agents) +1. Modify pack configurations (`mcps.json`, skills, agents; optional `.claude-plugin/plugin.json`) 2. Run `make generate` from the root directory 3. Commit the updated `docs/data.json` 4. Push to trigger GitHub Pages deployment diff --git a/ocp-admin/README.md b/ocp-admin/README.md index 6fc99e79..80e885b7 100644 --- a/ocp-admin/README.md +++ b/ocp-admin/README.md @@ -642,8 +642,6 @@ The pack includes 17 comprehensive reference documents covering all aspects of O ``` ocp-admin/ ├── README.md # This file -├── .claude-plugin/ -│ └── plugin.json # Plugin metadata ├── mcps.json # MCP server configurations ├── docs/ # Comprehensive reference documentation (17 files) │ ├── INDEX.md # Master documentation navigation @@ -675,6 +673,8 @@ ocp-admin/ └── aggregate.py # Metrics aggregation ``` +*Optional:* `.claude-plugin/plugin.json` — only if publishing via Claude Code’s plugin format; not required for [Lola](https://github.com/RedHatProductSecurity/lola) install. + ### Key Patterns - **Skills encapsulate operations** - Each skill handles one category of cluster tasks diff --git a/rh-sre/README.md b/rh-sre/README.md index 35ec8a31..3a445485 100644 --- a/rh-sre/README.md +++ b/rh-sre/README.md @@ -600,8 +600,6 @@ This pack demonstrates the complete agentic pack architecture: ``` rh-sre/ ├── README.md # This file -├── .claude-plugin/ -│ └── plugin.json # Plugin metadata ├── mcps.json # MCP server configurations ├── skills/ │ ├── remediation/SKILL.md # Orchestration skill (end-to-end CVE remediation) @@ -623,6 +621,8 @@ rh-sre/ └── .ai-index/ # Semantic indexing ``` +*Optional:* `.claude-plugin/plugin.json` — only if publishing via Claude Code’s plugin format; not required for [Lola](https://github.com/RedHatProductSecurity/lola) install. + ### Key Patterns - **Skills encapsulate tools** - Never call MCP tools directly - **Orchestration skills invoke other skills** - Complex workflows delegate to specialized skills diff --git a/rh-virt/README.md b/rh-virt/README.md index 3d739d6a..6c6ab0bc 100644 --- a/rh-virt/README.md +++ b/rh-virt/README.md @@ -511,8 +511,6 @@ The **vm-create** skill includes automatic error diagnosis and workaround propos ``` rh-virt/ ├── README.md # This file -├── .claude-plugin/ -│ └── plugin.json # Plugin metadata ├── mcps.json # MCP server configuration ├── docs/ # AI-optimized knowledge base │ └── troubleshooting/ # VM error diagnosis and workarounds (categorized by error type) @@ -532,6 +530,8 @@ rh-virt/ └── vm-clone/SKILL.md # VM cloning and duplication ``` +*Optional:* `.claude-plugin/plugin.json` — only if publishing via Claude Code’s plugin format; not required for [Lola](https://github.com/RedHatProductSecurity/lola) install. + ### Key Patterns - **Skills encapsulate operations** - Each skill handles one category of VM tasks diff --git a/scripts/generate_pack_data.py b/scripts/generate_pack_data.py index 5fdf4312..3ff4fe20 100644 --- a/scripts/generate_pack_data.py +++ b/scripts/generate_pack_data.py @@ -72,7 +72,7 @@ def load_plugin_titles() -> Dict[str, str]: def parse_plugin_json(pack_dir: str, plugin_titles: Dict[str, str]) -> Dict[str, Any]: """ - Parse plugin.json from a pack directory and merge with title from docs/plugins.json. + Parse optional plugin.json from a pack directory and merge with title from docs/plugins.json. Args: pack_dir: Name of the pack directory diff --git a/scripts/validate_structure.py b/scripts/validate_structure.py index ebc34930..369b0f5c 100644 --- a/scripts/validate_structure.py +++ b/scripts/validate_structure.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """ -Validate agentic collection pack structure (plugin.json, mcps.json, CLAUDE.md). +Validate agentic collection pack structure (mcps.json, CLAUDE.md; plugin.json optional). Skill-level validation (frontmatter, sections, security) is handled by validate-skills.sh and run-skill-linter.sh. @@ -18,13 +18,13 @@ def validate_plugin_json(pack_dir: str) -> List[str]: """ - Validate plugin.json structure. + Validate plugin.json structure when `.claude-plugin/plugin.json` exists. Args: pack_dir: Collection directory name Returns: - List of error messages (empty if valid) + List of error messages (empty if valid or file absent) """ errors = [] plugin_path = Path(pack_dir) / '.claude-plugin' / 'plugin.json' From 06cc14deebb10d4c8d0c26474b88cd49070f2998 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 13 Apr 2026 14:49:09 +0200 Subject: [PATCH 8/9] bump version numbers for all modules in rh-agentic-collection.yml from 0.0.1 to 0.1.0 Signed-off-by: Daniele Martinoli --- marketplace/rh-agentic-collection.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/marketplace/rh-agentic-collection.yml b/marketplace/rh-agentic-collection.yml index cff9dde8..11f3ab63 100644 --- a/marketplace/rh-agentic-collection.yml +++ b/marketplace/rh-agentic-collection.yml @@ -1,12 +1,12 @@ name: "redhat-agentic-collections" description: "Validated Agentic Collections from Red Hat Ecosystem Engineering" url: "https://github.com/RHEcosystemAppEng/agentic-collections" -version: "0.0.1" +version: "0.1.0" modules: - name: "ocp-admin" description: "Automation capabilities for OpenShift Container Platform cluster management, workload orchestration, security policies, and operational tasks." - version: "0.0.1" + version: "0.1.0" repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "ocp-admin" tags: @@ -17,7 +17,7 @@ modules: - name: "rh-developer" description: "Plugins for building and deploying applications on Red Hat platforms." - version: "0.0.1" + version: "0.1.0" repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "rh-developer" tags: @@ -32,7 +32,7 @@ modules: - name: "rh-sre" description: "Site reliability engineering tools and automation for managing Red Hat platforms and infrastructure." - version: "0.0.1" + version: "0.1.0" repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "rh-sre" tags: @@ -44,7 +44,7 @@ modules: - name: "rh-ai-engineer" description: "Red Hat OpenShift AI Engineering Agentic Collection" - version: "0.0.1" + version: "0.1.0" repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "rh-ai-engineer" tags: @@ -60,7 +60,7 @@ modules: - name: "rh-virt" description: "Virtual machine management and automation for OpenShift Virtualization and KubeVirt workloads." - version: "0.0.1" + version: "0.1.0" repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "rh-virt" tags: @@ -72,7 +72,7 @@ modules: - name: "rh-automation" description: "Ansible Automation Platform governance, execution safety, and forensic troubleshooting tools for Red Hat automation engineers." - version: "0.0.1" + version: "0.1.0" repository: "https://github.com/RHEcosystemAppEng/agentic-collections" path: "rh-automation" tags: From 2a581442eede3f8d035471f65821409fc873d864 Mon Sep 17 00:00:00 2001 From: Daniele Martinoli Date: Mon, 13 Apr 2026 14:53:05 +0200 Subject: [PATCH 9/9] remove rh-ai-engineer and rh-automation plugin.json files as part of project cleanup Signed-off-by: Daniele Martinoli --- rh-ai-engineer/.claude-plugin/plugin.json | 23 ----------------------- rh-automation/.claude-plugin/plugin.json | 21 --------------------- 2 files changed, 44 deletions(-) delete mode 100644 rh-ai-engineer/.claude-plugin/plugin.json delete mode 100644 rh-automation/.claude-plugin/plugin.json diff --git a/rh-ai-engineer/.claude-plugin/plugin.json b/rh-ai-engineer/.claude-plugin/plugin.json deleted file mode 100644 index 277f3bcf..00000000 --- a/rh-ai-engineer/.claude-plugin/plugin.json +++ /dev/null @@ -1,23 +0,0 @@ -{ - "name": "rh-ai-engineer", - "version": "1.0.0", - "description": "Plugins for deploying and managing AI/ML models on Red Hat OpenShift AI.", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": [ - "ai-engineer", - "openshift-ai", - "rhoai", - "kserve", - "vllm", - "nvidia-nim", - "model-serving", - "inference", - "gpu" - ] -} diff --git a/rh-automation/.claude-plugin/plugin.json b/rh-automation/.claude-plugin/plugin.json deleted file mode 100644 index 330c9501..00000000 --- a/rh-automation/.claude-plugin/plugin.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "name": "rh-automation", - "version": "1.0.0", - "description": "Ansible Automation Platform governance, execution safety, and forensic troubleshooting tools for Red Hat automation engineers.", - "author": { - "name": "Red Hat Ecosystem Engineering", - "email": "eco-engineering@redhat.com" - }, - "homepage": "https://github.com/RHEcosystemAppEng/agentic-collections", - "repository": "https://github.com/RHEcosystemAppEng/agentic-collections", - "license": "Apache-2.0", - "keywords": [ - "ansible", - "aap", - "automation", - "red-hat", - "governance", - "troubleshooting", - "execution" - ] -}