stevengonsalvez/plugins

/plugins - Extension Manager

Unified view and management of all external dependencies across the toolkit ecosystem.

Subcommands

• /plugins or /plugins list - Show all installed extensions
• /plugins add <name> - Add a new skill to the ecosystem
• /plugins sync - Update manifest from current installed state
• /plugins export - Generate reproducible install script
• /plugins status - Check versions against manifest

Universal Skill Lifecycle

Skills follow a single universal format (SKILL.md) across all agents. The toolkit provides a closed-loop system: skills enter from any tool, get canonicalized, and deploy everywhere.

                        SKILL ENTRY POINTS
                        ==================

    Claude Code              Codex CLI              Copilot CLI
    ───────────              ─────────              ───────────
    claude plugin install    $skill-installer       npx add-skill
    npx add-skill            npx add-skill          gh copilot skill
    manual copy              manual copy             manual copy
         │                       │                       │
         ▼                       ▼                       ▼
    {{HOME_TOOL_DIR}}/skills/       ~/.codex/skills/       ~/.copilot/skills/
         │                       │                       │
         └───────────┬───────────┘───────────────────────┘
                     │
                     ▼
              /sync-learnings          ◄── syncs new skills TO toolkit
                     │
                     ▼
         ┌───────────────────────┐
         │   packages/skills/    │     ◄── CANONICAL SOURCE (git-tracked)
         │   (toolkit repo)      │
         └───────────┬───────────┘
                     │
                     ▼
         ┌───────────────────────┐
         │ external-dependencies │     ◄── /plugins add or /plugins sync
         │       .yaml           │         updates the manifest
         └───────────┬───────────┘
                     │
                     ▼
              bootstrap.js             ◄── generates tool-specific output
                     │
          ┌──────────┼──────────┐
          ▼          ▼          ▼
     {{HOME_TOOL_DIR}}/  ~/.codex/  ~/.copilot/
      skills/     skills/     skills/     ◄── ALL tools get ALL skills
          │          │          │
          ▼          ▼          ▼
    setup-external.sh          ◄── git clone for agent-skills (external repos)


                     SKILL TYPES
                     ===========

    ┌─────────────────┬────────────────────┬──────────────────────┐
    │ Bundled          │ Agent-Skill         │ External (plugins)   │
    │ (we own it)      │ (3rd-party git repo)│ (tool-native)        │
    ├─────────────────┼────────────────────┼──────────────────────┤
    │ Lives in         │ SKILL.md stub in   │ Tracked in manifest  │
    │ packages/skills/ │ packages/skills/   │ only (not in repo)   │
    │                  │ + external-source  │                      │
    │ Deployed by      │ Deployed by        │ Installed by         │
    │ bootstrap copy   │ setup-external.sh  │ tool-native command  │
    │                  │ (git clone)        │                      │
    └─────────────────┴────────────────────┴──────────────────────┘


                     CLOSED LOOP
                     ===========

    1. Install skill via ANY tool ──► lands in ~/.{tool}/skills/
    2. /sync-learnings ──────────────► copies to packages/skills/ (canonical)
    3. /plugins sync ────────────────► updates external-dependencies.yaml
    4. bootstrap.js ─────────────────► deploys to ALL tools universally
    5. Repeat from any tool

Skill Type Decision

When adding a new skill, determine its type:

| Question | If YES | If NO | |----------|--------|-------| | Do we own/maintain the source? | Bundled | next question | | Is it a public git repo with SKILL.md? | Agent-skill | next question | | Installed via tool-native command? | External (manifest-only) | copy as bundled |

Data Sources

| Source | Location | Format | |--------|----------|--------| | Claude Plugins | {{HOME_TOOL_DIR}}/plugins/installed_plugins.json | JSON | | Marketplaces | {{HOME_TOOL_DIR}}/plugins/known_marketplaces.json | JSON | | Bundled Skills | packages/skills/*/SKILL.md | Markdown | | Unified Manifest | toolkit/external-dependencies.yaml | YAML |

/plugins list

Display all installed extensions grouped by category.

Output Format

# Installed Extensions

## Bundled Skills (5)
| Name | Path | Purpose |
|------|------|---------|
| webapp-testing | packages/skills/webapp-testing | Playwright-based testing |
| crypto-research | packages/skills/crypto-research | Cryptocurrency analysis |
| frontend-design | packages/skills/frontend-design | UI/UX generation |
| tmux-monitor | packages/skills/tmux-monitor | Session monitoring |
| retro-pdf | packages/skills/retro-pdf | Markdown to PDF |

## Claude Plugins (4)
| Name | Marketplace | Version | Installed |
|------|-------------|---------|-----------|
| beads | steveyegge/beads | 0.49.0 | 2026-01-24 |
| debug-bridge | stevengonsalvez/agent-bridge | 0.2.0 | 2026-01-11 |
| ralph-loop | anthropics/claude-plugins-official | e30768372b41 | 2026-01-11 |
| code-review | anthropics/claude-plugins-official | e30768372b41 | 2026-01-15 |

## MCP Servers (1)
| Name | Purpose |
|------|---------|
| context7 | Documentation lookup |

## npx Skills (0)
None installed

## Codex Skills (0)
None installed

Implementation

# Read Claude plugins
jq -r '.plugins | to_entries[] | "\(.key): \(.value[0].version)"' \
  /.claude/plugins/installed_plugins.json

# Read marketplaces
jq -r 'to_entries[] | "\(.key): \(.value.source.repo)"' \
  /.claude/plugins/known_marketplaces.json

# Read bundled skills
for skill in packages/skills/*/SKILL.md; do
  dirname "$skill" | xargs basename
