pligo-cli

v0.3.1

Published

24 days ago

Unified plugin system for discovering, installing, and managing reusable AI agent capabilities

pligo

Install and manage plugins for AI coding agents.

Supports OpenCode, Claude Code, Codex, Cursor, and 38 more.

A plugin is a package that bundles one or more skills, commands, agent definitions, and MCP servers. Most plugins today are a single skill — but the format lets a single install pull in everything an agent needs to work with a domain.

Install a Plugin

npx pligo-cli add nicomoya123/pligo-registry

pligo is the binary provided by the pligo-cli package. If npx pligo-cli doesn't resolve directly, use npm install -g pligo-cli for a global install, or npx -p pligo-cli pligo ....

Source Formats

# GitHub shorthand (owner/repo)
npx pligo-cli add nicomoya123/pligo-registry

# Full GitHub URL
npx pligo-cli add https://github.com/nicomoya123/pligo-registry

# Direct path to a skill in a repo
npx pligo-cli add https://github.com/nicomoya123/pligo-registry/tree/main/skills/web-design-guidelines

# GitLab URL
npx pligo-cli add https://gitlab.com/org/repo

# Any git URL
npx pligo-cli add [email protected]:nicomoya123/pligo-registry.git

# Local path
npx pligo-cli add ./my-local-skills

Options

| Option | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | -g, --global | Install to user directory instead of project | | -a, --agent <agents...> | Target specific agents (e.g., claude-code, codex). See Available Agents | | -s, --skill <skills...> | Install specific skills from the plugin by name (use '*' for all skills) | | -l, --list | List available skills in the plugin without installing | | --copy | Copy files instead of symlinking to agent directories | | -y, --yes | Skip all confirmation prompts | | --all | Install everything in the plugin to all detected agents without prompts | | --full-depth | Search all subdirectories even when a root SKILL.md exists | | -n, --dry-run | Preview what would be installed without writing to disk |

Global Flags

These apply to every command:

| Option | Description | | ----------------- | ------------------------------------------------------------------------ | | -V, --verbose | Show detailed output (file paths, symlink targets, API calls) | | -q, --quiet | Suppress non-essential output (banner, info lines) | | -h, --help | Show help | | -v, --version | Show version |

Examples

# List skills in a repository
npx pligo-cli add nicomoya123/pligo-registry --list

# Install specific skills
npx pligo-cli add nicomoya123/pligo-registry --skill frontend-design --skill skill-creator

# Install a skill with spaces in the name (must be quoted)
npx pligo-cli add owner/repo --skill "Convex Best Practices"

# Install to specific agents
npx pligo-cli add nicomoya123/pligo-registry -a claude-code -a opencode

# Non-interactive installation (CI/CD friendly)
npx pligo-cli add nicomoya123/pligo-registry --skill frontend-design -g -a claude-code -y

# Install all skills from a repo to all agents
npx pligo-cli add nicomoya123/pligo-registry --all

# Install all skills to specific agents
npx pligo-cli add nicomoya123/pligo-registry --skill '*' -a claude-code

# Install specific skills to all agents
npx pligo-cli add nicomoya123/pligo-registry --agent '*' --skill frontend-design

Installation Scope

| Scope | Flag | Location | Use Case | | ----------- | --------- | ------------------- | ---------------------------------------------- | | Project | (default) | ./<agent>/skills/ | Committed with your project, shared with team | | Global | -g | ~/<agent>/skills/ | Available across all of your projects |

Installation Methods

When installing interactively, you can choose:

| Method | Description | | ------------------------- | ------------------------------------------------------------------------------------------- | | Symlink (Recommended) | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. | | Copy | Creates independent copies for each agent. Use when symlinks aren't supported. |

Other Commands

