@voidagency/skills

CLI to install skills and agent definitions from GitHub or Bitbucket. Skills go into .agents/skills/; agents can also copy AGENTS.md to your project root for Cursor/IDE.

Quick start

# Install skills from a repo
npx @voidagency/skills add owner/repo

# Install an agent (AGENTS.md + its skills)
npx @voidagency/skills add-agent owner/repo
# Or a specific agent in a multi-agent repo:
npx @voidagency/skills add-agent bitbucket:adminvoid/skills@vactory-nextjs

Source formats

| Format | Example | |--------|---------| | GitHub | owner/repo, https://github.com/owner/repo | | Bitbucket | bitbucket:owner/repo, https://bitbucket.org/owner/repo | | GitLab | https://gitlab.com/org/repo | | One skill | owner/repo@skill-name or bitbucket:owner/repo@skill-name | | Local | ./path/to/repo |

Commands

| Command | Description | |---------|-------------| | add <source> | Install skills from a repo or URL | | add-agent <source> | Install agent definition + all skills from its agent.json | | list, ls | List installed skills | | remove [skills] | Remove installed skills | | find [query] | Search for skills (needs SKILLS_API_URL) | | check | Check for skill updates | | update | Update all skills to latest | | init [name] | Create a new SKILL.md template |

Add options

| Option | Description | |--------|-------------| | -g, --global | Install to user directory instead of project | | -a, --agent <agents...> | Target agents: cursor, opencode (default: cursor) | | -s, --skill <skills...> | Install only these skills (use '*' for all) | | --copy | Copy files instead of symlinking | | -y, --yes | Skip confirmation prompts | | --all | Install all skills to all agents without prompts |

Add-agent scope

• Project (default): Agent definition → .agents/agent-definitions/<slug>/, skills → .agents/skills/. If there is no AGENTS.md at project root, it is copied there so Cursor/IDE loads it.
• Global (-g): Agent definition → ~/.agents/agent-definitions/<slug>/, skills → ~/.cursor/skills or ~/.config/opencode/skills.

Supported agents

| Agent | --agent | Project skills | Global skills | |-------|-----------|----------------|---------------| | Cursor | cursor | .agents/skills/ | ~/.cursor/skills/ | | OpenCode | opencode | .agents/skills/ | ~/.config/opencode/skills/ |

Both use the same project path (.agents/skills/). If no agent is detected, you’re prompted to choose.

Skills and agents

• Skill: A folder with a SKILL.md file (and optional other files). Installed as a whole. One agent can use many skills.
• Agent: A distributable with AGENTS.md and optional agent.json. agent.json lists skills: { "skills": ["owner/repo", "owner/repo@skill-name"] }. add-agent installs those skills and the agent definition.

SKILL.md format

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

# My Skill

Instructions for the agent.

Required: name, description. Optional: metadata.internal: true (hidden unless INSTALL_INTERNAL_SKILLS=1).

Where skills are discovered in a repo

The CLI looks for directories containing SKILL.md in: repo root, skills/, skills/.curated, skills/.experimental, skills/.system, .agents/skills, .claude/skills, and other common agent paths, then falls back to a recursive search.

Environment variables

| Variable | Description | |----------|-------------| | SKILLS_API_URL | Used by find for remote search | | INSTALL_INTERNAL_SKILLS | Set to 1 or true to install skills with metadata.internal: true |

Telemetry is disabled by default in this fork.

Troubleshooting

• No skills found — Repo must have valid SKILL.md files with name and description in the frontmatter.
• Skill not loading — Confirm the skill is under .agents/skills/ (or the agent’s global path) and that the agent is configured to load from there.
• Permission errors — Ensure you have write access to the target directory.

Build and publish

From monorepo root:

yarn install
yarn workspace @voidagency/skills build

Publish (from packages/cli): bump version in package.json, then npm publish. Package: @voidagency/skills on npm. Source: Bitbucket — adminvoid/void-skills.

Links

• Agent Skills specification
• Cursor skills
• OpenCode skills

License

MIT