Repo Skills

Repo Skills is a small native CLI for shipping Agent Skills from the repository that owns them.

Skills often belong next to the SDK, framework, examples, tests, and docs that make them accurate. Repo Skills keeps that source checked in, then projects it into local agent skill roots by symlink or copy.

Install

Use npm when you want the packaged CLI:

npm install -g @bagakit/repo-skills

Build from source when working on the project:

git clone https://github.com/bagakit/repo-skills.git
cd repo-skills
make build
make install

Run without installing:

go run ./cmd/repo-skills -- repo status

Install with Go from a source checkout:

go install ./cmd/repo-skills

Go writes the binary to $GOBIN when set, otherwise to $GOPATH/bin. If repo-skills is not found after installation, add that directory to PATH.

export PATH="$(go env GOPATH)/bin:$PATH"
repo-skills repo status

Quick Start

Add a skill to your repository:

skill/my-project/SKILL.md

Declare it in repo-skills.toml:

version = 1
name = "my-project"

[[skillset]]
name = "default"
source = "skill/my-project"
layout = "single"
targets = ["agents"]
mode = "link"

Inspect and install the projection:

repo-skills repo status
repo-skills repo sync --dry-run
repo-skills repo sync

Inspect the installed skills on the machine:

repo-skills system inventory

Remove only projections that Repo Skills owns:

repo-skills repo unlink

Command Model

Repo Skills has two command surfaces. They are intentionally separate.

| Surface | Purpose | Requires repo-skills.toml | |---|---|---:| | repo-skills repo ... | Work with the current repository's manifest, source skills, and declared projections. | yes | | repo-skills system ... | Inspect local agent skill roots as installed-skill inventory. | no |

Repo commands:

repo-skills repo discover
repo-skills repo status
repo-skills repo sync
repo-skills repo unlink
repo-skills repo doctor

System commands:

repo-skills system inventory
repo-skills system doctor

Human output is compact and table-oriented. Use --json for automation:

repo-skills repo status --json
repo-skills system inventory --json

Manifest

repo-skills.toml is the repository-owned contract.

version = 1
name = "my-project"

[[skillset]]
name = "default"
source = "skill/my-project"
layout = "single"
targets = ["agents"]
mode = "link"

Fields:

| Field | Meaning | |---|---| | version | Manifest schema version. Current value: 1. | | name | Repository name used for stable source identity. | | source | Repo-local skill source directory or root containing skills. | | layout | single, top-level, or family. | | targets | Agent adapters such as agents, claude, gemini, opencode, or antigravity. | | mode | link, copy, or auto. | | scope | Optional global or local. Defaults to global. | | project | Optional local project path when scope = "local". |

Layouts:

| Layout | Source shape | |---|---| | single | source/SKILL.md is one skill. | | top-level | Each direct child of source with SKILL.md is a skill. | | family | Each source/<family>/<skill>/SKILL.md is a skill. |

Target Roots

Global target roots:

| Adapter | Root | |---|---| | agents | $HOME/.agents/skills | | claude | $HOME/.claude/skills | | gemini | $HOME/.gemini/skills | | opencode | $HOME/.config/opencode/skills | | antigravity | $HOME/.gemini/antigravity-cli/skills |

Local target roots are resolved below the selected project:

| Adapter | Local root | |---|---| | agents | .agents/skills | | claude | .claude/skills | | gemini | .gemini/skills | | opencode | .opencode/skills | | antigravity | .agent/skills |

Examples:

repo-skills repo status --agent claude
repo-skills repo sync --scope local --project ../consumer-app
repo-skills system inventory --agent agents,claude
repo-skills system inventory --target-root ~/.agents/skills

Safety Model

Repo Skills is conservative by default.

• Symlink projections are owned only when the link points at the declared source skill.
• Copy projections include .repo-skills-projection.json with a stable source identity and content hash.
• sync refuses foreign files, foreign directories, and foreign symlinks.
• unlink removes only owned symlinks or unmodified owned copies.
• Modified copies are left in place until a human resolves the drift.
• Ownership manifests do not store local absolute source paths.

npm Distribution

The npm package wraps the native Go binary with a small Node launcher.

Package layout:

package.json
npm/bin/repo-skills.js
npm/platform.js
npm/install.js
npm/binaries/repo-skills-<os>-<arch>

Build all npm binaries:

npm run build

Verify the package contents without publishing:

npm run pack:dry-run

Publish from a clean checkout:

NPM_TOKEN=... sh scripts/publish-npm.sh

Use PUBLISH_DRY_RUN=1 to run the build, tests, and pack check without publishing.

Development

Required tools:

• Go 1.25.0 or newer compatible toolchain
• Node.js 16 or newer for npm wrapper tests

Common checks:

go test ./...
go vet ./...
node --test npm/*.test.js
git diff --check

Build locally:

make build
./repo-skills repo status
./repo-skills system inventory

Format Go code:

make fmt

Non-Goals

Repo Skills is not a marketplace, registry resolver, rating system, or general package manager. It makes one narrower promise: when a skill belongs with a repository, the repository can distribute it safely and review it like code.

License

Repo Skills is released under the MIT License. See LICENSE.