| Command | Description | | -------------------------------------- | ---------------------------------------------------------------------- | | npx pligo-cli list | List installed plugins (alias: ls) | | npx pligo-cli info <name> | Show details about an installed plugin | | npx pligo-cli find [query] | Search for plugins (aliases: search, f, s) | | npx pligo-cli manage | Interactive bulk plugin management (alias: m) | | npx pligo-cli remove [names] | Remove installed plugins (aliases: rm, r) | | npx pligo-cli check | Check for available plugin updates | | npx pligo-cli update [names...] | Update plugins to latest (all if none specified; alias: upgrade) | | npx pligo-cli doctor | Check installation health | | npx pligo-cli restore | Restore plugins declared in pligo-lock.json | | npx pligo-cli sync | Sync plugins from @pligo/* packages in node_modules | | npx pligo-cli init-hooks | Set up auto-sync hooks for detected agents | | npx pligo-cli completion [shell] | Generate shell completions (bash, zsh, fish) | | npx pligo-cli registry <subcmd> | Manage named plugin registries (alias: reg) |

`pligo list`

List all installed plugins. Similar to npm ls.

# List all installed plugins (project and global)
npx pligo-cli list

# List only global plugins
npx pligo-cli ls -g

# Filter by specific agents
npx pligo-cli ls -a claude-code -a cursor

# Machine-readable output
npx pligo-cli ls --json

`pligo info`

Show metadata for a single installed plugin: source, scope, install path, linked agents, timestamps, and content hash. Supports partial / case-insensitive name matching.

npx pligo-cli info web-design
npx pligo-cli info web-design --json

`pligo find`

Search for plugins interactively or by keyword. Falls back to a 24-hour stale cache when offline.

# Interactive search (fzf-style)
npx pligo-cli find

# Search by keyword
npx pligo-cli find typescript

# Search a named registry's marketplace
npx pligo-cli find typescript -r my-registry

# Search the current directory's marketplace.json
npx pligo-cli find --local

`pligo manage`

Interactive bulk-management UI: view plugins grouped by source, multi-select for removal.

npx pligo-cli manage

`pligo check` / `pligo update`

# Check if any installed plugins have updates
npx pligo-cli check

# Update all plugins to latest versions
npx pligo-cli update

# Update a single plugin by name
npx pligo-cli update web-design-guidelines

# Preview what would change
npx pligo-cli update --dry-run

`pligo doctor`

Runs health checks on your installation: directory structure, symlink integrity, lock-file validity, orphaned plugin directories, ghost lock entries, and agent detection.

npx pligo-cli doctor

`pligo restore`

Reinstall every plugin declared in the project's pligo-lock.json. Useful after cloning a repo, in CI, or after node_modules is wiped.

npx pligo-cli restore

`pligo sync`

Sync plugins from any @pligo/* packages present in node_modules. Pairs with init-hooks to auto-run on npm install.

npx pligo-cli sync
npx pligo-cli sync -y

`pligo init-hooks`

Set up auto-sync hooks for detected agents (currently Claude Code and Cursor). After installing, pligo sync runs automatically on relevant lifecycle events.

npx pligo-cli init-hooks

`pligo completion`

Generate shell completion scripts. Auto-detects the current shell from $SHELL if no argument is given.

npx pligo-cli completion bash >> ~/.bashrc
npx pligo-cli completion zsh  >> ~/.zshrc
npx pligo-cli completion fish > ~/.config/fish/completions/pligo.fish

`pligo registry`

Manage named plugin registries to search alternative marketplaces.

npx pligo-cli registry add my-org https://plugins.example.com
npx pligo-cli registry list
npx pligo-cli registry remove my-org

`pligo remove`

Remove installed plugins.

# Remove interactively (select from installed plugins)
npx pligo-cli remove

# Remove specific plugin by name
npx pligo-cli remove web-design-guidelines

# Remove multiple plugins
npx pligo-cli remove frontend-design web-design-guidelines

# Remove from global scope
npx pligo-cli remove --global web-design-guidelines

# Remove from specific agents only
npx pligo-cli remove --agent claude-code cursor my-plugin

# Remove all installed plugins without confirmation
npx pligo-cli remove --all

# Remove a specific plugin from all agents
npx pligo-cli remove my-plugin --agent '*'

# Use 'rm' alias
npx pligo-cli rm my-plugin

| Option | Description | | ---------------- | ------------------------------------------------- | | -g, --global | Remove from global scope (~/) instead of project | | -a, --agent | Remove from specific agents (use '*' for all) | | -y, --yes | Skip confirmation prompts | | --all | Remove every installed plugin from every agent | | -n, --dry-run | Preview what would be removed |

What are Plugins?

A plugin is a versioned package that bundles one or more agent capabilities. Each plugin can ship any combination of four asset kinds:

Skills — reusable instruction sets in SKILL.md files with YAML frontmatter (name, description). Skills follow the open Agent Skills specification.
Commands — slash-command definitions in commands/*.md.
Agent definitions — sub-agent personas in agents/*.md.
MCP servers — declarative MCP configuration that gets merged into the host agent's MCP config.

Plugins let agents perform specialized tasks like:

Generating release notes from git history
Creating PRs following your team's conventions
Integrating with external tools (Linear, Notion, etc.)

Most plugins today contain a single skill — the format scales up when a domain needs more than one asset.

Discover plugins at skills.sh.

Supported Agents

Skills can be installed to any of these agents:

| Agent | --agent | Project Path | Global Path | |-------|-----------|--------------|-------------| | Amp, Kimi Code CLI, Replit, Universal | amp, kimi-cli, replit, universal | .agents/skills/ | ~/.config/agents/skills/ | | Antigravity | antigravity | .agents/skills/ | ~/.gemini/antigravity/skills/ | | Augment | augment | .augment/skills/ | ~/.augment/skills/ | | Claude Code | claude-code | .claude/skills/ | ~/.claude/skills/ | | Cline, Warp | cline, warp | .agents/skills/ | ~/.agents/skills/ | | CodeBuddy | codebuddy | .codebuddy/skills/ | ~/.codebuddy/skills/ | | Codex | codex | .agents/skills/ | ~/.codex/skills/ | | Command Code | command-code | .commandcode/skills/ | ~/.commandcode/skills/ | | Continue | continue | .continue/skills/ | ~/.continue/skills/ | | Cortex Code | cortex | .cortex/skills/ | ~/.snowflake/cortex/skills/ | | Crush | crush | .crush/skills/ | ~/.config/crush/skills/ | | Cursor | cursor | .agents/skills/ | ~/.cursor/skills/ | | Deep Agents | deepagents | .agents/skills/ | ~/.deepagents/agent/skills/ | | Droid | droid | .factory/skills/ | ~/.factory/skills/ | | Gemini CLI | gemini-cli | .agents/skills/ | ~/.gemini/skills/ | | GitHub Copilot | github-copilot | .agents/skills/ | ~/.copilot/skills/ | | Goose | goose | .goose/skills/ | ~/.config/goose/skills/ | | Junie | junie | .junie/skills/ | ~/.junie/skills/ | | iFlow CLI | iflow-cli | .iflow/skills/ | ~/.iflow/skills/ | | Kilo Code | kilo | .kilocode/skills/ | ~/.kilocode/skills/ | | Kiro CLI | kiro-cli | .kiro/skills/ | ~/.kiro/skills/ | | Kode | kode | .kode/skills/ | ~/.kode/skills/ | | MCPJam | mcpjam | .mcpjam/skills/ | ~/.mcpjam/skills/ | | Mistral Vibe | mistral-vibe | .vibe/skills/ | ~/.vibe/skills/ | | Mux | mux | .mux/skills/ | ~/.mux/skills/ | | OpenCode | opencode | .agents/skills/ | ~/.config/opencode/skills/ | | OpenHands | openhands | .openhands/skills/ | ~/.openhands/skills/ | | Pi | pi | .pi/skills/ | ~/.pi/agent/skills/ | | Qoder | qoder | .qoder/skills/ | ~/.qoder/skills/ | | Qwen Code | qwen-code | .qwen/skills/ | ~/.qwen/skills/ | | Roo Code | roo | .roo/skills/ | ~/.roo/skills/ | | Trae | trae | .trae/skills/ | ~/.trae/skills/ | | Trae CN | trae-cn | .trae/skills/ | ~/.trae-cn/skills/ | | Windsurf | windsurf | .windsurf/skills/ | ~/.codeium/windsurf/skills/ | | Zencoder | zencoder | .zencoder/skills/ | ~/.zencoder/skills/ | | Neovate | neovate | .neovate/skills/ | ~/.neovate/skills/ | | Pochi | pochi | .pochi/skills/ | ~/.pochi/skills/ | | AdaL | adal | .adal/skills/ | ~/.adal/skills/ |

[!NOTE] Kiro CLI users: After installing skills, manually add them to your custom agent's resources in .kiro/agents/<agent>.json:
{
  "resources": ["skill://.kiro/skills/**/SKILL.md"]
}

