@gobing-ai/superskill 0.1.4 → 0.1.6

package/README.md

@@ -15,6 +15,9 @@ Coding agents (Claude Code, Codex, Pi, OpenCode, Antigravity, Hermes, omp) each
 
 ```bash
 npm i -g @gobing-ai/superskill
+
+# or go with bun
+bun add -g @gobing-ai/superskill
 ```
 
 From source (contributors):
@@ -128,21 +131,79 @@ The CLI never scores or generates inline. Quality operations drive four personas
 
 Version-aware trends partition by `rubric_version`, preventing false regression signals when rubrics are updated.
 
-## Supported targets
+## Proper Location for Coding Agents
+
+Each coding agent stores skills, slash commands, subagents, and hooks in different directories. This table is the single source of truth for where `superskill install` writes each entity type per target — verified against each agent's source code (`vendors/`).
+
+### Entity locations — global (user-level, `~`)
+
+| Agent | Skills | Slash Commands | Subagents | Hooks |
+|-------|--------|---------------|-----------|-------|
+| **Claude Code** | `~/.claude/plugins/<name>/skills/` | `~/.claude/plugins/<name>/commands/` | `~/.claude/plugins/<name>/agents/` | `~/.claude/plugins/<name>/hooks/hooks.json` |
+| **Codex** | `~/.agents/skills/` | `~/.codex/prompts/` | `~/.codex/agents/` | — |
+| **Pi** | `~/.pi/agent/skills/` ¹ | `~/.pi/agent/prompts/` | `~/.pi/agent/agents/` ² | extensions ³ |
+| **omp** | `~/.omp/agent/skills/` | `~/.omp/agent/commands/` | `~/.omp/agent/agents/` ² | extensions ³ |
+| **OpenCode** | `~/.opencode/skills/` | `~/.config/opencode/commands/` | `~/.config/opencode/agents/` | — |
+| **Antigravity IDE** | `~/.gemini/config/skills/` | `~/.gemini/antigravity/global_workflows/` | — | — |
+| **Antigravity CLI** | `~/.gemini/antigravity-cli/skills/` | — | — | — |
+| **Hermes** | `~/.hermes/skills/` | config.yaml ⁴ | — ⁵ | `~/.hermes/hooks/<name>/HOOK.yaml` |
+| **OpenClaw** | `~/.openclaw/plugin-skills/` | — ⁶ | — ⁷ | webhooks ⁸ |
+
+### Entity locations — project-level (relative to workspace root)
+
+| Agent | Skills | Slash Commands | Subagents | Hooks |
+|-------|--------|---------------|-----------|-------|
+| **Claude Code** | `.claude/skills/` | `.claude/commands/` | `.claude/agents/` | `.claude/hooks/hooks.json` |
+| **Codex** | `.agents/skills/` | `.codex/prompts/` | `.codex/agents/` | — |
+| **Pi** | `.pi/skills/` | `.pi/prompts/` | `.pi/agents/` ² | `.pi/extensions/` |
+| **omp** | `.omp/skills/` | `.omp/commands/` | `.omp/agents/` ² | `.omp/hooks/` / `.omp/extensions/` |
+| **OpenCode** | `.opencode/skills/` | `.opencode/commands/` | `.opencode/agents/` | — |
+| **Antigravity IDE** | `.agents/skills/` | `.agents/workflows/` | — | — |
+| **Antigravity CLI** | `.agents/skills/` | — | — | — |
+| **Hermes** | `.hermes/skills/` | config.yaml ⁴ | — ⁵ | `.hermes/hooks/<name>/` |
+| **OpenClaw** | `skills/` | — ⁶ | — ⁷ | webhooks ⁸ |
+
+¹ Pi also reads `~/.agents/skills/` (Codex interop). omp reads from multiple agent directories (Claude Code, Codex, Gemini, OpenCode, etc.).
+
+² Subagents require an extension to be loaded (not built-in). Pi: `subagent` example extension. omp: `omp agents unpack` command.
+
+³ Pi and omp replaced legacy hooks with an **Extensions** system (TypeScript event handlers at `~/.pi/agent/extensions/` / `~/.omp/agent/extensions/`). Legacy hook dirs: `.omp/hooks/pre|post/*.ts`.
 
