Getting started

Install

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/driftsys/upskill/main/install.sh | sh

UPSKILL_VERSION pins a release tag (default: latest) and UPSKILL_INSTALL_DIR overrides the install location (default $HOME/.local/bin).

Windows (native — CMD / PowerShell):

cargo install upskill

Requires a Rust toolchain. The binary has no other runtime dependencies. HOME and USERPROFILE are both recognised as the global install root, so the standard Windows USERPROFILE variable works without any extra setup.

Windows (WSL): use the Linux install command above inside your WSL terminal.

Cross-platform alternative:

cargo install upskill

Or download a pre-built binary directly from the releases page.

upskill is a single static binary with no runtime dependencies.

Install your first source (consumer)

Inside a project where you want AI clients to pick up rules / skills / agents:

# Install everything from a source repo
upskill add driftsys/skills

# Or install a curated bundle (by name — resolves the .bundle.yaml automatically)
upskill add driftsys/bundles platform-baseline

# Pin to a tag, branch, or commit
upskill add driftsys/skills@v1.2.0

Generated files land in .claude/, .github/, and .agents/. The .upskill-lock.json file in your repo records what was installed and at which ref — commit it so other developers and CI regenerate the same content.

Verify state any time:

upskill list      # what's installed
upskill doctor    # any drift between lockfile and on-disk output?
upskill update    # re-fetch sources and regenerate

Configuring registries

To search content from corporate or custom registries, add them to your config:

# ~/.config/upskill/config.yaml
registries:
  - name: corp
    source: https://gitlab.com/mycompany/ai-skills
  - name: team
    source: myorg/team-skills

Then upskill search will include results from all configured registries. You can also search a specific registry:

upskill search auth --registry corp

Scaffold your first item (author)

Inside a source-registry repo (where SSOT items live), the recommended layout puts all items and bundles under a top-level skills/ directory (see Conventions):

mkdir -p skills && cd skills
upskill new skill code-review

This writes skills/code-review/SKILL.md with the minimum frontmatter the format spec requires (item directories live at one level under the source-registry root per format-spec §2.1). Open it, replace the TODO description and body, then run:

upskill lint --strict   # validate against the format spec
upskill fmt             # canonicalise YAML frontmatter

You can also scaffold rules (upskill new rule <name>) and agents (upskill new agent <name>). Bundles are plain *.bundle.yaml files that sit alongside the items they reference, also under skills/.

Man pages

upskill ships a man-page generator. Run it from the source tree:

just man             # or: cargo run --example mangen --release

That writes one .1 per command into target/man/:

target/man/upskill.1
target/man/upskill-add.1
target/man/upskill-doctor.1
…

Install system-wide:

sudo cp target/man/*.1 /usr/local/share/man/man1/
man upskill          # or: man upskill-add

Where to next

Commands — every verb explained, with flags.
Recipes — CI, private repos, pinning, cleanup.
Portable format — the on-disk SSOT contract the lint validates against.

Keyboard shortcuts