The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select which agents to install to.

Creating Skills

Skills are directories containing a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: What this skill does and when to use it
---

# My Skill

Instructions for the agent to follow when this skill is activated.

## When to Use

Describe the scenarios where this skill should be used.

## Steps

1. First, do this
2. Then, do that

Required Fields

name: Unique identifier (lowercase, hyphens allowed)
description: Brief explanation of what the skill does

Optional Fields

metadata.internal: Set to true to hide the skill from normal discovery. Internal skills are only visible and installable when INSTALL_INTERNAL_SKILLS=1 is set. Useful for work-in-progress skills or skills meant only for internal tooling.

---
name: my-internal-skill
description: An internal skill not shown by default
metadata:
  internal: true
---

Skill Discovery

The CLI searches for skills in these locations within a repository:

Root directory (if it contains SKILL.md)
skills/
skills/.curated/
skills/.experimental/
skills/.system/
.agents/skills/
.augment/skills/
.claude/skills/
.codebuddy/skills/
.commandcode/skills/
.continue/skills/
.cortex/skills/
.crush/skills/
.factory/skills/
.goose/skills/
.junie/skills/
.iflow/skills/
.kilocode/skills/
.kiro/skills/
.kode/skills/
.mcpjam/skills/
.vibe/skills/
.mux/skills/
.openhands/skills/
.pi/skills/
.qoder/skills/
.qwen/skills/
.roo/skills/
.trae/skills/
.windsurf/skills/
.zencoder/skills/
.neovate/skills/
.pochi/skills/
.adal/skills/

