# ipman

Adopt this skill: https://proskills.md/skills/other/twisker-ipman-src-ipman-templates-ipman

Page: https://proskills.md/skills/other/twisker-ipman-src-ipman-templates-ipman
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: src/ipman/templates/ipman/SKILL.md
size: 3840
upstream: https://github.com/twisker/ipman/blob/main/src/ipman/templates/ipman/SKILL.md

```text
---
name: ipman
description: Skills housekeeper for this machine. Use when the user wants to tidy, organize, dedup, clean, archive/enable, pack, or take custody of agent skills — e.g. "整理技能", "清理 skills", "技能重复了", "接管技能目录", "停用/启用技能", "功能包", "organize my skills", "too many skills". Read-only inspection first; every write action needs explicit confirmation.
skill-version: {{VERSION}}
---

# IpMan 技能管家 (companion skill)

You drive the `ipman` CLI on the user's behalf. The TUI is for humans in a
terminal — NEVER launch bare `ipman` here. Use `--json` commands and render
panels in chat instead.

## Step 0 — preflight (every invocation)

1. `command -v ipman` — if missing, STOP and tell the user to install:
   `pipx install ipman-cli` (or `uv tool install ipman-cli`). Never continue
   silently without the CLI.
2. `ipman skill-sync --check --json` — three-way version check:
   - `cli_outdated: true` → tell the user a newer ipman exists on PyPI and
     suggest the **/ipman-update** skill (it detects pipx/uv/pip and upgrades,
     then regenerates the skills). Or, ONLY with their consent, run
     `pipx upgrade ipman-cli` directly. Never upgrade silently.
   - `skill_stale: true` → run `ipman skill-sync --self <this skill's dir>`
     to regenerate this skill from the installed CLI, then say
     "skill updated to match CLI vX — continuing with current instructions."
   - both false → proceed, say nothing.

## Interaction protocol (three steps)

1. **Render the panel.** Run `ipman status --json` (or `ipman scan --json`
   for deep results incl. duplicate groups and cleanable findings). Render a
   compact markdown panel: one row per scope (taken_over ⚑/native ○, active,
   archived/loadable, wild, broken), then per-scope detail on request —
   启用区 (active skills with linkness/ownership) and 归档区 (loadable items
   and packs with active ratios). Number the rows.
2. **Choose.** Small option sets (≤4 or grouped) → present via your host's
   question tool (arrow-key selection). Large lists → the user names rows by
   number or name; repeat their selection back before acting.
   HARD RULE: any write action (`absorb`, `dedup --apply`, `clean --apply`,
   `takeover`, `release`, `enable`, `disable`, `pack create`) requires one
   explicit confirmation. Show the dry-run output first where one exists.
3. **Execute and report.** Run the CLI command, then re-render the affected
   part of the panel so the user sees the before/after.

## Command map (user vocabulary -> CLI)

| 用户说 | 命令 |
|--------|------|
| 看看技能状况 / 全景 | `ipman status --json` |
| 深扫 / 找重复 / 找垃圾 | `ipman scan --json` |
| 接管技能 X（收进统一保管） | `ipman absorb <X> [--user]` |
| 接管整个目录（保护层：防误删、可整体恢复） | `ipman takeover user` (or `.` for the project) |
| 修复被外部更新器打断的接管 | `ipman takeover <scope>` (auto-repairs, merges new skills) |
| 释放目录 | `ipman release <scope>` |
| 停用 X（先撤下，还能再启用） | `ipman disable <X> [--scope user]` |
| 启用 X / 整包启用 | `ipman enable <X> \| --pack <P> [--scope user]` |
| 去重 | `ipman dedup` then, confirmed, `ipman dedup --apply` |
| 清理断链/垃圾 | `ipman clean` then, confirmed, `ipman clean --apply` (quarantines to ~/.ipman/trash) |
| 定义功能包 | `ipman pack create <name> <skills…>` |
| 项目登记 | `ipman init` (inside the project) |