done

/plugins add

Add a new skill to the toolkit ecosystem. Handles all three skill types.

Usage

/plugins add <name>                     # interactive — detects source
/plugins add <name> --from {{HOME_TOOL_DIR}}/skills/<name>   # from installed skill
/plugins add <name> --from https://github.com/org/repo  # from git repo

Workflow

Step 1: Detect Source and Type

Source provided?
  ├─ Local path (~/.*skills/<name>/) ──► check for .git/
  │    ├─ Has .git/ ──► Agent-skill (external repo)
  │    └─ No .git/  ──► Bundled (copy to packages/)
  │
  ├─ Git URL ──► Agent-skill
  │
  └─ No source ──► Scan all tool skill dirs for <name>:
       {{HOME_TOOL_DIR}}/skills/<name>/
       ~/.codex/skills/<name>/
       ~/.copilot/skills/<name>/
       If found: use that path and re-enter detection
       If not found: error — provide --from

Step 2: Validate SKILL.md

# Must have valid SKILL.md with frontmatter
SKILL_FILE="<source>/SKILL.md"
# Check: name and description fields present
# Check: no syntax errors in YAML frontmatter
# Extract: name, description, features for manifest entry

Step 3: Execute by Type

Bundled skill (we own it — copy into repo):

1. Copy skill directory to packages/skills/<name>/
2. Add entry to external-dependencies.yaml under bundled-skills
3. Re-run node toolkit/bootstrap.js for each tool
4. Verify skill appears in ~/.{tool}/skills/<name>/

Agent-skill (external git repo):

1. Create stub packages/skills/<name>/SKILL.md with external-source: frontmatter
2. Add entry to external-dependencies.yaml under agent-skills with repo URL
3. Re-run node toolkit/bootstrap.js for each tool
4. Run setup-external.sh for each tool (or just git clone directly)
5. Verify skill cloned into ~/.{tool}/skills/<name>/

External plugin/tool-native (already installed via tool command):

1. Add entry to appropriate manifest section (claude-plugins, codex-skills, copilot-skills)
2. Record version and install command
3. No bootstrap needed — already installed by tool

Step 4: Report

# Skill Added: <name>

| Field | Value |
|-------|-------|
| Type | Bundled / Agent-skill / External |
| Source | <path or URL> |
| Manifest | external-dependencies.yaml updated |
| Deployed to | claude, codex, copilot |

Run `/plugins status` to verify.

Examples

# Skill discovered in /.claude/skills/ during /plugins list drift check
/plugins add remotion-best-practices
# → Detects in /.claude/skills/, no .git → copies to packages/skills/ as bundled

# Skill from a public git repo
/plugins add ui-ux-pro-max --from https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
# → Creates stub SKILL.md with external-source, adds to agent-skills manifest

# Skill just installed via claude plugin install
/plugins add code-review --type external
# → Reads installed_plugins.json for version, adds to claude-plugins manifest

/plugins sync

Update toolkit/external-dependencies.yaml from current installed state.

Workflow