Plugin Manifests

A plugin can declare its assets explicitly via .pligo/marketplace.json or .pligo/plugin.json (.claude-plugin/ is also accepted for backward compatibility with the Claude Code plugin marketplace). Manifests are the recommended way to ship a multi-asset plugin or a monorepo of plugins:

// .pligo/marketplace.json
{
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "my-plugin",
      "skills": ["./skills/review", "./skills/test"]
    }
  ]
}

If no manifest is present and no skills are found in standard locations, a recursive search is performed.

For interoperability with the Claude Code plugin marketplace, the .claude-plugin/ directory name continues to work.

Compatibility

Skills are generally compatible across agents since they follow a shared Agent Skills specification. However, some features may be agent-specific:

| Feature | OpenCode | OpenHands | Claude Code | Cline | CodeBuddy | Codex | Command Code | Kiro CLI | Cursor | Antigravity | Roo Code | Github Copilot | Amp | Neovate | Pi | Qoder | Zencoder | | --------------- | -------- | --------- | ----------- | ----- | --------- | ----- | ------------ | -------- | ------ | ----------- | -------- | -------------- | --- | ------- | --- | ----- | -------- | | Basic skills | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | allowed-tools | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | | context: fork | No | No | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | | Hooks | No | No | Yes | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No |

Troubleshooting

"No skills found"

Ensure the repository contains valid SKILL.md files with both name and description in the frontmatter.

Skill not loading in agent

Verify the skill was installed to the correct path
Check the agent's documentation for skill loading requirements
Ensure the SKILL.md frontmatter is valid YAML

Permission errors

Ensure you have write access to the target directory.

Environment Variables

| Variable | Description | | ------------------------- | -------------------------------------------------------------------------- | | INSTALL_INTERNAL_SKILLS | Set to 1 or true to show and install skills marked as internal: true |

# Install internal skills
INSTALL_INTERNAL_SKILLS=1 npx pligo-cli add nicomoya123/pligo-registry --list

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme