install-from-github

Files (1)

• SKILL.md

SKILL.md (first lines)

The user has found something on GitHub — a skill, an MCP server, a "Claude plugin" — and wants it integrated into their Claude Code setup **without leaving loose, untracked artefacts on disk**. The goal of this skill is to be a router: figure out what the project actually is, and pick the cleanest install path so the result is reproducible across machines.

Guiding principle: **everything the user installs should be reachable through a server-controlled surface** (the Skill-Substrate, when available; otherwise a marketplace they control), so a fresh machine can be reconstituted by reconnecting to the substrate or re-adding marketplaces. Loose skills dropped into `~/.claude/skills/` or one-off MCP entries scattered across configs are the failure mode this skill exists to prevent.

## Routing precedence (highest to lowest)

When a repo classifies as `claude-plugin` or `claude-marketplace`:

1. **Skill-Substrate** — if the user runs the substrate (i.e. has the `Skill-Substrate-Admin` plugin installed and the substrate is reachable), register the repo as a marketplace there. Subscriptions are server-side, so the install is reproducible across all the user's hosts without per-host bookkeeping. This is the default for Daniel.
2. **User's primary marketplace** — if the upstream is the user's own work and a primary marketplace exists.
3. **User's third-party marketplace** — for upstream by others, fork-and-wrap.
4. **Direct GitHub install** — last resort, only for one-off testing.

Detect substrate availability by checking for `~/.claude/plugins/Skill-Substrate-Admin/` or by attempting `ssh residencehome "docker ps --filter name=skill-substrate --format '{{.Names}}'"` (returns non-empty on substrate hosts). Skip the substrate path silently if neither indicator is present.

## Step 0: Onboarding — third-party marketplace pointer

This skill assumes the user has a dedicated **third-party marketplace** repo: a marketplace whose entries are wrappers around upstream projects authored by other people, kept distinct from the user's own original plugins.

Read config from:

```
${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/claude-rudder/config.json
```

Expected shape:

```json
{
  "third_party_marketplace": {
    "repo": "<owner>/<repo-name>",
    "local_path": "<absolute path to local clone>"
  },
  "primary_marketplace": {
    "repo": "<owner>/<repo-name>",
    "local_path": "<absolute path to local clone>"
  }
}
```

If `third_party_marketplace` is missing:

1. Tell the user this skill needs a designated third-party marketplace and explain why (portability — wrapped third-party skills live in one place, can be re-added on another machine via `claude plugins marketplace add`).
2. Ask whether they want to (a) point at an existing repo, or (b) bootstrap a new one.
3. If (b), scaffold a minimal marketplace repo: `.claude-plugin/marketplace.json` with empty `plugins: []`, a README explaining "this marketplace contains wrappers around third-party Claude Code skills and MCP servers", MIT license. Push to GitHub. Suggested name: `Claude-Third-Party-Plugins`.
4. Write the path back to `config.json`. Create the file (and its parent dir) if missing.

Never proceed past this step without a populated `third_party_marketplace.repo`.

## Step 1: Inspect the input

The user will give you a GitHub URL or `owner/repo`. Fetch enough to classify:

```bash
gh repo view <owner>/<repo> --json name,description,defaultBranchRef,url
gh api repos/<owner>/<repo>/contents -q '.[].name'
```

Then pull the files that disambiguate:

- `.claude-plugin/plugin.json` — it's a Claude Code plugin
- `.claude-plugin/marketplace.json` — it's a marketplace (multiple plugins inside)
- `SKILL.md` at root, or `skills/*/SKILL.md` without a `plugin.json` — loose skill(s)
- `package.json` with a `bin` field, or README mentioning `npx`, `mcpServers`, `claude_desktop_config.json` — MCP server
- `pyproject.toml` / `setup.py` exposing a CLI that speaks MCP — Python MCP server
- None of the above — out of scope; tell the user and stop

Use `gh api repos/<owner>/<repo>/contents/<path>` or `gh api repos/<owner>/<repo>/readme` to read files without cloning.

Record what you found in a short summary you'll show the user before acting.

## Step 2: Classify

Pick exactly one of:

| Class | Signal |
|---|---|
| `claude-plugin` | Has `.claude-plugin/plugin.json` |
| `claude-marketplace` | Has `.claude-plugin/marketplace.json` |
| `loose-skill` | Has `SKILL.md` or `skills/*/SKILL.md` but no `plugin.json` |
| `mcp-server` | NPX/Python package documented for MCP, no Claude plugin manifest |
| `other` | None of the above (CLI tool, library, demo) |

If the repo is **mixed** (e.g. an MCP server that also ships an example skill), prefer the most installable surface — usually `mcp-server` — and mention the secondary surface to the user.

## Step 3: Route

Show the user the classification and the proposed action, then act on confirmation.

### 3a. `claude-plugin`

Best case — it's already structured for native install.

1. Check whether the repo is already known to any of the user's surfaces:
   - **Substrate** (if available): `ssh residencehome "docker exec skill-substrate-skills-ingester-1 skills marketplace list"` — match on `source_repo`.
   - **Local marketplaces**: `claude plugins marketplace list`, then for each, check its `marketplace.json` for an entry whose `source.repo` matches.

2. **If found on the substrate** as marketplace `M`, the install command is:
   ```
   ssh residencehome "docker exec skill-substrate-skills-ingester-1 \
     skills install <M>:<plugin-name>"
   ```
   (Or call the `Skill-Substrate-Admin:admin-subscribe` skill.) Subscription is server-side; no further action needed.

3. **If found in a local marketplace** `M` (legacy / external host), the install command is:
   ```bash
   claude plugins install <plugin-name>@<M>
   ```
   Show the command. **Do not auto-install at user scope.** Mention `--scope project` for ad-hoc use.

4. **If not found anywhere**, offer routes in precedence order:
   - **Substrate route (preferred when substrate is reachable)** — register the repo as a one-plugin marketplace on the substrate, then ingest and subscribe:
     ```
     ssh residencehome "docker exec skill-substrate-skills-ingester-1 \
       skills marketplace add <owner>-<repo> --repo https://github.com/<owner>/<repo>.git \
         --visibility private --authorship third_party"
     ssh residencehome "docker exec skill-substrate-skills-ingester-1 \
       skills marketplace ingest <owner>-<repo>"
     ssh residencehome "docker exec skill-substrate-skills-ingester-1 \

From danielrosehill/Claude-Rudder, MIT.

More from danielrosehill/Claude-Rudder