| name | federation-request |
| description | Guide users through creating a federation PR to register an external agentic pack in the marketplace.
Collects only repository URL and pack path, infers other metadata from the repo, and confirms before proceeding.
Use when:
- "I want to federate my pack"
- "How do I add an external pack to the marketplace?"
- "Create a federation request"
- "Register an external module"
- User mentions "federation request", "federate", or "external module"
NOT for reviewing federation PRs (use /federation-review instead).
NOT for direct contributions (use /agentic-contribution-skill instead).
|
| license | Apache-2.0 |
| model | inherit |
| color | green |
| allowed-tools | Read Edit Write Bash Glob Grep Skill |
Federation Request
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 <name> 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.
Prerequisites
Required Tools:
git — version control
gh — GitHub CLI for PR creation
uv — Python environment manager (for /create-collection)
Verification:
which git >/dev/null && echo "✓ git" || echo "✗ git not found"
which gh >/dev/null && echo "✓ gh" || echo "✗ gh not found — install from https://cli.github.com"
which uv >/dev/null && echo "✓ uv" || echo "✗ uv not found — install from https://astral.sh/uv"
Human Notification Protocol:
If prerequisites fail:
❌ Cannot execute: <tool> not found
📋 Setup: <install instructions>
Security: Never display credentials. Never clone private repos without user confirmation.
When to Use This Skill
Use when:
- A user wants to register an external agentic pack in the marketplace
- A user asks how to federate a pack they maintain in another repository
- A user wants to create a PR to add a federated module
Do NOT use when:
- Reviewing an existing federation PR → Use
/federation-review
- Adding skills directly to this repository → Use
/agentic-contribution-skill
- Listing or inspecting existing clusters → Use
/cluster-inventory
Workflow
Phase 1: Discover and confirm module metadata
Collect only two inputs from the user, then infer the rest from the repository.
Step 1 — Ask for inputs (only these two)
-
repository — Git repository URL (e.g., https://github.com/org/repo)
- Validate: valid URL; must NOT be
https://github.com/RHEcosystemAppEng/agentic-collections (direct contribution, not federation)
-
path — Path to the skill pack inside the repo (e.g., ., plugins/claude-code-setup, my-pack)
- Validate: non-empty; use
. only when the pack root is the repo root
Do not ask for name, description, version, ref, tags, or maturity individually — infer them in Step 2.
Step 2 — Clone and infer fields automatically
After the user provides repository and path:
- Clone the repository to a temporary directory and resolve the default-branch HEAD commit SHA:
TMP=/tmp/federation-discover-$$
git clone --quiet --no-checkout "<repository>" "$TMP"
REF=$(git -C "$TMP" ls-remote origin HEAD | cut -f1)
git -C "$TMP" checkout --quiet "$REF"
PACK="$TMP/<path>"
- Verify the pack exists:
test -d "$PACK/skills" && echo "✓ Pack found" || echo "✗ No skills/ directory at <path>"
If verification fails, report the error and ask the user to correct the repository URL or path. Do not continue.
- Infer each field using this precedence (first match wins):
| Field | Inference rules |
|---|
| name | 1) .claude-plugin/plugin.json or .cursor-plugin/plugin.json → name · 2) basename of path (if not .) · 3) sole skills/<dir>/ folder name · Must be kebab-case, unique in marketplace/rh-agentic-collection.yml |
| title | Human-readable catalog display name · 1) README.md first # heading · 2) title-case words from name (claude-code-setup → Claude Code Setup) · 3) short phrase from plugin.json description · Non-empty, ≤120 chars; used in collection.yaml name: and docs/plugins.json |
| description | 1) plugin.json → description · 2) README.md first substantive sentence · 3) first skill SKILL.md frontmatter description (flatten to one line, ≤200 chars) |
| version | 1) plugin.json → version (normalize to semver X.Y.Z) · 2) default 0.1.0 |
| ref | REF from clone above (40-char commit SHA of default branch HEAD) |
| tags | Derive 3–6 kebab-case tags from skill folder names, plugin.json keywords, README headings, and path segments; always append federation |
| maturity | Default ORANGE (recommended for new federations; not listed on public GitHub Pages until promoted to GREEN) |
- Validate inferred values before presenting:
- name: kebab-case, 1–64 chars, not already in
marketplace/rh-agentic-collection.yml
- title: non-empty human-readable string; not identical to raw kebab-case
name unless no better source exists
- description: non-empty, under 200 characters
- version: semver
X.Y.Z
- ref: 40 hexadecimal characters (run
uv run python -c "import sys; sys.path.insert(0,'scripts'); import pack_registry as pr; print(pr.federation_ref_error('<ref>') or 'ok')" to verify)
- tags: at least one tag besides
federation
If inference fails or produces ambiguous results (e.g., multiple skill dirs with no plugin.json and path is .), show what was found and ask the user to clarify only the conflicting field(s), then re-infer.
Step 3 — Present summary and wait for confirmation
Show inferred values in one table. Include maturity and note that the user may override any field before confirming:
## Inferred module metadata
| Field | Value (inferred) | Source |
|-------------|-----------------------------------------------|---------------------|
| Name | <name> | plugin.json / path |
| Title | <human-readable title> | README / name |
| Description | <description> | README / SKILL.md |
| Version | <version> | plugin.json |
| Repository | <repository> | (user provided) |
| Ref | <40-character commit SHA> | default branch HEAD |
| Path | <path> | (user provided) |
| Tags | <tag1>, <tag2>, ..., federation | skills / README |
| Maturity | ORANGE | default (new federation) |
Reply **yes** to proceed, or tell me what to change (e.g., "use GREEN maturity", "title should be …", "name should be foo-bar").
Wait for explicit user confirmation before Phase 2. Apply any corrections the user requests, then confirm again if values changed materially.
Keep the temporary clone at $TMP through Phase 2 if no corrections require re-cloning; otherwise re-clone at the confirmed ref.
Phase 2: Create Marketplace Entry
- Action: Read
marketplace/rh-agentic-collection.yml
- Action: Append the new federated module entry before the comment block at the end of the file. Use this format:
- name: "<name>"
description: "<description>"
version: "<version>"
repository: "<repository>"
ref: "<commit-sha>"
path: "<path>"
tags:
- "<tag1>"
- "<tag2>"
- "federation"
-
Output to user: "Added module entry to marketplace/rh-agentic-collection.yml."
-
Action: Add a display-title entry to docs/plugins.json. Key must match the marketplace module name (not the repo path):
"<name>": {
"title": "<human-readable title>"
}
- Merge into existing
docs/plugins.json; preserve JSON formatting (2-space indent, trailing newline).
- Skip if the key already exists — update
title only when the user corrected it in Phase 1.
- Output to user: "Added
docs/plugins.json entry for <name>."
Phase 3: Generate Collection Files
- Action: Reuse the Phase 1 clone if still valid at the confirmed
ref, or clone again:
git clone --quiet --no-checkout <repository> /tmp/federation-<name>
cd /tmp/federation-<name> && git checkout --quiet <commit-sha>
- Action: Verify the pack exists at the declared path (skip if already verified in Phase 1):
test -d /tmp/federation-<name>/<path>/skills && echo "✓ Pack found" || echo "✗ No skills/ directory at <path>"
If the pack is not found, report the error and ask the user to verify the repository URL and path.
- Action: Create the federation module directory:
mkdir -p federation/modules/<name>
-
Action: Invoke the /create-collection skill targeting the cloned pack. The skill will generate collection.yaml and collection.json under .catalog/.
Since /create-collection expects the pack to be a local directory registered in the marketplace, work as follows:
- Point
/create-collection to the cloned pack at /tmp/federation-<name>/<path>/
- After generation, copy the resulting
.catalog/ contents to federation/modules/<name>/.catalog/
- Set
id: to the module name (kebab-case marketplace identifier)
- Set
name: in collection.yaml to the confirmed title (must match docs/plugins.json → title)
- Set
maturity: in collection.yaml to the value confirmed in Phase 1 (default ORANGE), then regenerate collection.json with uv run python scripts/catalog_yaml_to_json.py --pack federation/modules/<name>
mkdir -p federation/modules/<name>/.catalog
cp /tmp/federation-<name>/<path>/.catalog/collection.yaml federation/modules/<name>/.catalog/
cp /tmp/federation-<name>/<path>/.catalog/collection.json federation/modules/<name>/.catalog/
cp /tmp/federation-<name>/<path>/.catalog/*.md federation/modules/<name>/.catalog/ 2>/dev/null || true
- Action: Clean up the temporary clone:
rm -rf /tmp/federation-<name>
- Output to user: "Generated collection files at
federation/modules/<name>/.catalog/."
Phase 4: Create Pull Request
- Action: Create a feature branch:
git checkout -b feat/federate-<name>
- Action: Stage all changes:
git add marketplace/rh-agentic-collection.yml docs/plugins.json federation/modules/<name>/
- Action: Show the user what will be committed:
git diff --cached --stat
-
Action: Ask user to confirm the commit. Propose message:
feat: federate <name> module from <repository>
Wait for explicit confirmation.
-
Action: Commit and push:
git commit -m "<approved message>"
git push -u origin feat/federate-<name>
- Action: Create the PR with the
federation label:
gh pr create \
--title "feat: federate <name> module" \
--body "$(cat <<'EOF'
## Federation Request
Adds **<name>** as a federated module from [<repository>](<repository>).
### Module Details
| Field | Value |
|-------------|------------------|
| Name | <name> |
| Title | <title> |
| Version | <version> |
| Path | <path> |
| Ref | <commit-sha> |
### What's Included
- Module entry in `marketplace/rh-agentic-collection.yml`
- Display title in `docs/plugins.json`
- Collection catalog at `federation/modules/<name>/.catalog/`
### Validation
CI will run automated federation validation (repo LICENSE check, Tier 1, Tier 2, MCP pinning, credential scan) when the `federation` label is detected.
EOF
)" \
--label "federation"
- Output to user: The PR URL and a note that CI validation will run automatically.
Phase 5: Summary
Present final summary:
## Federation Request Complete
| Item | Status |
|-----------------------|--------|
| Marketplace entry | ✅ Added to marketplace/rh-agentic-collection.yml |
| plugins.json title | ✅ Added to docs/plugins.json |
| Collection files | ✅ Generated at federation/modules/<name>/.catalog/ |
| Pull request | ✅ <PR-URL> |
| CI validation | ⏳ Will run automatically (federation label applied) |
**Next steps:**
- CI will validate the federated module automatically
- A maintainer will review using `/federation-review`
- Once approved and merged, the module will be installable via `lola install -f <name>`
Dependencies
Required MCP Servers
None — this skill uses CLI tools only.
Required MCP Tools
None — no MCP tools are invoked.
Related Skills
/create-collection — generates .catalog/collection.yaml and collection.json for the federated pack
/federation-review — used by maintainers to validate the resulting PR
/agentic-contribution-skill — for direct contributions (not federation)
Reference Documentation
Internal:
Critical: Human-in-the-Loop Requirements
MUST confirm before:
- Inferred metadata (Phase 1): Present summary table with all inferred fields (including maturity); wait for yes or apply user corrections first
- Commit (Phase 4): Show staged changes and proposed message, wait for approval
- Push & PR (Phase 4): Confirm before pushing and creating the PR
NEVER:
- Push without explicit approval
- Create commits without confirmation
- Skip the Phase 1 confirmation step
- Proceed if the pack is not found at the declared path
Example Usage
User: /federation-request
Skill: I'll add your external pack to the marketplace. I only need two things:
1. Git repository URL
2. Path to the skill pack inside the repo (use "." if it's at the repo root)
User: https://github.com/partner-org/net-diag-skills
plugins/network-diagnostics
Skill: Cloning and inspecting the repository...
## Inferred module metadata
| Field | Value | Source |
|-------------|------------------------------------------------|---------------------|
| Name | network-diagnostics | plugin.json |
| Title | Network Diagnostics | README.md |
| Description | Network troubleshooting skills for SDN and ... | README.md |
| Version | 0.2.0 | plugin.json |
| Repository | https://github.com/partner-org/net-diag-skills | (user provided) |
| Ref | a1b2c3d4e5f6789012345678901234567890abcd | default branch HEAD |
| Path | plugins/network-diagnostics | (user provided) |
| Tags | networking, sdn, ovn, troubleshooting, federation | skills / README |
| Maturity | ORANGE | default |
Reply **yes** to proceed, or tell me what to change.
User: yes
Skill: ✅ Added module to marketplace/rh-agentic-collection.yml
✅ Added docs/plugins.json entry
✅ Generated collection files at federation/modules/network-diagnostics/.catalog/
...