integrate-agentgear
This skill should be used when adding agentgear to a Rust binary that ships a Claude Code plugin, or migrating a hand-rolled install, self-heal, or per-harness config-merge engine onto its derive.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- integrate-agentgear
- description
- This skill should be used when adding agentgear to a Rust binary that ships a Claude Code plugin, or migrating a hand-rolled install, self-heal, or per-harness config-merge engine onto its derive.
- when_to_use
- Use when a binary should install its own CC plugin, when a plugin needs to reach non-CC harnesses without hand-writing a translator per harness, or when deciding whether a given plugin is a fit.
03 SKILL.md 正文
integrate-agentgear
One #[derive(PluginHost)] struct gives a host the full install / uninstall / update /
self-heal / doctor lifecycle. agentgear drives the claude plugin CLI for those ops and bakes the
plugin tree into the binary. It writes that one Claude-Code plugin into 23 other harnesses'
native config files, detect-gated, never clobbering user config (copilot-cli is a 25th target,
orchestrated through its own plugin CLI rather than a per-surface config translate). The host declares intent once;
agentgear delivers it per harness.
This skill is the process. The exhaustive API lives in the repo's wiki/ pages (mapped at the end); cite them rather than restating them.
fit check (do this first)
Answer these before writing any code. A "no" changes the plan.
- Does one binary both ship and install the plugin? agentgear's embed model assumes the
PluginHostbinary IS the artifact that carries and installs the plugin tree. A plugin whose binary is a separate, independently-versioned artifact the plugin locates at runtime (say, one it finds on PATH) has no clean agentgear story yet. - The plugin's own binary distribution stays the host's job.
Sourcemodels where the plugin tree comes from, never where the host's compiled binary comes from. Keep any curl+checksum / PATH-resolution / version-GC installer the host already has; agentgear does not replace it. - Which harnesses does it target? A Claude-Code-only plugin needs only the default
claudebackend, so the 24-harness translate does nothing for it. That is fine: the win there is the automated lifecycle (setup / self-heal / doctor / version-guard), not translation. Only name extraagents = [...]when the plugin genuinely ships to those harnesses. - Does it hand-roll CC registry state directly? Writing
known_marketplaces.jsonorinstalled_plugins.jsonby hand is the exact anti-pattern agentgear removes: the CLI is the only supported writer. Migrating that is a correctness upgrade, not just a line cut.
greenfield: minimal setup
The smallest working host is Claude-only. Four things (shapes from examples/hello-mcp):
Cargo.toml: agentgear as both a normal and a build dependency. Default features (derive+claude+embed) cover a Claude-only host:[dependencies] agentgear = "0.1" [build-dependencies] agentgear = "0.1"build.rs: one line. It readsplugin.json, guards the version, and (withembed) compresses the tree into the binary:
A missingfn main() { agentgear::build::assert_plugin_version(); }build.rsis a compile error, not a silent loss (the derive checks for its marker).- the derive struct, in the lib (not just
main.rs) so tests can read the metadata without spawning the binary:use agentgear::PluginHost; #[derive(PluginHost)] #[plugin(name = "my-plugin")] pub struct MyPlugin; - the
plugin/tree, next toCargo.toml. The only required file isplugin/.claude-plugin/plugin.json; itsnamemust equal the derive'sname, itsversionmust equalCARGO_PKG_VERSION, andauthoris required (it becomes the marketplace owner).
Then wire the binary's own subcommands to the lifecycle methods (setup → install, uninstall, doctor, and for a fuller surface update, self-heal, check-restart). Point the plugin's SessionStart hook at self_heal, gated as let session = agentgear::SessionSource::from_stdin(); if MyPlugin::heal_needed_report(session)?.needed() { MyPlugin::self_heal(session)?; } (Claude Code pipes the SessionStart payload on stdin; read it once): the pre-check reads files and spawns no CLI, so a healthy claude install skips the heal's claude calls. Point UserPromptSubmit at restart_pending().
The full attribute table, the six-subcommand main.rs, and the tree rules are in
wiki/Getting-Started.md and wiki/Plugin-Tree.md. Do not restate them here; read them.
brownfield: migrating a hand-rolled installer
Adopt the derive first (greenfield steps), get one green setup / doctor, then delete the
plumbing it replaces. Delete in this order, verifying after each:
| hand-rolled thing | replaced by |
|---|---|
marketplace-register + plugin-install code (shell or Rust), incl. any known_marketplaces.json write |
install(Scope::User, Source::Embedded) |
direct claude plugin ... shell calls / a custom CLI wrapper |
agentgear's ClaudeCli (locate, env-scrub, non-interactive, tolerant --json); no host code shells out to claude |
a committed marketplace.json |
generated into the versioned dir at materialize; never ship one |
| a per-client config-merge engine (per-harness JSON/TOML/YAML writers, "which client do I support" descriptor files) | the built-in backends + confedit's atomic read-modify-write; name harnesses in agents = [...] instead of writing translators |
| a hand-rolled tree materialize / diff-copy | agentgear's materialize (tree hashing, atomic versioned-dir flip) |
manual SessionStart self-heal logic |
point the existing hook at self_heal(session), gated on heal_needed_report(session)?.needed() — read the payload once into session (let session = agentgear::SessionSource::from_stdin();) |
| a hand-maintained CC-version floor check | agentgear gates on claude --version before any mutating call |
a hand-written statusLine writer in ~/.claude/settings.json (refuse/force flags on a foreign value) |
delete it; agentgear writes no status-line slot anymore — a host ships a statusline print subcommand and the user wires it manually |
One real migration deleted ~1,100 net lines (20 per-client descriptor files plus a parse-and-merge engine plus its tests), replaced by ~160 lines of CLI glue. That commit is the reference for scope.
Grep the tree afterward for the deleted symbols and any surviving Command::new("claude") /
known_marketplaces / marketplace.json reference; a mechanical delete leaves stragglers.
multi-harness
agents = ["claude", "codex", "opencode", ...]on the derive sets the fan-out list every lifecycle op walks. The 25 valid ids (closed list, unknown id = compile error) are:claude,codex,opencode,gemini,cursor,cline,devin,qwen-code,copilot-cli,vscode-copilot,jetbrains-copilot,kimi,kiro,zed,omp,openclaw,kilo,antigravity,antigravity-cli,pi,goose,amp,crush,droid,augment.- Each non-CC backend is a cargo feature named after its id (dashes kept). List every backend
you name in
agentsunderfeatures, or useall-agents:
A backend named inagentgear = { version = "0.1", features = ["codex", "opencode", "gemini"] }agentswhose feature is off is a compile error in the host crate, with the exactfeatures = [...]fix in the message.claudeis always on. install_into(scope, source, &["codex"])narrows a single run to a subset ofAGENTSat runtime (the--agent <id>pattern).backend_for(id)resolves one id to its backend for a status/picker view.examples/multi-installeris the reference.${AGENTGEAR_CLIENT}expands to each harness's own id (claude,codex, …) in a hook'scommandand an MCP server'scommand/args;claudeandcopilot-cliexpand it across the whole materialized tree. Migrate any baked-in--client claude-codeto the token: the literal rides through every backend unchanged and evaluates true on all of them, so a hook binary that branches on its caller sees the wrong harness. Unlike${CLAUDE_PLUGIN_ROOT}(skipped, below), this token is expanded, so a command carrying it stays portable.
Per-harness fidelity (what each backend translates, what it skips and why) is in wiki/Agent-Backends.md, wiki/Harness-Comparison.md and the wiki/Capability-*.md pages. Read them before promising a surface reaches a backend.
what does NOT migrate yet (gap blockers)
Check these against the target plugin before promising a full migration.
- statusLine is no longer written by agentgear at all; any settings key is unmodeled. The
automatic slot wiring (declaration, five slot backends, stash-and-restore) is retired: a host
ships a
statuslineprint subcommand and the user wires it manually. Any settings key outside the plugin tree is unmodeled: the components IR carries five surfaces (mcp servers, hooks, commands, agents, skills) and nothing else reaches a harness's own settings file. - codex
notifyhooks / opencode hooks. agentgear's codex backend writeshooks.json, which stays inert until the user trusts it via codex's/hooksTUI; opencode has no declarative hook surface at all (in-process JS/TS plugin only). A plugin relying on either cannot fully migrate its hook path yet. ${CLAUDE_PLUGIN_ROOT}in an mcp/hook command. Every non-CC backend silently skips a command carrying that token (it only expands inside CC). Use bare executable names so the surface survives translation. Watch for thecargo:warningat build and doctor's "no portable ... to register" line.
verify
setupthendoctoron a scratchHOMEinstall the plugin and report healthy;uninstallstrips exactly what was written.- The hand-rolled plumbing named in the migration table is gone (grep the deleted symbols).
- A
plugin.json/Cargo.tomlversion mismatch fails the build (the guard, not a runtime error). - For a multi-harness host, install into a scratch profile for each named backend and confirm its
native config file carries the plugin, gated on
detect(). - Hermetic-test discipline (env overrides to clear, why
claude/copilot-clineed an#[ignore]d real-CLI run) is inwiki/Testing-Your-Host.md.
reference map
| need | read |
|---|---|
every #[plugin(...)] attr, defaults, the tree rules |
wiki/Getting-Started.md, wiki/Plugin-Tree.md |
lifecycle method signatures, Scope, Source, reports |
wiki/Types-and-Errors.md |
| which backend translates what, event maps, skips | wiki/Agent-Backends.md, wiki/Harness-Comparison.md, wiki/Capability-*.md |
| test harness rules | wiki/Testing-Your-Host.md |