Skip to content

Managing Skills

The daily loop: see (status/scan) → absorb what's loose → dedup/clean → switch things on and off with enable/disable and packs.

Taking over loose skills (接管技能)

ipman absorb --user            # inventory: absorbable / git clone / suite / not-a-skill
ipman absorb --user my-notes   # take one over
ipman absorb --user --all      # every plain skill directory

Absorbing moves the directory into the store (as a fresh git repo, so changes are tracked from that point on) and leaves a symlink in its place — your agent sees exactly the same skill. The link points at a read-only pinned snapshot; pass --live to link the writable working copy instead (for skills you edit constantly).

What --all deliberately leaves alone: git clones (prefer their upstream), suite wrappers whose files are symlinks into a toolkit (e.g. gstack — its own updater owns them), marketplace plugins (your agent owns them), and anything without a SKILL.md.

Absorb is idempotent and resumable, and same-name absorbs across projects are content-compared: identical → deduplicated onto one store copy; different → refused with both versions preserved (--as <new-name> keeps both).

The dependent-detection guard

Absorb moves a directory into the store — so it refuses to move a directory that other skills link into. A suite root like a gstack toolkit clone has dozens of wrapper skills whose SKILL.md files are symlinks pointing back into it; absorbing it would break every one of them:

ipman absorb --user gstack
# gstack: 55 other skill(s) link into it (baoyu-design, browse, ...);
# absorbing would break them. This is a suite root — use 'takeover' to
# protect the whole directory instead.

The fix it points you at is takeover (see How It Works), which protects the whole directory at once without repointing anything a downstream skill depends on. A plain git clone with no dependents has nothing linking into it, so a named absorb of it works fine — only --all skips it, on the assumption you'd rather track its upstream.

Suite identity (套件识别)

Skills that belong to a self-managed toolkit are tagged with the specific suite they came from — not a bare suite, but suite:gstack:

ipman status -v
#   browse                 link   suite:gstack   active
#   design-review          link   suite:gstack   active

ipman scan rolls these up into a per-suite tally so you can see at a glance what's self-managed and should be left to its own updater:

ipman scan
# Suites detected (self-managed toolkits — use takeover, not absorb):
#   gstack: 55 skill(s)

Off and on without loss (停用/启用)

ipman disable my-notes --scope user
ipman enable  my-notes --scope user

disable removes only the symlink — the original stays in the store and the exact version pin stays in the ledger, so enable restores precisely what you had. The TUI's 归档区 lists everything enable-able in the current scope, including skills other scopes are using (enabling shares the same original — no copying).

Packs (功能包)

ipman pack create writing-kit my-notes baoyu-comic
ipman enable  --pack writing-kit --scope .      # into the current project
ipman disable --pack writing-kit --scope user

Packs are additive named sets: several can be active in one scope, they can overlap, and they work on native and custody scopes alike. Members must be store-managed (absorb first — pack creation tells you which ones aren't). In the TUI: Space to multi-select, p to create a pack from the selection.

Dedup and clean

ipman dedup && ipman dedup --apply
ipman clean && ipman clean --apply     # quarantines; --empty-trash purges

Dedup merges only semantically-compatible copies (loose dirs and unremoted absorbed skills); anything with its own upstream identity is reported, never merged. Clean never deletes — findings move to ~/.ipman/trash/<timestamp>/ and can be moved back.

Contributing fixes upstream

Absorbed skills are real git repos in the store. Edit there, commit, add a remote, PR — ipman doctor reminds you when a live working copy has uncommitted changes.