Skip to content

Skills

Skills are reusable prompt/recipe folders that agents can discover at runtime. Each skill is a directory with a SKILL.md file plus any supporting files it needs.

vp skills installs, lists, updates, and removes skills through the vibepod-skills-engine container, so you don't need Node, npm, pnpm, git, or skill-specific tooling installed locally.

Browse example skills and future VibePod-specific skills in the VibePod/vibepod-skills repository.

Quick start

# install a skill globally for your user
vp skills add github:vibepod/vibepod-skills//skills/researcher --scope user

# paste a GitHub tree URL directly
vp skills add https://github.com/org/repo/tree/main/skills/researcher --scope user

# install into the current project instead
vp skills add github:vibepod/vibepod-skills//skills/researcher --scope local

# show what's installed across local + user scopes
vp skills list

# remove it
vp skills delete researcher --scope user

Scopes

Scope Lives in Default when
local <project>/.vibepod/skills/ invoked inside a project (.vibepod/ present)
user ${XDG_CONFIG_HOME:-~/.config}/vibepod/skills/ invoked outside any project

If you want a project install, pass --scope local explicitly. This creates <project>/.vibepod/skills/ when needed. Without --scope local, a command run outside a directory tree that already contains .vibepod/ defaults to user.

Local skills shadow user skills when the same ID is installed in both. vp skills list shows which one wins.

Locator examples

Use canonical locators when you know them:

vp skills add github:org/repo//skills/researcher#v1.0.0
vp skills add gitlab:org/repo//skills/sql#main
vp skills add npm:@acme/vibepod-skill-researcher
vp skills add ./skills/my-skill --link --scope local

For GitHub, you can also paste the browser URL for a folder:

vp skills add https://github.com/org/repo/tree/main/skills/researcher

See Locator format for the full grammar, bundle installs, and reproducibility details.

For concrete examples, see the VibePod/vibepod-skills repository.

Example skill repositories

These repositories are useful places to browse existing skills and authoring patterns. Third-party skills can contain instructions and executable helper scripts, so review the source and license before installing them.

Example installs from external repositories:

vp skills add github:anthropics/skills//skills/claude-api --scope user
vp skills add github:addyosmani/agent-skills//skills/code-review-and-quality --scope user
vp skills add \
  https://github.com/obra/superpowers/tree/main/skills/systematic-debugging \
  --scope user
vp skills add \
  https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/spec-to-repo \
  --scope user

How agents see skills

When you run a supported agent, VibePod reads the local and user skill lockfiles, merges them, and mounts each installed skill into that agent's skill discovery directory. Local skills win over user skills with the same ID.

Current SKILL.md auto-discovery support:

Agent Skill mount target inside the container
claude /claude/skills/<id>
codex /config/.agents/skills/<id>
opencode /config/.agents/skills/<id>
auggie /config/.agents/skills/<id>
pi /config/.pi/agent/skills/<id>

Other agents can still run normally, but VibePod does not currently mount SKILL.md folders into an auto-discovery location for them.

Commands

Command What it does
vp skills add <locator> [--id] [--scope] Install a skill
vp skills list [--scope] [--json] Show installed skills with shadowing
vp skills delete <id> [--scope] Uninstall a skill
vp skills sync [--scope] Reconcile installed/ with the lockfile (no re-resolve)
vp skills update [<id>] [--scope] Re-resolve locators and rewrite the lockfile
vp skills export <id>... [--path] [--scope] [--force] Copy installed skills as plain folders to <path>/<id>/
vp skills cache clear Remove cached git clones and npm packages

All commands accept --json for machine-readable output. Apart from export, which only copies files on the host, the CLI is a thin wrapper around the engine container — see vibepod-skills-engine for what runs inside.

Use sync when you want to restore the exact installed contents from the lockfile. Use update when you want to re-resolve moving refs such as branches or package ranges and rewrite the lockfile.

Exporting skills

vp skills export copies installed skills out as plain SKILL.md folders, so you can commit them to a repository or hand them to someone else:

# into the current directory; local shadows user, as agents see it
vp skills export researcher sql

# take the user-scope copies and write them somewhere else
vp skills export researcher sql --scope user --path ./skills

Each skill lands in <path>/<id>/ (default: the current directory) exactly as installed; no lockfile or registry is written. Symlinks inside a skill are copied as symlinks, never followed. A skill installed with --link is exported as a plain copy of its linked source folder. An existing <path>/<id> is left alone unless you pass --force, and nothing is written when any requested ID is missing or would conflict. Even with --force, export refuses a <path>/<id> that is, contains or sits inside an installed skill in either scope, so it can never overwrite an installation.

The result is a skill bundle in its own right, so vp skills add ./skills/<id> (or the whole --path directory) installs it again.

Remote sources are fetched into skills-cache/ under the VibePod config directory. The engine re-fetches on every add, sync and update, so the cache never serves stale content; vp skills cache clear only reclaims disk space. Installed skills are copies and keep working after the cache is cleared.

Configuration

Env var Effect
VP_SKILLS_ENGINE_IMAGE Override the engine image (defaults to ${VP_IMAGE_NAMESPACE}/skills-engine:latest)
VP_IMAGE_NAMESPACE Used to derive the default engine image
VIBEPOD_TRUSTED_SOURCES Comma-separated locator prefixes; if set, all other locators are rejected