/skillhone

name: skillhone
description: Local Issue, pull-request, and Wiki workbench for agent skills. Use when a user asks what skill problems, Issues, PRs, repair trajectories, work records, completed optimizations, pending fixes, or pending synchronization exist; when an Agent needs to report a reproducible skill defect; or when the user wants to initialize, inspect, optimize, review, merge, or synchronize a local skill repair. If a managed Skill has a missing referenced file, failing test, or broken command, invoke skillhone-auto-optimization before editing implementation files or installing dependencies. Uses a local SQLite/Git backend and DeepSeek Harness for optimization, with no hosted Git service.

SkillHone

Use SkillHone as the local maintenance layer for Agent-skill repositories. One Skill always maps to one Git repository and therefore owns an isolated set of Issue numbers, PR numbers, Wiki records, branches, tests, and repair Runs. The Catalog indexes those repositories but never combines their state. Any Agent runtime can call the CLI. DeepSeek Harness consumes the configured repair queue without a per-Issue approval step. User choice is required at Skill ownership and merge boundaries.

Route the user's intent first

Treat inspection and synchronization as different operations. Never turn a status question into a write:

• “修好了吗 / did the repair succeed / 测试通过了吗 / 优化到哪了” means inspect

only. Run `skillhone --skill <name> --json status`, then inspect the linked Issue, Run, and PR when needed. Report whether repair ran, tests passed, and the PR is open or merged. Do not merge and do not run `sync apply`.

• “已经同步了吗 / 我现在用的是新版本吗 / 需要同步吗” means inspect copy-back

state only. Run `skillhone --json sync status <name>` and interpret the state table below. Do not run `sync apply`.

• “帮我同步 / 把修复应用回去 / update my installed Skill” explicitly authorizes

copy-back. First run `sync status`; run `skillhone sync apply <name>` only when it returns `ready_to_sync` with `can_apply: true`.

`sync` never merges a PR. A repair can have passed tests while still waiting in an open PR, and a merged repair can still be waiting for copy-back.

Import existing Skills

Import one Skill directory or discover the Skills already installed for an Agent runtime. Before importing, ask the user which ownership mode they want:

• `copy` keeps the existing runtime Skill untouched, optimizes a copy under

`~/.skillhone/skills/`, and requires a later `sync apply` to copy a merged result back. A timestamped backup is made before applying.

• `takeover` (legacy alias: `managed`) backs up the existing runtime Skill and replaces it with a link to

the repository under `~/.skillhone/skills/`, so all Agents use the centrally optimized copy directly.

Never choose `takeover` or replace an existing Skill without the user's answer. Also ask whether passing local PRs should wait for review (`review`) or merge automatically after their tests pass (`automatic`). Do not infer either choice.

skillhone init /path/to/my-skill --mode copy --merge review
skillhone init --from codex --mode takeover --merge review
skillhone import /path/to/my-skill --mode copy
skillhone import --from codex --mode takeover
skillhone import --from cursor --mode copy
skillhone import --from claude-code --mode copy
skillhone import --from pi --mode copy
skillhone import --from zcode --mode copy
skillhone import --from all --mode copy
skillhone skills list
skillhone sync status
skillhone sync apply my-skill

Use `init` for first-time adoption because it records both choices and imports the Skill. Use `import` later when the global choices already exist and only a new Skill must be added. `init` without `--mode` or `--merge` deliberately returns `choice_required`; present those choices to the user instead of retrying with guessed values.

Interpret `sync status` as follows:

• `awaiting_merge`: repair may be complete, but its PR is still open; inspect it.
• `ready_to_sync`: merged central copy differs; explicit `sync apply` can apply it.
• `in_sync`: the copy-mode runtime Skill already has the merged result.
• `source_changed`: the runtime Skill changed separately; do not overwrite it.
• `takeover_active`: the runtime already points at SkillHone; no copy-back exists.
• `source_missing`, `repository_not_ready`, or `takeover_disconnected`: explain

the blocking state and stop.

In `copy` mode, `sync apply` creates a timestamped backup and is idempotent. In `takeover` mode, a merged default branch is already the runtime version, so a sync request should report `already-managed`, not copy files.

Each imported Skill becomes `~/.skillhone/skills/<name>`, an independent Git repository with an initial local commit. Re-importing identical content is idempotent; a conflicting Skill name is rejected instead of overwritten. The importer excludes runtime state and Git metadata and rejects detected secrets before creating Git history.

Inspect work

Run commands in the affected Skill repository, or select an imported Skill by name from anywhere. If the user supplies a repository path, that path is authoritative: use `--repo <path>` for the entire workflow and do not substitute a same-name or byte-identical catalog repository.

skillhone status
skillhone issue list
skillhone pr list
skillhone wiki list
skillhone web --open
skillhone --skill web-search status
skillhone --skill web-search issue list

When the user asks to see current Issues, PRs, Wiki work records, repair trajectories, completed optimizations, or pending work, prefer `skillhone web --open`. If opening a browser is inappropriate, return the JSON form instead:

skillhone --json status
skillhone --json issue view <N>
skillhone --json pr view <N>
skillhone --json wiki view <slug>

The Web workbench puts the per-Skill Issue, PR, and Wiki counts on the first screen. Status also includes an approval inbox for every open local PR. Its four record vi