skills

CLI tool to install OpenCode skills from public GitHub repositories.

Usage

npx skills add <github-repo-url> --skill <skill-name> [--ref <branch>]

Arguments

| Argument | Required | Description | |----------|----------|-------------| | <github-repo-url> | Yes | Public GitHub repository URL | | --skill <name> | Yes | Name of the skill to install | | --ref <branch> | No | Branch to fetch from (default: main) |

Examples

# Install a skill from the default branch (main)
npx skills add https://github.com/owner/repo --skill my-skill

# Install a skill from a specific branch
npx skills add https://github.com/owner/repo --skill my-skill --ref develop

Source Repository Convention

Skills must follow this directory layout in the source repository:

skills/
  <skill-name>/
    SKILL.md       ← fetched and installed locally

The CLI fetches only SKILL.md. Supporting files are not copied in v1.

Install Destination

Skills are installed to .opencode/skills/<skill-name>/SKILL.md relative to the current working directory.

.opencode/
  skills/
    <skill-name>/
      SKILL.md

Conflict Behavior

If .opencode/skills/<skill-name>/SKILL.md already exists, the installation is aborted. No data is overwritten silently.

To reinstall, remove the existing file first:

rm -rf .opencode/skills/<skill-name>
npx skills add <repo-url> --skill <skill-name>

Limitations

• Public repositories only — no authentication support in v1.
• SKILL.md only — recursive folder copy is out of scope.
• Default branch is main — use --ref for non-main branches. No master fallback.

Zero Dependencies

This package uses only Node.js built-ins (node:fs, node:path, node:util, native fetch). Node.js >= 18 is required.