Safety notes you may relay when relevant: apply-level actions are dry-run
first and quarantined (recoverable from ~/.ipman/trash); absorb never touches
marketplace plugins, git clones (kept for their upstream) or suite wrappers;
disable never deletes content — the store keeps the original.
```

## File: README.md
upstream: https://github.com/twisker/ipman/blob/main/README.md

````text
<p align="center">
  <img src="images/IpMan.jpg" alt="IpMan Banner" width="600" />
</p>

# IpMan - Intelligence Package Manager

*I can take on ten.*

> The skills housekeeper for AI agents. Discover, organize, absorb, dedup and clean the skills already on your machine — like a disk-cleanup utility, but for agent skills. It never installs and never destroys.

**[Documentation](https://twisker.github.io/ipman)** | **[中文文档](https://twisker.github.io/ipman/zh/)** | **[中文 README](README.zh-cn.md)**

---

## What it is (and is not)

Skills pile up: copied folders, half-remembered clones, duplicates across projects, broken leftovers. Your agent's own tooling installs skills — but nothing tidies them.

IpMan is that missing housekeeper. **It does not install or uninstall skills** — your agent's native mechanisms keep doing that. IpMan handles what they don't:

| Verb | What it does |
|------|--------------|
| **scan / status** | See every skills directory (user-global and per-project) and the true state of each skill: real dir, symlink, broken, duplicate, suite-managed |
| **absorb** | Take loose skill folders into one central store (a fresh git repo each — changes tracked from then on) and leave a symlink in place. Your agent notices nothing |
| **dedup** | Find byte-identical copies across projects and merge them onto one stored original |
| **clean** | Broken links, orphaned store entries, empty shells — quarantined to `~/.ipman/trash`, never deleted |
| **enable / disable** | Switch a skill off without losing it (the link goes, the original stays), switch it back on anytime |
| **pack** | Name a set of skills and enable/disable them as one unit, in any scope |
| **takeover / release** | Optionally put a whole skills directory in IpMan's custody: survives accidental `rm -rf`, restorable with one `sync` |

Everything destructive is dry-run first and quarantined — recoverable, always.

## Quick start

```bash
pipx install ipman-cli        # or: pip install ipman-cli / uv tool install ipman-cli

ipman                         # in a terminal: the interactive TUI
ipman status                  # or the same, as plain text
ipman scan                    # deep scan: wild skills, duplicates, cleanables
```

Typical first session:

```bash
ipman absorb --user           # inventory of ~/.claude/skills: what's absorbable
ipman absorb --user my-notes  # take one over (moved to store, symlinked back)
ipman dedup                   # duplicate report (dry-run)
ipman clean                   # cleanables report (dry-run)
```

## Toolkits are recognized, not mangled

Toolkits like gstack are git clones that dozens of your other skills symlink *into*. IpMan identifies them — `scan` reports `Suites detected: gstack: 55 skills`, and each wrapper shows `suite:gstack` rather than a generic `suite`. Trying to `absorb` such a root is refused (it would break every dependent); the right move is directory **custody** (`takeover`), which protects the whole directory while leaving the toolkit's own updater untouched. Marketplace plugins and independent clones are never touched either.

## Use it from inside your agent

Install the companion skills (explicitly — IpMan never auto-installs anything, not even itself):

```bash
ipman skill-sync --scope claude-code-user   # installs 'ipman' + 'ipman-update'
```

Then tell your agent "clean up my skills" / "整理一下我的技能" — it drives the same engine through `--json` commands, confirming before every write. The skills stay version-locked to the CLI (`ipman skill-sync --check`).

**Updating** is a skill too: `/ipman-update` detects how you installed (pipx / uv / pip), upgrades the CLI from PyPI on your OK, then regenerates the skills so they never drift from the tool.

**Status bar**: `ipman statusline` prints one line for your agent's status bar:

```bash
ipman statusline    # -> 📦 user⚑12 | myproj✓3 | !1断链   (⚑ custody, ✓ native)
```

Wire it into Claude Code's `statusLine` command in `settings.json`.

## Speaks your language

The whole interface — status values (`real`/`link`/`broken`), error messages, the TUI and CLI output — auto-switches between English and Chinese based on your locale (`LANG` / `LC_ALL`). `zh*` gives you 真目录/软链接/断链; anything else stays English. Nothing to configure.

## Safety model

- **Never installs, never uninstalls** — organization only
- **Dry-run first**: `dedup`/`clean` report before `--apply`
- **Quarantine, not deletion**: `clean --apply` moves to `~/.ipman/trash`; `--empty-trash` is a separate, explicit step
- **Pinned read-only originals**: absorbed skills link to read-only snapshots — even a trailing-slash `rm -rf` can't gut the store
- **Toolkits, clones and marketplace plugins are left alone**: anything with its own manager or upstream is reported, never touched

## Status

v3 (0.4.x): the housekeeper surface is new; verified on macOS with Claude Code. Windows: per-skill operations expected to work (junction fallback, CI-tested), directory takeover pending a Windows verification pass. Feedback and issues welcome.

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.
````
