skiller

skiller is a small Linux CLI for managing reusable agent skills across projects.

It keeps skill packages in one central library and creates symbolic links into the current project, so every repository can opt into the skills it needs without copying the same files over and over.

Platform support: official releases currently target Linux only. macOS and Windows are not official targets yet.

What it gives you

• One reusable Skill Library at ~/.skiller/skills.
• Per-project skill links under ./.agents/skills.
• Filesystem search for directories that contain SKILL.md.
• Safe default behavior: existing links or paths are not overwritten unless you pass --force.
• Release-ready builds with injected version, commit, and build date metadata.

Quick start

1. Install on Linux

curl -fsSL https://raw.githubusercontent.com/Rudnik-Ilia/skiller/main/install.sh | sh

The installer downloads the latest Linux release archive, verifies checksums.txt when sha256sum is available, and installs skiller into /usr/local/bin by default.

For a user-local install:

curl -fsSL https://raw.githubusercontent.com/Rudnik-Ilia/skiller/main/install.sh | SKILLER_INSTALL_DIR="$HOME/.local/bin" sh

Install a specific release tag:

curl -fsSL https://raw.githubusercontent.com/Rudnik-Ilia/skiller/main/install.sh | SKILLER_VERSION=v0.1.0 sh

As with any curl | sh installer, review install.sh first if you do not trust the source.

2. Import a skill package

A Skill Package is a directory that usually contains a SKILL.md file and optional supporting files.

skiller import ~/.agents/skills/pdf

This copies the package into the central Skill Library:

~/.skiller/skills/pdf

If the skill already exists in the library, use --force to replace it:

skiller import --force ~/.agents/skills/pdf

3. Link it into a project

From inside the project that should use the skill:

cd ~/my-project
skiller ln pdf

This creates a project-local symlink:

./.agents/skills/pdf -> ~/.skiller/skills/pdf

If a path with that skill name already exists in the project, use --force to replace it:

skiller ln --force pdf

4. List or remove project links

skiller ls
skiller rm pdf

rm removes the project symlink only. The central library copy remains available for other projects.

Workflow

Command reference

Command	Purpose
skiller search	Walk the filesystem from / and print discovered skill packages.
skiller import <path>	Copy a skill package into the central Skill Library.
skiller import --force <path>	Replace an existing central skill with the imported package.
skiller ln <skill>	Link a central skill into the current project.
skiller ln --force <skill>	Replace an existing project skill link or path.
skiller ls	List skills in the central library.
skiller rm <skill>	Remove a linked skill from the current project.
skiller version	Print version, commit, and build date.
skiller --version	Print the short version string.

Compatibility aliases are still supported:

Alias	Equivalent command
skiller add <path>	skiller import <path>
skiller list	skiller ls
skiller link <skill>	skiller ln <skill>
skiller remove <skill>	skiller rm <skill>
skiller unlink <skill>	skiller rm <skill>

Paths and configuration

Default central store:

~/.skiller/skills

Default project skill set:

./.agents/skills

Override the parent app directory with SKILLER_HOME:

SKILLER_HOME=/custom/path skiller ls

With that override, the central store becomes:

/custom/path/skills

Search behavior

skiller search scans from /, follows Linux filesystem conventions, and includes hidden directories so it can discover skill packages under paths such as .agents/skills and .skiller/skills.

Search output is tab-separated:

pdf	/home/YOUR_USER/.skiller/skills/pdf
grill-me	/home/YOUR_USER/.agents/skills/grill-me

Persistent search settings live in:

~/.skiller/settings.json

Example:

{
  "search": {
    "exclude": [
      "/home/YOUR_USER/.hermes",
      "/home/YOUR_USER/.claude",
      "/home/YOUR_USER/.codex"
    ],
    "ignoreDirs": [
      ".cache",
      ".git",
      ".hg",
      ".svn",
      "dev",
      "node_modules",
      "proc",
      "run",
      "sys",
      "target",
      "vendor",
      "__pycache__"
    ]
  }
}

• exclude is for full directory paths.
• ignoreDirs is for directory names that should be skipped wherever they appear.
• search does not accept paths or flags; use settings for persistent exclusions.

Alternative installation methods

Install with Go

Requires Linux and Go 1.22+:

go install github.com/Rudnik-Ilia/skiller@latest

Make sure your Go bin directory is on PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Build from source

git clone https://github.com/Rudnik-Ilia/skiller.git
cd skiller
go build -o skiller .
./skiller --help
./skiller version

Or use the Makefile:

make build
./bin/skiller --help

Development

Tests live in the top-level tests/ package and exercise the project mostly through exported APIs and CLI workflows.

Run the full local check:

make check

Run tests with cross-package coverage:

make coverage

Equivalent commands:

go test ./...
go test ./... -coverpkg=./... -coverprofile=coverage.out
go tool cover -func=coverage.out
go vet ./...
go build -trimpath -o /tmp/skiller-check .

Architecture

Domain vocabulary lives in CONTEXT.md.

Main modules:

cmd/                 Cobra command adapters
internal/app/        Project workflows, such as Project Install
internal/skills/     Skill Library and Project Skill Link behavior
internal/filesystem/ Filesystem seam and OS adapter
internal/config/     Path and environment configuration
internal/build/      Build metadata injected into release binaries

cmd/link.go is intentionally thin: it delegates the Project Install workflow to internal/app.ProjectInstaller.

Releases and versioning

skiller uses semantic version tags:

vMAJOR.MINOR.PATCH

Examples:

v0.1.0
v0.2.0
v1.0.0

Recommended version bumps:

• Increase PATCH for bug fixes: v0.1.0 → v0.1.1.
• Increase MINOR for new backward-compatible features: v0.1.0 → v0.2.0.
• Increase MAJOR for breaking CLI or behavior changes: v1.4.2 → v2.0.0.

Development builds report dev:

go run . version

Release builds inject the tag, commit, and build date. Users can inspect that metadata with:

skiller version
skiller --version

This repository includes GitHub Actions workflows:

• .github/workflows/ci.yml runs tests, coverage, go vet, and a build on pushes and pull requests.
• .github/workflows/release.yml builds Linux release archives when you push a version tag.

To publish a new release:

git tag v0.1.0
git push origin v0.1.0

The release workflow uploads:

skiller_linux_amd64.tar.gz
skiller_linux_arm64.tar.gz
checksums.txt

Publishing under a different GitHub repo

This project is currently configured for:

github.com/Rudnik-Ilia/skiller

If your GitHub username or repository name is different, replace Rudnik-Ilia/skiller in:

• go.mod
• Go import paths under main.go, cmd/, and internal/
• install.sh
• this README.md

Then run:

go mod tidy
go test ./...

Notes and limits

• Skills are expected to be directories.
• import copies a skill directory into the central store.
• ln creates a symlink from the current project to the central store.
• Existing links or paths are not overwritten unless --force is used.
• Linux is the only official target for current releases.

License

Released under the MIT License. See LICENSE.