diff --git a/.claude/skills/agentic-contribution-skill/SKILL.md b/.claude/skills/agentic-contribution-skill/SKILL.md index 18dc37be..7de3ff99 100644 --- a/.claude/skills/agentic-contribution-skill/SKILL.md +++ b/.claude/skills/agentic-contribution-skill/SKILL.md @@ -411,7 +411,7 @@ See [Prerequisites](#prerequisites) section for required system tools (git, uv, **External**: - [agentskills.io Specification](https://agentskills.io/specification) - Base skill standard - [Conventional Commits](https://www.conventionalcommits.org/) - Commit message format -- [Lola Package Manager](https://github.com/RedHatProductSecurity/lola) - AI skills package manager +- [Lola Package Manager](https://github.com/LobsterTrap/lola) - AI skills package manager ## Critical: Human-in-the-Loop Requirements diff --git a/.claude/skills/federation-request/SKILL.md b/.claude/skills/federation-request/SKILL.md index bcee4b7b..9959ce83 100644 --- a/.claude/skills/federation-request/SKILL.md +++ b/.claude/skills/federation-request/SKILL.md @@ -23,6 +23,10 @@ allowed-tools: Read Edit Write Bash Glob Grep Skill Guide users through creating a complete federation PR — from discovering pack metadata in an external repo to opening the pull request with the `federation` label. Only repository URL and pack path are asked upfront; other fields are inferred and confirmed before any writes. +**Install scope:** Federated modules are full Lola packs. `lola install -f ` installs **every skill** in the pack, the same as in-repo modules (`rh-sre`, `rh-developer`, etc.). There is no marketplace field to install a subset. + +**`ref` pinning:** Marketplace `ref` is required for CI/catalog in this repo but **ignored by Lola at install** until [lola#180](https://github.com/LobsterTrap/lola/issues/180). + ## Prerequisites **Required Tools**: @@ -154,7 +158,7 @@ Keep the temporary clone at `$TMP` through Phase 2 if no corrections require re- description: "" version: "" repository: "" - ref: "" # required project extension: 40-character commit SHA + ref: "" # required project extension: 40-character commit SHA (Lola ignores until lola#180) path: "" tags: - "" @@ -333,6 +337,7 @@ None — no MCP tools are invoked. ### Reference Documentation **Internal:** +- [Federation Request Guide](../../../FEDERATION_REQUEST_GUIDE.md) — contributor guide for federation requests - [Federation Review Guide](../../../FEDERATION_REVIEW_GUIDE.md) — evaluation criteria for federated packs - [COLLECTION_SPEC.md](../../../COLLECTION_SPEC.md) — collection catalog specification - [CONTRIBUTING.md](../../../CONTRIBUTING.md) — contribution paths overview diff --git a/.claude/skills/federation-review/SKILL.md b/.claude/skills/federation-review/SKILL.md index 7965e6bf..1f5fb00a 100644 --- a/.claude/skills/federation-review/SKILL.md +++ b/.claude/skills/federation-review/SKILL.md @@ -22,6 +22,10 @@ metadata: Validate an external agentic pack proposed for federation in a PR. Checks license compatibility, runs automated validation, and verifies the module is loadable by Lola. +Federated modules install as **complete Lola packs** — all skills under the declared `path`, same as in-repo marketplace modules. There is no per-skill marketplace filter. + +Federated modules install as **complete Lola packs** — all skills under the declared `path`, same as in-repo marketplace modules. There is no per-skill marketplace filter. + ## Prerequisites - Access to the agentic-collections repository @@ -116,7 +120,8 @@ lola market rm "$MARKET" ``` 2. **Check:** The federated module appears in the module list with correct name, version, and description. -3. **Output to user:** Lola verification result (visible or not, with details). +3. **Note:** Lola does not yet honor marketplace `ref` at install time ([lola#180](https://github.com/LobsterTrap/lola/issues/180)); verify listing only, not revision pinning. +4. **Output to user:** Lola verification result (visible or not, with details). ### Phase 5: Summary diff --git a/.github/workflows/federation-validation.yml b/.github/workflows/federation-validation.yml index 35e47bd4..c931b5d7 100644 --- a/.github/workflows/federation-validation.yml +++ b/.github/workflows/federation-validation.yml @@ -99,7 +99,6 @@ jobs: repo = mod.get('repository', '') ref = mod.get('ref', '') pack_path = mod.get('path', '.') - skills = mod.get('skills') name = mod.get('name', 'unknown') print(f'\n--- Validating: {name} ---') @@ -111,8 +110,6 @@ jobs: cmd = [sys.executable, 'scripts/validate_federation.py', repo, '--ref', ref, '--pack-path', pack_path, '--json', '--module-json', json.dumps(mod)] - if skills: - cmd.extend(['--skills'] + skills) result = subprocess.run(cmd, capture_output=True, text=True) print(result.stdout) diff --git a/CLAUDE.md b/CLAUDE.md index 35d61847..ff70132d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ 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. +Packs follow the [Lola](https://github.com/LobsterTrap/lola) package manager format. Install via `lola install -f ` from the marketplace. Each pack follows this structure: ``` @@ -44,7 +44,7 @@ There are two ways to add skills to this project: **Direct Contribution** — Skills are added directly to this repository, inside an existing pack. The contributor opens a PR, skills are reviewed and merged, and maintainers own them from that point. Use `/agentic-contribution-skill` in Claude Code or follow [CONTRIBUTING.md](CONTRIBUTING.md). -**Federation** — An external repository containing a complete, independent Lola pack is referenced in our catalog. The code stays in the external repo; users install it directly via Lola. The external owner maintains their pack. To request federation, open a PR adding the module to `marketplace/rh-agentic-collection.yml` with the `federation` label. Maintainers evaluate the pack using the [Federation Review Guide](FEDERATION_REVIEW_GUIDE.md) and the `/federation-review` skill. +**Federation** — An external repository containing a complete, independent Lola pack is referenced in our catalog. The code stays in the external repo; users install the **full pack** (all skills at `path`) directly via Lola. The external owner maintains their pack. To request federation, follow [FEDERATION_REQUEST_GUIDE.md](FEDERATION_REQUEST_GUIDE.md) or run `/federation-request` in Claude Code. Maintainers evaluate requests using [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md) and the `/federation-review` skill. ## Working with Agentic Collections diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d377324..1cba13bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,7 +72,8 @@ Both tiers must pass before submitting a PR. ## Resources - [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) -- Design principles and templates -- [Federation Review Guide](FEDERATION_REVIEW_GUIDE.md) -- How external packs are evaluated for federation +- [FEDERATION_REQUEST_GUIDE.md](FEDERATION_REQUEST_GUIDE.md) -- How to federate an external pack into the marketplace +- [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md) -- How external packs are evaluated for federation - [agentskills.io specification](https://agentskills.io/specification) -- Base skill standard - [Documentation site](https://rhecosystemappeng.github.io/agentic-collections) -- Browse all collections - [GitHub Issues](https://github.com/RHEcosystemAppEng/agentic-collections/issues) -- Report bugs or ask questions diff --git a/FEDERATION_REQUEST_GUIDE.md b/FEDERATION_REQUEST_GUIDE.md new file mode 100644 index 00000000..071672da --- /dev/null +++ b/FEDERATION_REQUEST_GUIDE.md @@ -0,0 +1,123 @@ +# Federation Request Guide + +List your external Lola pack in the Red Hat Agentic Collections marketplace **without moving code into this repo**. Users install from your repository via [Lola](https://github.com/LobsterTrap/lola). Maintainer review: [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md). + +> **Install scope:** `lola install -f ` installs the **full pack** at `path` (same as in-repo modules). No per-skill subset in marketplace YAML. +> **Lola `ref`:** Required here as a 40-character commit SHA for CI/catalog pinning. Lola ignores it at install until [lola#180](https://github.com/LobsterTrap/lola/issues/180). + +## Process + +```mermaid +flowchart TB + subgraph contributor ["Contributor"] + A["Prepare external pack
(Lola layout, LICENSE, skills)"] + B["validate_federation.py"] + C{Path} + D["/federation-request"] + E["Manual edits"] + F["PR: marketplace YAML + plugins.json
+ federation/modules/<name>/.catalog/"] + A --> B --> C + C -->|recommended| D --> F + C -->|this guide| E --> F + end + + subgraph ci ["CI (federation label)"] + G["Federation Validation workflow
Tier 1 blocks · Tier 2 warns · MCP when applicable"] + F --> G + end + + subgraph maintainer ["Maintainer"] + H{Path} + I["/federation-review"] + J["FEDERATION_REVIEW_GUIDE.md"] + K["Merge"] + G --> H + H -->|recommended| I --> K + H -->|manual| J --> K + end + + K --> L["Users: lola install -f <name>"] +``` + +| Skill | Role | When | +|-------|------|------| +| **`/federation-request`** | Contributor | Infer metadata from repo URL + pack path; prepare the PR | +| **`/create-collection`** | Contributor | Generate `federation/modules//.catalog/` from the external pack | +| **`/federation-review`** | Maintainer | Run checks and guide approval | +| **`/agentic-contribution-skill`** | Contributor | **Not federation** — add skills inside this repo ([CONTRIBUTING.md](CONTRIBUTING.md)) | + +--- + +## Requirements + +| Requirement | Details | CI | +|-------------|---------|-----| +| **Lola pack** | `CLAUDE.md`, `README.md`, `skills/` at declared `path` | Blocks | +| **License** | Apache-2.0–compatible LICENSE in your repo | Manual | +| **Tier 1** | [agentskills.io](https://agentskills.io/specification) linter | Blocks | +| **Tier 2** | [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) | **Warns** | +| **MCP** | If `mcps.json` has servers: pin images; `${ENV_VAR}` for secrets | Blocks when applicable | +| **Public repo + pinned `ref`** | Cloneable; 40-character commit SHA in marketplace entry | Blocks | + +```bash +uv run python scripts/validate_federation.py --ref <40-char-sha> +uv run python scripts/validate_federation.py --ref --pack-path +``` + +--- + +## Prepare the PR + +**Inputs** (for `/federation-request`): public **repository** URL and pack **path** (`.` at repo root). Everything else is inferred from a clone — `name`, `title`, `description`, `version`, `ref`, `tags`; override before opening the PR. Default maturity: **`ORANGE`**. + +**Three files to add or update:** + +1. **`marketplace/rh-agentic-collection.yml`** + +```yaml + - name: "" + description: "" + version: "" + repository: "" + ref: "<40-char-commit-sha>" + path: "" + tags: ["", "federation"] +``` + +2. **`docs/plugins.json`** — `"": { "title": "" }` +3. **`federation/modules//.catalog/`** — catalog at `ref` (`id:` = module `name`) + +```bash +git checkout -b feat/federate- +git add marketplace/rh-agentic-collection.yml docs/plugins.json federation/modules// +git commit -m "feat: federate module from " +gh pr create --title "feat: federate module" --label "federation" +``` + +The **`federation`** label triggers CI. Full check list: [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md#automated-validation-recommended). + +--- + +## After merge + +```bash +lola market add rh-agentic-collections https://raw.githubusercontent.com/RHEcosystemAppEng/agentic-collections/main/marketplace/rh-agentic-collection.yml +lola install -f +``` + +**Updates:** bump `version` and `ref` (new SHA), refresh `.catalog/` if needed, open a PR with the `federation` label. Promotion to **`GREEN`** lists the pack on the [documentation site](https://rhecosystemappeng.github.io/agentic-collections). + +--- + +## FAQ + +| Question | Answer | +|----------|--------| +| Subset of skills from a larger repo? | Use a dedicated pack subdirectory; set `path` to it. | +| Private repo or monorepo? | Public only; monorepos OK via `path`. | +| Tag instead of SHA for `ref`? | No — use `git rev-parse ` and pin the SHA. | +| Federation vs direct contribution? | Federation = external pack; direct = skills in this repo via `/agentic-contribution-skill`. | + +## Resources + +- [FEDERATION_REVIEW_GUIDE.md](FEDERATION_REVIEW_GUIDE.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) · [COLLECTION_SPEC.md](COLLECTION_SPEC.md) · [Lola](https://github.com/LobsterTrap/lola) diff --git a/FEDERATION_REVIEW_GUIDE.md b/FEDERATION_REVIEW_GUIDE.md index 834fcc8c..e98f8398 100644 --- a/FEDERATION_REVIEW_GUIDE.md +++ b/FEDERATION_REVIEW_GUIDE.md @@ -4,6 +4,10 @@ Step-by-step guide for maintainers evaluating a federation PR. Federation means referencing an **external agentic pack** in our catalog. The code stays in the external repo — we don't copy or modify it. Users install federated packs directly from the external repo via Lola. +Contributors: see [FEDERATION_REQUEST_GUIDE.md](FEDERATION_REQUEST_GUIDE.md) for how to open a federation PR. + +> **Lola `ref` field:** Marketplace `ref` is required here for validation and catalog pinning, but **Lola ignores it at install time** until [LobsterTrap/lola#180](https://github.com/LobsterTrap/lola/issues/180) is fixed. + ## Two ways to review | Method | When to use | @@ -26,9 +30,6 @@ uv run python scripts/validate_federation.py --ref <40-character-comm # Pack in a subdirectory uv run python scripts/validate_federation.py --ref --pack-path -# Only specific skills -uv run python scripts/validate_federation.py --ref --skills - # JSON output (for CI) uv run python scripts/validate_federation.py --ref --json ``` @@ -79,9 +80,9 @@ The module entry in `marketplace/rh-agentic-collection.yml` must have the requir | `description` | Yes | Brief description | | `version` | Yes | Module version | | `repository` | Yes | Git URL to the external repo | -| `ref` | Yes (project extension) | 40-character commit SHA pinning the pack (not a Lola field; required by this repo) | +| `ref` | Yes (project extension) | 40-character commit SHA (required by this repo; **Lola ignores until [lola#180](https://github.com/LobsterTrap/lola/issues/180)**) | -If the request is for a **subset of skills** (not the full pack), verify only the listed skill paths exist. +All skills under the pack's `path` are validated and installed — the same scope as in-repo marketplace modules. ### Step 3: Validate skills — Tier 1 (agentskills.io spec) diff --git a/README.md b/README.md index 84d41da8..bcdddaa7 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ## 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. +Install collections using [Lola](https://github.com/LobsterTrap/lola), the AI skills package manager. **Installation applies to the current folder only** — run commands from your project directory. ### One-time setup: add marketplace @@ -144,7 +144,7 @@ Each plugin has additional requirements: **New skill idea?** Run `/agentic-contribution-skill` in Claude Code. **Have an existing skill?** Run `/agentic-contribution-skill` and choose import mode. -**Want to federate your own pack?** Follow the [Federation Guide](docs/federation_guide.md). +**Want to federate your own pack?** Follow the [Federation Request Guide](FEDERATION_REQUEST_GUIDE.md). **Full guide:** [CONTRIBUTING.md](CONTRIBUTING.md) --- @@ -515,7 +515,7 @@ That CLI checks marketplace/plugin manifests for that workflow, including `plugi - **[Documentation Site](https://rhecosystemappeng.github.io/agentic-collections)**: Browse all collections, skills, and MCP servers - **[CLAUDE.md](CLAUDE.md)**: Repository structure and development workflow - **[Skill Design Principles](SKILL_DESIGN_PRINCIPLES.md)**: Quality guidelines for skills -- **[Federation Guide](docs/federation_guide.md)**: How to federate your external pack into the marketplace +- **[Federation Request Guide](FEDERATION_REQUEST_GUIDE.md)**: How to federate your external pack into the marketplace - **[Federation Review Guide](FEDERATION_REVIEW_GUIDE.md)**: How we evaluate external packs for federation - **[VALIDATION_REPORT.md](VALIDATION_REPORT.md)**: Marketplace compliance verification - **[Security Policy](SECURITY.md)**: Credential handling and vulnerability reporting diff --git a/SKILL_DESIGN_PRINCIPLES.md b/SKILL_DESIGN_PRINCIPLES.md index f742b9ad..e242262b 100644 --- a/SKILL_DESIGN_PRINCIPLES.md +++ b/SKILL_DESIGN_PRINCIPLES.md @@ -4,7 +4,7 @@ Repository-specific design principles for creating skills and agents in agentic **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). +**Distribution (Lola):** Packs are installed with the [Lola](https://github.com/LobsterTrap/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). **Collection catalog (pack-local):** Each pack may include **`/.catalog/collection.yaml`** and a **`collection.json`** mirror so tooling and docs can show a structured view of the collection. Authors follow [COLLECTION_SPEC.md](COLLECTION_SPEC.md) and the **create-collection** skill; field constraints are defined in **[`catalog/schema.yaml`](catalog/schema.yaml)** (JSON Schema in YAML). Pack **`SKILL.md`**, **`README.md`**, **`CLAUDE.md`**, and **`marketplace/rh-agentic-collection.yml`** stay the **sources of truth**; the catalog aggregates and summarizes them and does **not** replace or regenerate README or marketplace content. diff --git a/docs/app.js b/docs/app.js index 98350ed8..3db5e714 100644 --- a/docs/app.js +++ b/docs/app.js @@ -911,7 +911,7 @@ lola install -f ${moduleName}`; lolaLink.style.marginTop = '0.5rem'; lolaLink.style.fontSize = '0.85rem'; const lolaAnchor = document.createElement('a'); - lolaAnchor.href = 'https://github.com/RedHatProductSecurity/lola'; + lolaAnchor.href = 'https://github.com/LobsterTrap/lola'; lolaAnchor.target = '_blank'; lolaAnchor.textContent = 'Lola →'; lolaAnchor.style.color = 'var(--primary)'; diff --git a/docs/index.html b/docs/index.html index d15693d3..7ebec992 100644 --- a/docs/index.html +++ b/docs/index.html @@ -51,7 +51,7 @@

Red Hat Agentic Catalog