embed-plugins

Skill: embed-plugins

Embed plugins from public source repos into a target repo as project-local plugins. Each embedded plugin lives at .claude/plugins/<plugin-name>/ (full plugin tree, wholesale copy) and is enabled by bare name in .claude/settings.json — same shape as Anthropic's own pr-review-toolkit precedent.

When to use

• A consuming repo opted into one or more plugins and you want them committed to the repo's own files, so users in environments that can't install marketplace plugins (Claude Code Web, air-gapped CI) still get them.
• You added a new plugin to the manifest and want it embedded.
• The upstream plugin updated and you want to refresh the embedded copy.

When NOT to use

• For your own daily Claude Code use across many repos — install plugins user-level instead (claude plugin install <plugin>@<marketplace>). Embedding is for the consuming repo's benefit, not yours.
• To pull in plugin content you don't intend to keep current. Embedded files drift the moment upstream changes; running this skill is the maintenance step.

Procedure

1. Confirm the target repo has a manifest. Look for <repo-root>/.claude/embedded-plugins.json. If missing, the maintainer needs to add one. The format is:

   {
     "plugins": [
       { "source": "github:owner/repo", "ref": "main" },
       { "source": "github:other-owner/other-repo" }
     ]
   }
   

   ref defaults to main if omitted. The plugin's name is read from each source's own .claude-plugin/plugin.json — the manifest doesn't repeat it.

2. Run the embed script. From the target repo's root (or pass the path explicitly):

   bash ${CLAUDE_PLUGIN_ROOT}/scripts/embed-plugins.sh
   # or, against a different repo:
   bash ${CLAUDE_PLUGIN_ROOT}/scripts/embed-plugins.sh /path/to/target/repo
   

   The script:

   • Clones each listed source (shallow, to the manifest's ref).
   • Wipes any prior .claude/plugins/<plugin-name>/ for that plugin and copies the new tree in (without the upstream's .git).
   • Updates .claude/settings.json: enables the embedded copy by bare name ("<name>": true), and disables any matching marketplace entry ("<name>@<marketplace>": false) so hooks don't fire twice.
   • Idempotent. Running it again refreshes embedded copies to the manifest's current ref.

3. Inspect the diff. Embedded files are committed to the repo, so the diff goes through normal review. After running the embed:

   git status
   git diff .claude/settings.json
   git diff --stat .claude/plugins/
   

   Expect a wholesale tree under .claude/plugins/<name>/ per embedded plugin, plus a small .claude/settings.json toggle.

4. Commit. Single PR per refresh is fine; the embed is intentionally one logical unit.

Hard rules

• Don't hand-edit files under .claude/plugins/<embedded-plugin>/. Every embed run wipes and re-copies. Edits will silently disappear on the next refresh. If you need to fork a plugin's behavior, fork the upstream source repo and point the manifest at your fork.
• Don't gitignore .claude/plugins/. The whole point is committed-to-the-repo plugin content. If files weren't committed, environments that can't install marketplace plugins wouldn't see them.
• Don't run on a dirty .claude/plugins/ tree without committing first. The embed wipes existing trees for plugins listed in the manifest. Uncommitted edits there will be lost.

What lives where

plugin-embedder/                          # this plugin's own repo
  scripts/embed-plugins.sh                # the workhorse
  skills/embed-plugins/SKILL.md           # this file

<consuming-repo>/                         # any repo that wants embedded plugins
  .claude/
    embedded-plugins.json                 # manifest (committed; small)
    plugins/<plugin-name>/                # embedded plugin tree (committed)
    settings.json                         # `enabledPlugins` updated by embed script

Limitations

• Source repos must have .claude-plugin/plugin.json at the repo root. Monorepo subdirectories aren't supported (no path field in the manifest yet).
• ref must be a branch or tag. Raw commit SHAs are rejected by git clone --branch. Use a tag if you need reproducibility.
• Don't run two embeds against the same target concurrently. Wipe-then-copy isn't atomic.

Requirements

• git and jq on PATH (preflight-checked, errors loudly if missing). tar, mktemp, bash itself are POSIX-standard and assumed present.