From a598aab8d6d5ce011cefd26ad517f4e5df184ff7 Mon Sep 17 00:00:00 2001 From: Santhi Prakash Date: Tue, 15 Sep 2026 19:21:06 +0000 Subject: [PATCH] fix(hooks): stop auto-injecting the meta-skill on SessionStart (#569) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plugin's SessionStart hook injected using-agent-skills/SKILL.md as additionalContext on every session. Claude Code already discovers and routes skills from their descriptions, so the hook stacks a second router on the native one — the pattern docs/getting-started.md warns against ("That creates two routers for the same task"), measured at ~3.5k wasted cache-creation tokens per session in #569. Delete hooks/hooks.json (the registration; the plugin now ships no hooks) and keep hooks/session-start.sh as a standalone script for hosts without native skill routing, matching the fix shape suggested in the issue. Update the hook header, CONTRIBUTING.md, codex-setup.md, and gemini-cli-setup.md to match. --- CONTRIBUTING.md | 2 +- docs/codex-setup.md | 2 +- docs/gemini-cli-setup.md | 2 +- hooks/hooks.json | 14 -------------- hooks/session-start.sh | 7 ++++++- 5 files changed, 9 insertions(+), 18 deletions(-) delete mode 100644 hooks/hooks.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f08c85ee..91a0269f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,7 +81,7 @@ We don't accept translations of the documentation (README, `docs/`) or of skills ## Testing Hooks -The session-start hook (`hooks/session-start.sh`) injects the `using-agent-skills` meta-skill into every new Claude Code session. A regression test at `hooks/session-start-test.sh` validates the hook's JSON payload — both when `jq` is available and when it isn't. +The session-start script (`hooks/session-start.sh`) injects the `using-agent-skills` meta-skill when wired into a host's `SessionStart` hook. The Claude Code plugin does not register it — Claude Code routes skills natively, and always-on injection would create two routers for the same task (see [docs/getting-started.md](docs/getting-started.md)); the script remains for hosts without native skill routing. A regression test at `hooks/session-start-test.sh` validates the script's JSON payload — both when `jq` is available and when it isn't. Run it before opening any PR that touches: diff --git a/docs/codex-setup.md b/docs/codex-setup.md index 51a71e56..25e25e0d 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -32,4 +32,4 @@ After install, invoke a skill in Codex chat with `@` (e.g. `@spec-driven-develop - `.agents/plugins/marketplace.json` — marketplace entry declaring the repo root (`./`) as the plugin source. - `skills//SKILL.md` — unchanged. Codex and Claude Code share the same `name` + `description` frontmatter format, so one file serves both platforms. -Slash commands in `.claude/commands/`, personas in `agents/`, and the lifecycle hook under `hooks/` stay Claude Code-specific. On Codex, invoke the underlying skill directly instead of the slash command (e.g. `@spec-driven-development` instead of `/spec`). +Slash commands in `.claude/commands/` and personas in `agents/` stay Claude Code-specific. The `SessionStart` script under `hooks/` is a standalone helper for hosts without native skill routing and is not wired by either plugin. On Codex, invoke the underlying skill directly instead of the slash command (e.g. `@spec-driven-development` instead of `/spec`). diff --git a/docs/gemini-cli-setup.md b/docs/gemini-cli-setup.md index 4722488a..8b13aa6b 100644 --- a/docs/gemini-cli-setup.md +++ b/docs/gemini-cli-setup.md @@ -93,7 +93,7 @@ To enable these, ensure you have the relevant MCP extensions installed in your G Gemini CLI supports session lifecycle hooks. You can use these to automatically inject context or run validation scripts at the start of a session. -To replicate the `agent-skills` experience from other tools, you can configure a `SessionStart` hook that reminds you of the available skills or loads a meta-skill. +To replicate the `agent-skills` experience from other tools, you can configure a `SessionStart` hook that reminds you of the available skills or loads a meta-skill. `hooks/session-start.sh` in this repo is a ready-made script for that: it prints the `using-agent-skills` meta-skill as a standard `SessionStart` JSON envelope on stdout. ### Explicit Context Loading diff --git a/hooks/hooks.json b/hooks/hooks.json deleted file mode 100644 index 5e57bf8d..00000000 --- a/hooks/hooks.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "hooks": { - "SessionStart": [ - { - "hooks": [ - { - "type": "command", - "command": "SCRIPT=\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"; [ -f \"$SCRIPT\" ] || SCRIPT=\"${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh\"; [ -f \"$SCRIPT\" ]&& bash \"$SCRIPT\" || true" - } - ] - } - ] - } -} diff --git a/hooks/session-start.sh b/hooks/session-start.sh index 8a91a994..cf93e771 100755 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -1,6 +1,11 @@ #!/bin/bash # agent-skills session start hook -# Injects the using-agent-skills meta-skill into every new session +# Injects the using-agent-skills meta-skill into a new session. +# +# Not wired by the plugin: hosts that already route skills from their +# descriptions (Claude Code, Codex CLI) would run a second router on top of +# the native one — see docs/getting-started.md. Wire this script into a +# SessionStart hook only on hosts without native skill routing. # # Every output path must emit the standard SessionStart envelope # {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "..."}}