shuhari

Agent skills, on every machine.

shuhari links the skills you choose from git repositories into the directories your agents read. Each machine keeps its own config. Git carries the skills, and one command brings a machine up to date.

Install Read the concepts 
[targets]
claude = { kind = "host", path = "~/.claude/skills" }
agents = { kind = "host", path = "~/.agents/skills" }

[sources.agent-skills]
path   = "~/Projects/agent-skills"
git    = "git@github.com:you/agent-skills.git"
skills = ["personal/*"]

[sources.superpowers]
git    = "https://github.com/obra/superpowers.git"
skills = ["skills/*"]
rev    = "b55764852ac78870e65c6565fb585b6cd8b3c5c9"

[[install]]
skills  = ["agent-skills:rust-style", "superpowers:brainstorming"]
targets = ["claude"]
~/.config/shuhari/config.tomlOne machine config
  1. Install

    Prebuilt binaries for macOS and Linux, from the Homebrew tap.

    brew install attilagyorffy/shuhari/shuhari
  2. Init

    Find your skills, propose sources and install choices, write the config after you confirm.

    shuhari init
  3. Apply

    Link the chosen skills into each target.

    shuhari apply
  4. Sync

    Later: update every source, then apply.

    shuhari sync

It changes only what it owns.

A target directory often holds more than shuhari put there: a skill you are still writing, a link to another tool, a copy from an older setup. shuhari changes only symlinks that point into one of its sources and name one of its skills. It never overwrites or deletes a real directory, or a link that points somewhere else.

~/.claude/skills/
├── rust-style    → ~/Projects/agent-skills/personal/rust-style    1
├── brainstorming → ~/.local/share/shuhari/sources/superpowers/…  1
├── draft-skill/                                                2
│   └── SKILL.md
└── notes         → ~/Dropbox/notes                               3

Example targetThree kinds of entry

  • 1Owned link. It points into a source and names one of its skills. apply creates, replaces and removes these to match your install choices.
  • 2Real directory. shuhari reports it as not imported and leaves it in place. You can import it into a source, or declare it local.
  • 3Link that points elsewhere. Not shuhari's. It is never touched.

The one exception is shuhari import, which you run on purpose. It copies an unmanaged skill directory into a source, replaces the original with a link, and then deletes the original.

Init shows every change first.

shuhari init asks where your skills are: a git URL or a local path. It searches the repository for SKILL.md directories and proposes one skill pattern per parent directory. It proposes each git submodule as a separate source, pinned to the commit the repository records.

It adds an install choice for each link that already exists in your targets, so the next apply removes nothing that works now. Then it shows every change and the plan of the next apply, and writes the config only after you confirm.

summary: 40 linked, 1 kept local, 31 need attention, 9 not managed
  sources: 148 skills in 4 sources
  pending: 12 link changes; run `shuhari apply`

Example outputThe summary init prints

After it writes the config, init prints this summary. When an entry needs attention, it offers shuhari doctor --fix, which asks about each problem it can fix.

Install

The Homebrew tap attilagyorffy/homebrew-shuhari ships prebuilt binaries for macOS (Apple silicon and Intel) and Linux (x86_64). Installing needs no credentials and no Rust toolchain.

brew install attilagyorffy/shuhari/shuhari

InstallHomebrew

Upgrade with brew upgrade shuhari. From a checkout of the source, run cargo install --path ..

Quick start

shuhari init      # find your skills, propose sources and install choices, write the config
shuhari apply     # link the chosen skills
shuhari doctor    # check the whole setup; `doctor --fix` asks about each problem it can fix
shuhari sync      # later: update every source, then apply

Quick startFour commands

Every question that init asks has a flag, and --yes accepts every proposal. See init for the flags. Every command accepts --json.

The name

守破離 (shu-ha-ri) means “obey, break, leave”: the three stages of mastery in tea ceremony and the martial arts. A student first follows the form, then breaks from it, then leaves it behind. The tool keeps the skills you practice with on every machine. The name is a theme; shuhari does not track your progress.