Installs plugin components (skills, commands/workflows, rules, hooks, MCP) into the .agents/ central store and symlinks them to agent environments that require it (.claude/). DEFAULT method: run plugin_add.py for an interactive TUI that supports local and GitHub owner/repo installs. Use plugin_installer.py for scripted/CI single-plugin installs. Trigger when a user says "install plugin", "deploy plugin", "add plugin", "install from GitHub", or "sync plugin to agents".
From plugin-managernpx claudepluginhub richfrem/agent-plugins-skills --plugin plugin-managerThis skill is limited to using the following tools:
acceptance-criteria.mdevals/evals.jsonevals/results.tsvplugin.jsonreferences/acceptance-criteria.mdreferences/agent_bridge_diagram.mmdreferences/agent_bridge_overview.mdreferences/bridge_installer.pyreferences/ecosystem_system_bridge.mmdreferences/install_all_plugins.pyrequirements.txtscripts/bridge_installer.pyscripts/install_all_plugins.pyProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Designs KPI dashboards with metrics selection (MRR, churn, LTV/CAC), visualization best practices, real-time monitoring, and hierarchy for executives, operations, and product teams.
This skill requires Python 3.8+ and standard library only. No external packages needed.
To install this skill's dependencies:
pip-compile ./requirements.in
pip install -r ./requirements.txt
See ./requirements.txt for the dependency lockfile (currently empty — standard library only).
This skill deploys plugin components to agent environments using the
.agents/ central store + symlink pattern. It is the full-stack installer:
| Installer | Features | Requires Local Clone? | Recommended For |
|---|---|---|---|
uvx ★ default | Full interactive TUI | No (runs from GitHub) | Everyone using uv |
bootstrap.py | Full interactive TUI | No (downloads in-memory) | End users without uv |
legacy methods | Skills only | No (runs from GitHub) | Users wanting only individual skills |
plugin_add.py | Full interactive TUI | Yes | Local developers debugging the installer |
Use
uvx(★ recommended default) for an interactive TUI that installs full plugins without requiring Node.js. Use thebootstrap.pycurl pipeline if you do not haveuvinstalled. Useplugin_add.pydirectly for scripted/CI single-plugin installs from a local clone.
There is no difference between an initial install and a subsequent install from the consumer's perspective. Because uvx and bootstrap.py execute ephemerally, they are inherently stateless tooling.
You do not need to "install the installer". Just run the uvx or curl command whenever you need to add or update a plugin. The state is strictly kept inside your .agents/ repository.
The plugin_add.py interactive TUI (multiselect, arrow-key navigation, fuzzy search, owner/repo GitHub shorthand, temp-clone-then-install flow) is inspired by universal one-liner installation patterns:
This implementation re-creates those UX patterns in pure Python stdlib (no npm, no external packages) so they work on Windows without symlink issues and operate at the plugin level rather than individual SKILL.md files.
plugins/<plugin>/
skills/ → .agents/skills/<skill>/ (canonical copy, all agents read from here)
.claude/skills/<skill> → symlink (Claude Code)
commands/ → .agents/workflows/<plugin>_<cmd>.md (canonical copy)
.claude/commands/<plugin>_<cmd>.md → symlink (Claude Code)
rules/ → .agents/rules/<plugin>_<rule>.md (canonical copy)
CLAUDE.md → appended (Claude Code)
hooks/hooks.json → .agents/hooks/<plugin>-hooks.json (canonical copy)
.claude/hooks/<plugin>-hooks.json → symlink (Claude only)
.mcp.json → ./.mcp.json (merged)
Central store is always .agents/ at project root. Symlinks point from
each agent's own directory back into .agents/. This mirrors exactly how
npx skills manages its canonical store at .agents/skills/.
| Component | .agents/ (canonical) | .claude/ (Claude Code) |
|---|---|---|
skills/ | .agents/skills/<n>/ full copy | .claude/skills/<n> → symlink |
commands/*.md | .agents/workflows/<plugin>_<cmd>.md | .claude/commands/<plugin>_<cmd>.md → symlink |
rules/ | .agents/rules/<plugin>_<rule>.md | Appended → CLAUDE.md |
hooks/hooks.json | .agents/hooks/<plugin>-hooks.json | .claude/hooks/<plugin>-hooks.json → symlink |
agents/*.md | .agents/agents/<plugin>-<agent>.md | .claude/agents/<plugin>-<agent>.md → symlink |
.mcp.json | Merged → ./.mcp.json | Merged → ./.mcp.json |
Antigravity, Gemini, and GitHub Copilot all natively read from
.agents/— no separate symlinks needed. The canonical.agents/copy is sufficient.
Commands naming: Nested command folders are flattened to snake_case.
commands/ops/restart.md→<plugin>_ops_restart.md
commands/vsworkflows/naming: The plugin source folder is always namedcommands/. The installer writes to.agents/workflows/(canonical) and.claude/commands/(symlink). Never rename the source folder.
skills/as slash commands (Claude Code): In Claude Code, anyskills/<name>/SKILL.mdentry in a plugin is deployed to.claude/skills/<name>/and automatically functions as both a proactive skill AND a namespaced slash command (/plugin-name:name). This is the preferred pattern for new commands — usecommands/as thin wrappers that delegate to skills. The installer handles both paths independently; no special flag needed.
plugin_installer.py writes to the external skills lock file after installation
so that legacy tools remain aware of bridge-installed skills.
Lock file locations:
| File | Path | Purpose |
|---|---|---|
| Global lock | ~/.agents/.skill-lock.json | Tracks global installs; enables legacy check/update |
| Project lock | <project>/skills-lock.json | Tracks project installs; enables legacy experimental installs |
Lock file schema (version 3):
{
"version": 3,
"skills": {
"my-skill": {
"source": "richfrem/agent-plugins-skills",
"sourceType": "github",
"sourceUrl": "https://github.com/richfrem/agent-plugins-skills.git",
"skillPath": "plugins/my-plugin/skills/my-skill",
"skillFolderHash": "<git-tree-sha>",
"installedAt": "<iso-timestamp>",
"updatedAt": "<iso-timestamp>"
}
},
"dismissed": {}
}
After running plugin_installer.py, each installed skill must be written to
the appropriate lock file. Skills only — commands, rules, hooks, and MCP are
not tracked by npx skills.
uvx ★ Recommended# Interactive TUI from any GitHub repo
uvx --from git+https://github.com/richfrem/agent-plugins-skills plugin-add richfrem/agent-plugins-skills
# Install from Anthropic official plugins (has plugins/ subdir)
uvx --from git+https://github.com/richfrem/agent-plugins-skills plugin-add anthropics/claude-plugins-official
# Install from flat-layout repo (no plugins/ dir — auto-discovered)
uvx --from git+https://github.com/richfrem/agent-plugins-skills plugin-add anthropics/knowledge-work-plugins
# Install all non-interactively
uvx --from git+https://github.com/richfrem/agent-plugins-skills plugin-add richfrem/agent-plugins-skills --all -y
plugin_add.py (interactive TUI)The recommended local invocation. Supports the same GitHub source syntax as uvx.
plugin_add.py accepts a flexible owner/repo[/subpath] source:
| Source Format | What Happens |
|---|---|
richfrem/agent-plugins-skills | Clone repo, auto-detect plugins/ dir |
anthropics/claude-plugins-official/plugins | Clone repo, use plugins/ subpath directly |
anthropics/knowledge-work-plugins | Clone repo, no plugins/ dir — scans root for plugin-shaped dirs |
anthropics/knowledge-work-plugins/engineering | Clone repo, drill into engineering/ as a single plugin |
https://github.com/org/repo/tree/main/plugins | Full GitHub URL — tree/main/ is stripped automatically |
/local/path/to/repo | Local clone — same discovery waterfall |
When a repo root is resolved, plugins are found via three-tier fallback:
plugins/ subdir exists → scan its childrenplugins/ dir → scan root-level dirs that have .claude-plugin/plugin.json or skills/.claude-plugin/plugin.json → treat as one plugin# Interactive plugin picker — current repo
python ./scripts/plugin_add.py
# Install from remote GitHub repo (any layout)
python ./scripts/plugin_add.py richfrem/agent-plugins-skills
# Install specific subpath
python ./scripts/plugin_add.py anthropics/knowledge-work-plugins/engineering
# Full GitHub URL (tree/main/ stripped automatically)
python ./scripts/plugin_add.py https://github.com/anthropics/claude-plugins-official/tree/main/plugins
# Install all non-interactively
python ./scripts/plugin_add.py richfrem/agent-plugins-skills --all -y
# Dry-run preview
python ./scripts/plugin_add.py --dry-run
.claude/ Auto-InitIf no .claude/ directory exists in the target project, plugin_add.py will prompt:
No .claude/ directory found in this project.
Initialize .claude/ for Claude Code integration? [Y/n]
Answering Y (default) creates .claude/ so Claude Code symlinks are activated during installation. Answering n skips it — only .agents/ (the canonical store) will be populated.
bridge_installer.py (scripted / CI)Install a single plugin:
python ././scripts/bridge_installer.py \
--plugin plugins/my-plugin
Dry run (preview only, no writes):
python ././scripts/bridge_installer.py \
--plugin plugins/my-plugin --dry-run
CRITICAL: Do not run the installer without a Recap-Before-Execute summary. Always propose
--dry-runfirst for any destructive or first-time operation.
Before running the bridge, verify:
./plugin.json.agents/, .claude/ exists
(do NOT create these automatically — if missing, print the exact mkdir
command and wait for user confirmation)--target auto is used anywhere in the call chainState exactly what will happen:
### Plugin Installation Plan
- **Plugin**: plugins/my-plugin (v1.2.0)
- **Components**:
- 2 skills → .agents/skills/ (canonical) + .claude/skills/ symlinks
- 3 commands → .agents/workflows/, .claude/commands/
- 1 rules file → .agents/rules/, appended to CLAUDE.md
- hooks.json → .agents/hooks/ + .claude/hooks/
- **Detected environments**: claude (.claude/)
- **Lock file**: will update skills-lock.json
> Proceed? (yes to run live, no to dry-run first)
Wait for explicit confirmation before running live. Default to dry-run.
Do NOT create automatically. Print:
mkdir .claude # for Claude Code
Wait for user confirmation. A missing directory may mean an uninitialised project.
Do NOT scan for similar names. Report the error and list plugins/ contents.
Ask the user to confirm the correct plugin name.
Report each failed component individually with its error. Do NOT claim success. Offer to retry individual components once the user resolves the issue.
--target auto attemptedSTOP immediately. Ask the user to specify the exact environment name
(antigravity, claude, gemini, github). Never run with --target auto.
Log symlinkFailed: true. Fallback chain:
os.symlink() — true symlink (needs Developer Mode)mklink /J for dirs / mklink /H for files — no Developer Mode neededshutil.copy2() — plain copy (last resort, no live sync)Warn: "On Windows, enable Developer Mode for true symlink support."
Log the error but do not abort the install. Warn the user that
installed skills may not be tracked in skills-lock.json.
The installer auto-detects agent environments by checking for these directories
at project root. Antigravity, Gemini, and GitHub Copilot now natively read from
.agents/ so no per-agent symlinks are needed for them. Only environments that
require their own directory layout (Claude Code, Azure) are listed here:
DETECTABLE_AGENTS = {
".claude": {
"name": "claude",
"skills": ".claude/skills",
"agents": ".claude/agents",
"commands": ".claude/commands", # Markdown
"rules": None, # Append to CLAUDE.md instead
"rules_append_target": "CLAUDE.md",
"hooks": ".claude/hooks",
"rules_mode": "append",
},
".azure": {
"name": "azure",
"skills": ".azure/skills",
"commands": None,
"rules": None,
"hooks": None,
},
}
npx skills won't handlenpx skills list/check/update sees bridge-installed skillsnpx skills installs will be
missing these; bridge install completes the pictureplugin_add.py owner/repo (auto-clones + interactive TUI) or the authoritative installation hub for individual skills.maintain-pluginsmaintain-plugins — structural audits, sync, orphan cleanup, README generation