1. Read Current State

   • Parse {{HOME_TOOL_DIR}}/plugins/installed_plugins.json
   • Parse {{HOME_TOOL_DIR}}/plugins/known_marketplaces.json
   • Scan packages/skills/*/SKILL.md

2. Compare with Manifest

   • Identify new installations
   • Identify removed plugins
   • Identify version changes

3. Generate Diff Report

   # Plugin Sync Report
   
   ## Changes Detected
   
   | Plugin | Status | Details |
   |--------|--------|---------|
   | new-plugin | NEW | Installed from marketplace X |
   | old-plugin | REMOVED | No longer in installed_plugins.json |
   | beads | UPDATED | 0.48.0 -> 0.49.0 |
   
   Update manifest? [Y/n]
   

4. Update Manifest

   • Merge changes into external-dependencies.yaml
   • Preserve comments and formatting
   • Update updated timestamp

Implementation

#!/bin/bash
# Sync Claude plugins to manifest

MANIFEST="toolkit/external-dependencies.yaml"
PLUGINS_JSON="/.claude/plugins/installed_plugins.json"
MARKETPLACES_JSON="/.claude/plugins/known_marketplaces.json"

# Extract plugin data
jq -r '.plugins | to_entries[] | {
  name: (.key | split("@")[0]),
  marketplace_id: (.key | split("@")[1]),
  version: .value[0].version,
  installed_at: .value[0].installedAt
}' "$PLUGINS_JSON"

# Match with marketplace repos
jq -r 'to_entries[] | {
  id: .key,
  repo: .value.source.repo
}' "$MARKETPLACES_JSON"

/plugins export

Generate a shell script to reproduce the current setup on a new machine.

Output

#!/bin/bash
# Generated by /plugins export
# Reproduces toolkit extension setup
# Generated: 2026-01-24

set -e

echo "Installing Claude Code plugins..."

# Add marketplaces
claude plugin marketplace add steveyegge/beads
claude plugin marketplace add stevengonsalvez/agent-bridge
claude plugin marketplace add anthropics/claude-plugins-official

# Install plugins
claude plugin install beads
claude plugin install debug-bridge
claude plugin install ralph-loop
claude plugin install code-review

echo "Plugin installation complete!"
echo ""
echo "Note: MCP servers must be configured manually in claude_desktop_config.json"
echo "Note: Bundled skills are included in toolkit/packages/skills/"

Usage

# Generate and save script
/plugins export > setup-plugins.sh

# Make executable and run
chmod +x setup-plugins.sh
./setup-plugins.sh

/plugins status

Check if installed versions match manifest and highlight available updates.

Output Format

# Extension Status Report

## Version Check

| Plugin | Manifest | Installed | Status |
|--------|----------|-----------|--------|
| beads | 0.49.0 | 0.49.0 | OK |
| debug-bridge | 0.2.0 | 0.2.0 | OK |
| ralph-loop | e30768372b41 | e30768372b41 | OK |
| code-review | e30768372b41 | e30768372b41 | OK |

## Not in Manifest
- (none)

## In Manifest but Not Installed
- (none)

All extensions are in sync.

Implementation

# Compare manifest versions with installed
yq '.claude-plugins[] | "\(.name)=\(.version)"' toolkit/external-dependencies.yaml > /tmp/manifest_versions

jq -r '.plugins | to_entries[] | "\(.key | split("@")[0])=\(.value[0].version)"' \
  /.claude/plugins/installed_plugins.json > /tmp/installed_versions

diff /tmp/manifest_versions /tmp/installed_versions

Integration with /sync-learnings

The /sync-learnings command can optionally include plugin manifest sync:

## During /sync-learnings

If plugin changes detected:
1. Show plugin diff alongside file diff
2. Ask: "Also sync plugin manifest? [Y/n]"
3. If yes, run `/plugins sync` logic

File Locations

| File | Purpose | |------|---------| | toolkit/external-dependencies.yaml | Unified manifest (versioned) | | {{HOME_TOOL_DIR}}/plugins/installed_plugins.json | Claude's plugin state | | {{HOME_TOOL_DIR}}/plugins/known_marketplaces.json | Registered marketplaces | | packages/skills/*/SKILL.md | Bundled skill definitions |

Best Practices

1. Run /plugins sync after installing new plugins - Keep manifest up to date
2. Commit manifest changes - Track extension history in git
3. Use /plugins export for onboarding - New team members can reproduce setup
4. Check /plugins status periodically - Ensure consistency

Example Session

User: /plugins

Claude: # Installed Extensions

## Bundled Skills (5)
| Name | Purpose |
|------|---------|
| webapp-testing | Playwright-based testing |
| crypto-research | Cryptocurrency analysis |
| frontend-design | UI/UX generation |
| tmux-monitor | Session monitoring |
| retro-pdf | Markdown to PDF |

## Claude Plugins (4)
| Name | Version | Marketplace |
|------|---------|-------------|
| beads | 0.49.0 | steveyegge/beads |
| debug-bridge | 0.2.0 | stevengonsalvez/agent-bridge |
| ralph-loop | e30768372b41 | anthropics/claude-plugins-official |
| code-review | e30768372b41 | anthropics/claude-plugins-official |

## MCP Servers (1)
| Name | Purpose |
|------|---------|
| context7 | Documentation lookup |

Total: 10 extensions tracked
Manifest: toolkit/external-dependencies.yaml (last updated: 2026-01-24)