-| Target | Engine | Output location |
-|--------|--------|-----------------|
-| `claude` | Direct `claude plugin install` | Claude Code marketplace |
-| `codex` | rulesync | `~/.agents/skills/` |
-| `pi` | rulesync + superskill hook shim | Pi native format |
-| `omp` | superskill copy (via `pi` surrogate) | `~/.omp/agent/skills/` |
-| `opencode` | rulesync | `~/.agents/skills/` |
-| `antigravity-cli` | rulesync | `~/.gemini/antigravity-cli/skills/` |
-| `antigravity-ide` | rulesync | `~/.gemini/config/skills/` |
-| `hermes` | superskill copy (via `opencode` surrogate) | `~/.hermes/skills/` |
+⁴ Hermes slash commands: built-in `CommandDef` entries OR user-defined `quick_commands:` in `~/.hermes/config.yaml`. Skills auto-register as `/<skill-name>` — best path.
+
+⁵ Hermes spawns subagents dynamically via `delegate_task` tool; no persistent subagent directory.
+
+⁶ OpenClaw auto-discovers slash commands from skill directories as `/<skill-name>`. No separate commands directory.
+
+⁷ OpenClaw agents are configured in YAML (`agents.list`), not as files in a directory.
+
+⁸ OpenClaw hooks are inbound HTTP webhooks (`hooks.path`, `hooks.transformsDir`) — not coding-agent event hooks. No hook file installation needed.
 
 Since ts-ai-runner 0.3.21, `omp`, `hermes`, and `antigravity-cli` are canonical `AgentName` values — slash-command dialect translation maps 1:1. Only `antigravity-ide` still bridges through `opencode`.
 
+### How superskill installs
+
+| Agent | Engine | Notes |
+|-------|--------|-------|
+| **Claude Code** | `claude plugin marketplace add` + `claude plugin install` | Native plugin system — handles all entity types automatically |
+| **Codex** | rulesync | `codex` → `codexcli` |
+| **Pi** | rulesync + superskill shim | Subagents adapted as Skills 2.0 skill directories; Pi native agents written directly to `~/.pi/agent/agents/` |
+| **omp** | rulesync + superskill shim | `omp` → `pi` surrogate for rulesync, then copy to `~/.omp/`; omp also reads from other agent dirs |
+| **OpenCode** | rulesync | `opencode` → `opencode` |
+| **Antigravity IDE** | rulesync | `antigravity-ide` → `antigravity-ide` |
+| **Antigravity CLI** | rulesync | `antigravity-cli` → `antigravity-cli`; commands/subagents not supported by rulesync for this target |
+| **Hermes** | rulesync + superskill shim | `hermes` → `opencode` surrogate for rulesync, then copy to `~/.hermes/`; hooks format is HOOK.yaml not hooks.json |
+| **OpenClaw** | implicit (via `~/.agents/skills/`) | Reads skills from `~/.agents/skills/` (shared root with codex/opencode in global mode). No dedicated dispatch needed. |
+
+### Known gaps
+
+| Gap | Status |
+|-----|--------|
+| **antigravity-cli** commands/subagents | Rulesync doesn't support `antigravity-cli` for commands/subagents (only `antigravity` project-level). |
+| **Hermes hooks format** | Superskill writes `hooks.json`; Hermes expects `~/.hermes/hooks/<name>/HOOK.yaml` + `handler.py`. |
+| **Hermes commands** | No `commands/` directory. Install commands as skills for slash-command auto-discovery. |
+| **Pi/omp hooks → extensions** | Legacy pi-hooks shim should migrate to the Extensions format. |
+| **OpenClaw agents/hooks** | OpenClaw reads skills from `~/.agents/skills/` (implicitly covered). Dedicated agent YAML config and webhook-based hooks are not managed by superskill. |
 ## Bundled `cc` plugin
 
 superskill ships with a Claude Code plugin at [`plugins/cc/`](plugins/cc/) (marketplace name: `cc`, version `0.1.1`) that demonstrates the full authoring lifecycle and provides the meta-agent skills the expert personas reference:
@@ -155,7 +216,7 @@ superskill ships with a Claude Code plugin at [`plugins/cc/`](plugins/cc/) (mark
 | **hooks** | 1 | `Stop` hook running the anti-hallucination guard |
 | **scripts** | 3 | `ah_guard.ts`, `validate_response.ts`, `logger.ts` — deterministic enforcement for the anti-hallucination protocol |
 
-The plugin follows a three-tier delegation pattern: **Commands/Agents → Skills → `superskill` CLI**. See [`plugins/cc/README.md`](plugins/cc/README.md) for the full entity design and relationship diagram.
+The plugin follows a three-tier delegation pattern: **Commands/Agents → Skills → `superskill` CLI**. For non-Claude targets, `superskill install` adapts commands and subagents as Skills 2.0 skill directories (`pipeline/adapt-command.ts`, `pipeline/adapt-subagent.ts`) so every target receives a uniform skill-based distribution. See [`plugins/cc/README.md`](plugins/cc/README.md) for the full entity design and relationship diagram.
 
 ## Development