@softspark/ai-toolkit 4.3.3 → 4.4.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.4.0 - native editor skill pointers and hook governance hardening (2026-05-25)
+
+Minor release. Adds native skill pointer generation for more editor surfaces and hardens search-first governance so quiet hooks still inject model context without noisy transcript output.
+
+### Added
+
+- **Native editor skill pointers** - Added Cursor, Windsurf, and Cline skill pointer generators so supported editors can discover the ai-toolkit skill catalog through their native skill directories.
+- **Shared skill pointer builder** - Added `scripts/skill_pointer.py` to keep generated skill pointer metadata consistent across editor-specific generators.
+- **Release coverage** - Added generator and hook tests covering the new skill pointer outputs, quiet JSON `UserPromptSubmit` context, and noisy Codex search-first log fallback.
+
+### Changed
+
+- **Editor registry and install flow** - Updated supported-tool metadata and install behavior for Cursor, Windsurf, and Cline native skill pointer targets.
+- **Codex hook generation** - `scripts/generate_codex_hooks.py` now emits quiet JSON context for `user-prompt-submit.sh`, matching Claude Code's installed hook behavior.
+- **Hook runtime documentation** - Updated the hooks catalog, Codex compatibility notes, global install model, supported tools registry, and maintenance SOP with the new runtime behavior.
+
+### Fixed
+
+- **Quiet hook context injection** - `_hook-io.sh` now lets `AI_TOOLKIT_HOOK_FORMAT=json` emit `hookSpecificOutput.additionalContext` even when `AI_TOOLKIT_HOOK_QUIET=1` is set.
+- **Search-first false positives in Codex** - `stop-search-check.sh` now scans a larger recent Codex log window and recognizes both `ToolCall: mcp__...__smart_query` and `tool.name="smart_query"` log shapes.
+- **Installed runtime drift** - Claude and Codex hook manifests now install `UserPromptSubmit` with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json`.
+
+### Ecosystem
+
+- **Snapshot refresh** - Refreshed the ecosystem doctor snapshot after upstream documentation/content drift review and generator updates.
+
+### Verification
+
+- `bats tests/test_generators.bats`
+- `bats tests/test_cli.bats`
+- `bats tests/test_skills_native.bats tests/test_native_surfaces.bats`
+- `bats tests/test_hooks.bats tests/test_search_first_flow.bats`
+- `bats tests/test_install.bats tests/test_codex.bats`
+- `python3 scripts/validate.py --strict`
+- `git diff --check`
+
+---
+
 ## v4.3.3 - silent hook context roll-forward (2026-05-21)
 
 Patch release. Rolls forward the quiet-hook release with a stricter default: non-blocking plain-text hook context is now silent even when a runtime uses a stale or manually copied command without `AI_TOOLKIT_HOOK_QUIET=1`.

package/README.md

@@ -6,16 +6,16 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-107-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1144%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1149%20passing-success)](tests/)
 
-## What's New in v4.3.3
+## What's New in v4.4.0
 
-Patch release. Rolls forward quiet hook handling so informational hook context stays out of the visible chat window even with stale or manually copied hook commands.
+Minor release. Adds native skill pointers for more editor surfaces and hardens quiet hook governance for Claude and Codex.
 
-- **Silent hook context by default**: `SessionStart`, `UserPromptSubmit`, and other non-blocking plain-text context output now require `AI_TOOLKIT_HOOK_VERBOSE=1`.
-- **Side effects preserved**: search-first flags, session-state reset, stale-flag cleanup, and blocking decisions still run without printing reminder text.
-- **Runtime refresh applied**: installed hook scripts and Codex/Claude hook config pick up the silent default.
-- **Test coverage updated**: hook tests now cover default silence and verbose opt-in, bringing the suite to 1144 tests.
+- **Native editor skills**: Cursor, Windsurf, and Cline now get generated skill pointer catalogs alongside existing rule surfaces.
+- **Quiet JSON governance**: `UserPromptSubmit` keeps output quiet while still injecting `additionalContext` for search-first and workflow reminders.
+- **Codex search-first hardening**: Stop enforcement recognizes current Codex MCP log shapes and tolerates noisy skill-loader output.
+- **Release coverage updated**: generator, install, Codex, hook, and search-first tests cover the new behavior; suite count is 1149 tests.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -101,11 +101,11 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Platform | Config Files | Scope |
 |----------|-------------|-------|
 | Claude Code | `~/.claude/` | global |
-| Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` | project (`~/.cursor/mcp.json` for MCP only) |
-| Windsurf | `~/.codeium/.../global_rules.md` + `.windsurf/rules/*.md` | global + project |
+| Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` + `.cursor/skills/*` | project (`~/.cursor/mcp.json` for MCP only) |
+| Windsurf | `~/.codeium/.../global_rules.md` + `~/.codeium/windsurf/skills/*` + `.windsurf/rules/*.md` | global + project |
 | Gemini CLI | `~/.gemini/GEMINI.md` | global |
 | GitHub Copilot | `.github/copilot-instructions.md` | project |
-| Cline | `~/Documents/Cline/Rules/*.md` + `.clinerules/*.md` | global + project |
+| Cline | `~/.cline/rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | global + project |
 | Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | global rules + project |
 | Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | global + project |
 | Augment | `~/.augment/rules/*.md` + `.augment/rules/ai-toolkit-*.md` | global + project |
@@ -148,7 +148,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1144 tests)
+├── tests/               # Bats test suite (1149 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.3.3",
+  "version": "4.4.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -356,7 +356,7 @@ Lead Session (You)
 Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.
 
 ### Codex Integration
-Codex receives `AGENTS.md`, `.agents/rules/*.md`, optional `.agents/skills/*`, and `.codex/hooks.json`. `generate_codex_hooks.py` emits only Codex-supported lifecycle events and prefixes commands with `AI_TOOLKIT_HOOK_QUIET=1`, so informational hook context is not shown at session start or prompt submit while side effects and blocking Stop decisions still run. Claude's bundled `UserPromptSubmit` hook also runs in quiet mode for the same reason.
+Codex receives `AGENTS.md`, `.agents/rules/*.md`, optional `.agents/skills/*`, and `.codex/hooks.json`. `generate_codex_hooks.py` emits only Codex-supported lifecycle events and prefixes commands with `AI_TOOLKIT_HOOK_QUIET=1`, so informational hook output is not shown at session start or prompt submit while side effects and blocking Stop decisions still run. The `UserPromptSubmit` governance hook also sets `AI_TOOLKIT_HOOK_FORMAT=json` so proactive `additionalContext` reaches the model quietly. Claude's bundled `UserPromptSubmit` hook uses the same quiet JSON context path.
 
 ### opencode Integration (v2.5.0+)
 opencode is the 11th supported editor. Five generators handle its integration surface:

package/app/hooks/_hook-io.sh

@@ -58,12 +58,11 @@ hook_new_content() {
 
 hook_emit_context() {
     local message="$1"
-    if [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ]; then
-        return 0
-    fi
     if [ "${AI_TOOLKIT_HOOK_FORMAT:-}" = "json" ]; then
         jq -nc --arg msg "$message" \
             '{"hookSpecificOutput":{"additionalContext":$msg},"suppressOutput":true}'
+    elif [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ]; then
+        return 0
     elif [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" = "1" ]; then
         printf '%s\n' "$message"
     fi

package/app/hooks/stop-search-check.sh

@@ -59,7 +59,10 @@ try:
     with log_path.open("rb") as handle:
         handle.seek(0, 2)
         size = handle.tell()
-        handle.seek(max(0, size - 2_000_000))
+        # Codex logs can be noisy between the search call and Stop hook
+        # execution, especially when skill loading emits repeated warnings.
+        # Keep this bounded, but large enough to avoid false positives.
+        handle.seek(max(0, size - 20_000_000))
         lines = handle.read().decode("utf-8", errors="replace").splitlines()
 except OSError:
     sys.exit(1)

package/app/hooks.json

@@ -103,7 +103,7 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "AI_TOOLKIT_HOOK_QUIET=1 \"$HOME/.softspark/ai-toolkit/hooks/user-prompt-submit.sh\""
+                        "command": "AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json \"$HOME/.softspark/ai-toolkit/hooks/user-prompt-submit.sh\""
                     }
                 ]
             },

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-05-21T08:27:23Z",
+  "last_run": "2026-05-25T11:12:53Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,14 +24,21 @@
       }
     },
     "augment": {
-      "docs_hash": "8be23f4fb78816c3",
+      "docs_hash": "2546ce56fc2d92e4",
       "headings": [
+        "Admin",
+        "Auggie CLI",
         "Code",
+        "Cosmos",
         "Documentation Index",
+        "Getting Started",
         "Introduction",
+        "Models & Pricing",
         "On this page",
         "Other automation",
+        "Other clients",
         "Review",
+        "Troubleshooting",
         "\u200bAuggie CLI",
         "\u200bAutomate your SDLC",
         "\u200bCosmos",
@@ -58,7 +65,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "0518086bd4527849",
+      "docs_hash": "78dbdbf9b1b09fe8",
       "headings": [
         "Documentation Index",
         "On this page",
@@ -105,15 +112,20 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.146 (Claude Code)"
+      "version": "2.1.150 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "c2ce2443743365fa",
+      "docs_hash": "0d30b8f46cb45976",
       "headings": [
         "API Reference",
+        "Best Practices",
         "CLI",
         "Cline Overview",
+        "Configurations",
         "Documentation Index",
+        "Features",
+        "Getting Started",
+        "IDE Specific Features",
         "JetBrains Plugin",
         "Kanban",
         "Observability",
@@ -121,6 +133,8 @@
         "SDK",
         "Security & Governance",
         "Team Management",
+        "Troubleshooting",
+        "Usage",
         "VS Code Extension",
         "\u200bAgent Core (SDK)",
         "\u200bApplications",
@@ -142,7 +156,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "70f184b6cdd1f765",
+      "docs_hash": "8cad495445dd03e0",
       "headings": [
         "About",
         "Contributing",
@@ -161,7 +175,7 @@
         "Packages 0",
         "Provide feedback",
         "Quickstart",
-        "Releases 795",
+        "Releases 799",
         "Repository files navigation",
         "Resources",
         "Saved searches",
@@ -191,10 +205,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.132.0"
+      "version": "codex-cli 0.133.0"
     },
     "cursor": {
-      "docs_hash": "60edb30c9ddcdadd",
+      "docs_hash": "56c9209877480e01",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -210,7 +224,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "c6aab087667f7717",
+      "docs_hash": "6a47f9b11ff1527d",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -249,7 +263,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "ab274112faeec90f",
+      "docs_hash": "a5b81592ca646743",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
@@ -281,7 +295,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "2c48c702b9e592a7",
+      "docs_hash": "6f089d2c7caabceb",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -297,7 +311,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "5277673e235393f7",
+      "docs_hash": "74eb2d934df9b613",
       "headings": [
         "Add features",
         "Ask questions",
@@ -357,18 +371,23 @@
       }
     },
     "windsurf": {
-      "docs_hash": "fa29ba621f291d81",
+      "docs_hash": "eddf51fabbcaa0a3",
       "headings": [
+        "Accounts",
         "Advanced",
+        "Agent Command Center",
         "App Deploys",
         "Cascade",
         "Context Awareness",
         "Documentation Index",
+        "Editor",
         "MCP",
         "Memories",
         "On this page",
         "Recommended Plugins",
+        "Security",
         "Terminal",
+        "Troubleshooting",
         "Usage",
         "Welcome to Windsurf",
         "Workflows",
@@ -390,11 +409,13 @@
         "AGENTS.md": true,
         "Cascade": true,
         "MCP": true,
+        "SKILL.md": false,
         "always_on": false,
         "glob": true,
         "hooks": true,
         "memories": true,
         "model_decision": false,
+        "skills": true,
         "windsurfrules": false,
         "workflows": true
       }

package/kb/procedures/maintenance-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Claude Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "3.0.0"
+version: "3.0.1"
 created: "2026-03-23"
-last_updated: "2026-04-23"
+last_updated: "2026-05-25"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -34,7 +34,7 @@ ai-toolkit install --local --editors all                  # all supported editor
 ai-toolkit install --local --editors cursor,aider         # specific editors only
 ```
 
-Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`, `codex`.
+Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`, `codex`, `gemini`, `opencode`.
 
 To restrict which language rules are injected, use `--lang`:
 
@@ -202,6 +202,43 @@ Manual path:
 
 Use `PreToolUse` for blocking validations, `PostToolUse` for non-blocking feedback, `UserPromptSubmit` for prompt governance, and `PreCompact` / `SessionEnd` for context preservation and handoff.
 
+## Troubleshooting Rule Enforcement in Claude Code
+
+Use this when Claude appears to ignore `CLAUDE.md`, `.claude/rules/*.md`, output styles, or search-first rules.
+
+1. **Check current Claude docs first.** Confirm the live contract for memory, settings, output styles, and hooks:
+   - `https://code.claude.com/docs/en/memory`
+   - `https://code.claude.com/docs/en/settings`
+   - `https://code.claude.com/docs/en/output-styles`
+   - `https://code.claude.com/docs/en/hooks`
+2. **Verify instruction loading.** Run `/memory` in Claude Code and confirm the expected `CLAUDE.md`, `CLAUDE.local.md`, and `.claude/rules/*.md` files are listed. Remember that Claude Code reads `CLAUDE.md`, not `AGENTS.md`, unless `CLAUDE.md` imports it.
+3. **Verify the active output style.** Check `.claude/settings.local.json` or `/config`. Output style changes apply after `/clear` or a new session.
+4. **Inspect installed hooks.** Ensure `~/.claude/settings.json` contains the ai-toolkit `UserPromptSubmit` and `Stop` entries. The governance hook must run with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json` so it injects `additionalContext` without noisy transcript output.
+5. **Reproduce the hook path directly.**
+   ```bash
+   printf '{"session_id":"debug","prompt":"debug this technical rule issue"}' \
+     | AI_TOOLKIT_SEARCH_FIRST=strict AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json \
+       ~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh
+   ```
+   The output must be valid JSON with `hookSpecificOutput.additionalContext`.
+6. **Check corrective enforcement.** If the assistant still skips required research, `stop-search-check.sh` should block Stop with the search-first message. If it does not, inspect `~/.softspark/ai-toolkit/state/search-required-*.flag` and the Codex/Claude transcript logs.
+7. **Repair drift.** Run:
+   ```bash
+   ai-toolkit update --only hooks
+   python3 scripts/ecosystem_doctor.py --tool claude-code --format text
+   scripts/validate.py
+   ```
+
+## Verification
+
+After changing rule-enforcement behavior, run at minimum:
+
+```bash
+bats tests/test_hooks.bats tests/test_search_first_flow.bats
+bats tests/test_install.bats tests/test_codex.bats
+python3 scripts/validate.py --strict
+```
+
 ## Managing Plugins
 
 ```bash

package/kb/reference/architecture-overview.md

@@ -105,11 +105,11 @@ Machine (global)                              Project (local)
 **`ai-toolkit update`** — re-apply after `npm install -g @softspark/ai-toolkit@latest` or after `add-rule` / `remove-rule`. Same as `install` but semantically correct for update flows.
 
 **`ai-toolkit install --local`** — run per project. Always installs Claude Code configs (CLAUDE.md, settings.local.json, constitution.md, language rules). Editor configs are opt-in via `--editors`:
-- `--editors all` — install all 9 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex)
+- `--editors all` — install all 11 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex, Gemini, opencode)
 - `--editors cursor,aider` — install only selected editors
 - (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
 
-Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Codex local install additionally generates `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
+Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
 
 If a project already has `.mcp.json`, local install mirrors its `mcpServers` entries into `.claude/settings.local.json` plus any selected editors with project-scoped native MCP files (`.cursor/mcp.json`, `.github/mcp.json`).
 

package/kb/reference/codex-cli-compatibility.md

@@ -110,10 +110,12 @@ This means Claude-only events such as `TaskCompleted`, `TeammateIdle`,
 `~/.codex/hooks.json` (global layer). Non-Codex events are silently skipped.
 `remove-hook` cleans both Claude and Codex targets.
 
-Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. This keeps
-non-blocking reminders and startup context out of the visible Codex hook output
-while preserving hook side effects and blocking decisions such as search-first
-Stop enforcement.
+Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. The
+`UserPromptSubmit` governance hook additionally sets `AI_TOOLKIT_HOOK_FORMAT=json`
+so it can pass quiet `additionalContext` before the model responds. This keeps
+non-blocking reminders and startup context out of visible hook output while
+preserving hook side effects, proactive search-first context, and blocking
+decisions such as search-first Stop enforcement.
 
 Plain-text informational hook context is also silent by default in the shared
 hook helper. Set `AI_TOOLKIT_HOOK_VERBOSE=1` only when debugging hook output
@@ -133,6 +135,8 @@ Known limits:
   so `stop-search-check.sh` also checks `~/.codex/log/codex-tui.log` for
   `smart_query`, `hybrid_search_kb`, `crag_search`, `multi_hop_search`, and
   `verify_answer` calls after the search-first flag timestamp before blocking.
+  The scan is bounded to a recent log window, but sized to tolerate noisy Codex
+  skill-loader output between the search call and the Stop hook.
 
 These are runtime platform limits, not installation defects.
 

package/kb/reference/global-install-model.md

@@ -60,10 +60,10 @@ The `--profile` flag controls how much of each editor's native surface is activa
 `ai-toolkit install --editors <name>` can write global files only for editors
 with documented, file-based config surfaces:
 
-- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md`
+- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md`
 - `gemini`: `~/.gemini/GEMINI.md`
 - `augment`: `~/.augment/rules/ai-toolkit.md`
-- `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md`
+- `cline`: `~/.cline/rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
 - `roo`: `~/.roo/rules/ai-toolkit-*.md`
 - `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
 - `codex`: `~/AGENTS.md`, `~/.agents/rules/*`, `~/.agents/skills/*`, `~/.codex/hooks.json`

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.3"
+version: "1.5.5"
 created: "2026-03-27"
-last_updated: "2026-05-21"
+last_updated: "2026-05-25"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -112,11 +112,13 @@ and can provide a lightweight governance reminder: plan mode for architectural
 work, evidence-first debugging, KB-first research, and validation expectations.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`. The bundled `app/hooks.json`
-registers this command with `AI_TOOLKIT_HOOK_QUIET=1`, so it still arms or
-clears the per-session search-first flag but suppresses the informational
-reminder output. In plain-text mode, informational reminders are silent by
-default and require `AI_TOOLKIT_HOOK_VERBOSE=1`; JSON hook output remains
-available with `AI_TOOLKIT_HOOK_FORMAT=json`.
+registers this command with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json`.
+This keeps the hook visually quiet (`suppressOutput: true`) while still
+injecting `hookSpecificOutput.additionalContext` before Claude starts working.
+That context is the proactive half of search-first enforcement; the paired
+`stop-search-check.sh` remains the corrective half. In plain-text mode,
+informational reminders are silent by default and require
+`AI_TOOLKIT_HOOK_VERBOSE=1`.
 
 ### UserPromptSubmit (usage tracking) — `track-usage.sh`
 
@@ -393,7 +395,7 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 | Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
 | Fires | After any search-style tool call |
 
-**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Search provider detection parses actual MCP server names from `mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and permission allowlists do not count as providers. Together the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
+**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Search provider detection parses actual MCP server names from `mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and permission allowlists do not count as providers. Codex Stop enforcement also scans the recent `~/.codex/log/codex-tui.log` window for `ToolCall: mcp__...__smart_query` and `tool.name="smart_query"`-style entries because Codex MCP tool calls may not fire the shared `PostToolUse` tracker. Together the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
 
 Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -444,7 +446,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
 | `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
 | `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
-| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. Honors `AI_TOOLKIT_HOOK_QUIET=1` and `AI_TOOLKIT_HOOK_VERBOSE=1` for non-blocking context output. |
+| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. JSON context output takes precedence over `AI_TOOLKIT_HOOK_QUIET=1`, so quiet hooks can still emit `additionalContext` with `suppressOutput: true`; plain-text output requires `AI_TOOLKIT_HOOK_VERBOSE=1`. |
 | `app/hooks/_search-capability.sh` | Shared bash helper that enables search-first blocking only when RAG/Web is configured or strict mode is requested. |
 
 ## Runtime Profiles

package/kb/reference/supported-tools-registry.md

@@ -3,9 +3,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.2.1"
+version: "1.3.0"
 created: "2026-04-23"
-last_updated: "2026-04-28"
+last_updated: "2026-05-25"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -47,9 +47,9 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Docs | https://cursor.com/docs |
 | Changelog | https://cursor.com/changelog |
 | Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
-| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json` |
-| Compat read paths | `.claude/skills/`, `.claude/agents/`, `.agents/skills/` (Cursor cross-reads these so ai-toolkit's Claude/Codex installs work automatically) |
-| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (profile=full), `scripts/generate_cursor_agents.py` (profile=full) |
+| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `~/.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json` |
+| Compat read paths | `.agents/skills/`, `~/.agents/skills/`, `.claude/skills/`, `~/.claude/skills/`, `.codex/skills/`, `~/.codex/skills/` |
+| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (profile=full), `scripts/generate_cursor_agents.py` (profile=full), `scripts/generate_cursor_skills.py` (profile=full pointer) |
 | Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
 
 ### Windsurf
@@ -60,10 +60,10 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Docs | https://docs.windsurf.com |
 | Changelog | https://windsurf.com/changelog |
 | Stable docs mirror | https://docs.windsurf.com/llms.txt + per-page .md twins |
-| Config paths | `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `AGENTS.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/mcp_config.json` |
+| Config paths | `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `.windsurf/skills/*/SKILL.md`, `AGENTS.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/skills/*/SKILL.md`, `~/.codeium/windsurf/mcp_config.json` |
 | Compat read paths | `.agents/skills/`, `~/.agents/skills/`, (with Claude Code config-reading) `.claude/skills/`, `~/.claude/skills/` |
-| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full) |
-| Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, MCP, memories, hooks |
+| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full), `scripts/generate_windsurf_skills.py` (global + profile=full pointer) |
+| Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, skills, MCP, memories, hooks |
 | Activation modes emitted | always_on (agents/security/quality), glob (testing + language rules), model_decision (code-style/workflow) |
 
 ### GitHub Copilot
@@ -98,11 +98,11 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `cline` |
 | Docs | https://docs.cline.bot |
 | Release notes | https://github.com/cline/cline/releases |
-| Config paths | `.clinerules/*.md`, `.clinerules/workflows/*.md`, `.clinerules/hooks/`, `.cline/skills/`, `~/.cline/data/settings/cline_mcp_settings.json`, `~/Documents/Cline/Rules/` |
-| Our generators | `scripts/generate_cline.py`, `scripts/generate_cline_rules.py` |
+| Config paths | `.clinerules/*.md` (compat), `.clinerules/workflows/*.md` (compat workflows), `.cline/rules/*.md`, `.cline/hooks/`, `.cline/skills/*/SKILL.md`, `~/.cline/rules/*.md`, `~/.cline/hooks/`, `~/.cline/skills/*/SKILL.md`, `~/.cline/data/settings/cline_mcp_settings.json` |
+| Our generators | `scripts/generate_cline.py`, `scripts/generate_cline_rules.py`, `scripts/generate_cline_skills.py` |
 | Tracked capabilities | `clinerules`, Plan Mode, Act Mode, MCP, custom modes, workflows, hooks, skills, subagents, conditional rules |
-| Notes | Conditional rules (`paths:` YAML frontmatter) are emitted for testing and language-specific rules since 2026-04. Skills (`.cline/skills/`) and hooks (`.clinerules/hooks/`) remain experimental upstream and are not yet generated. |
-| Global install | `ai-toolkit install --editors cline` writes only documented global rules under `~/Documents/Cline/Rules/`; MCP remains managed by `ai-toolkit mcp install --editor cline`. |
+| Notes | Conditional rules (`paths:` YAML frontmatter) are emitted for testing and language-specific rules since 2026-04. Project rules still use `.clinerules/` for compatibility; the documented `~/.cline/rules/` path is used for global install. Skills are emitted as a pointer catalogue in `profile=full` and global installs. |
+| Global install | `ai-toolkit install --editors cline` writes documented global rules under `~/.cline/rules/` and a skill pointer under `~/.cline/skills/`; MCP remains managed by `ai-toolkit mcp install --editor cline`. |
 
 ### Roo Code
 

package/llms-full.txt

@@ -4404,9 +4404,9 @@ title: "SOP: Claude Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "3.0.0"
+version: "3.0.1"
 created: "2026-03-23"
-last_updated: "2026-04-23"
+last_updated: "2026-05-25"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -4435,7 +4435,7 @@ ai-toolkit install --local --editors all                  # all supported editor
 ai-toolkit install --local --editors cursor,aider         # specific editors only
 ```
 
-Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`, `codex`.
+Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`, `codex`, `gemini`, `opencode`.
 
 To restrict which language rules are injected, use `--lang`:
 
@@ -4603,6 +4603,43 @@ Manual path:
 
 Use `PreToolUse` for blocking validations, `PostToolUse` for non-blocking feedback, `UserPromptSubmit` for prompt governance, and `PreCompact` / `SessionEnd` for context preservation and handoff.
 
+## Troubleshooting Rule Enforcement in Claude Code
+
+Use this when Claude appears to ignore `CLAUDE.md`, `.claude/rules/*.md`, output styles, or search-first rules.
+
+1. **Check current Claude docs first.** Confirm the live contract for memory, settings, output styles, and hooks:
+   - `https://code.claude.com/docs/en/memory`
+   - `https://code.claude.com/docs/en/settings`
+   - `https://code.claude.com/docs/en/output-styles`
+   - `https://code.claude.com/docs/en/hooks`
+2. **Verify instruction loading.** Run `/memory` in Claude Code and confirm the expected `CLAUDE.md`, `CLAUDE.local.md`, and `.claude/rules/*.md` files are listed. Remember that Claude Code reads `CLAUDE.md`, not `AGENTS.md`, unless `CLAUDE.md` imports it.
+3. **Verify the active output style.** Check `.claude/settings.local.json` or `/config`. Output style changes apply after `/clear` or a new session.
+4. **Inspect installed hooks.** Ensure `~/.claude/settings.json` contains the ai-toolkit `UserPromptSubmit` and `Stop` entries. The governance hook must run with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json` so it injects `additionalContext` without noisy transcript output.
+5. **Reproduce the hook path directly.**
+   ```bash
+   printf '{"session_id":"debug","prompt":"debug this technical rule issue"}' \
+     | AI_TOOLKIT_SEARCH_FIRST=strict AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json \
+       ~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh
+   ```
+   The output must be valid JSON with `hookSpecificOutput.additionalContext`.
+6. **Check corrective enforcement.** If the assistant still skips required research, `stop-search-check.sh` should block Stop with the search-first message. If it does not, inspect `~/.softspark/ai-toolkit/state/search-required-*.flag` and the Codex/Claude transcript logs.
+7. **Repair drift.** Run:
+   ```bash
+   ai-toolkit update --only hooks
+   python3 scripts/ecosystem_doctor.py --tool claude-code --format text
+   scripts/validate.py
+   ```
+
+## Verification
+
+After changing rule-enforcement behavior, run at minimum:
+
+```bash
+bats tests/test_hooks.bats tests/test_search_first_flow.bats
+bats tests/test_install.bats tests/test_codex.bats
+python3 scripts/validate.py --strict
+```
+
 ## Managing Plugins
 
 ```bash
@@ -6195,11 +6232,11 @@ Machine (global)                              Project (local)
 **`ai-toolkit update`** — re-apply after `npm install -g @softspark/ai-toolkit@latest` or after `add-rule` / `remove-rule`. Same as `install` but semantically correct for update flows.
 
 **`ai-toolkit install --local`** — run per project. Always installs Claude Code configs (CLAUDE.md, settings.local.json, constitution.md, language rules). Editor configs are opt-in via `--editors`:
-- `--editors all` — install all 9 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex)
+- `--editors all` — install all 11 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex, Gemini, opencode)
 - `--editors cursor,aider` — install only selected editors
 - (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
 
-Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Codex local install additionally generates `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
+Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
 
 If a project already has `.mcp.json`, local install mirrors its `mcpServers` entries into `.claude/settings.local.json` plus any selected editors with project-scoped native MCP files (`.cursor/mcp.json`, `.github/mcp.json`).
 
@@ -7035,10 +7072,12 @@ This means Claude-only events such as `TaskCompleted`, `TeammateIdle`,
 `~/.codex/hooks.json` (global layer). Non-Codex events are silently skipped.
 `remove-hook` cleans both Claude and Codex targets.
 
-Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. This keeps
-non-blocking reminders and startup context out of the visible Codex hook output
-while preserving hook side effects and blocking decisions such as search-first
-Stop enforcement.
+Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. The
+`UserPromptSubmit` governance hook additionally sets `AI_TOOLKIT_HOOK_FORMAT=json`
+so it can pass quiet `additionalContext` before the model responds. This keeps
+non-blocking reminders and startup context out of visible hook output while
+preserving hook side effects, proactive search-first context, and blocking
+decisions such as search-first Stop enforcement.
 
 Plain-text informational hook context is also silent by default in the shared
 hook helper. Set `AI_TOOLKIT_HOOK_VERBOSE=1` only when debugging hook output
@@ -7058,6 +7097,8 @@ Known limits:
   so `stop-search-check.sh` also checks `~/.codex/log/codex-tui.log` for
   `smart_query`, `hybrid_search_kb`, `crag_search`, `multi_hop_search`, and
   `verify_answer` calls after the search-first flag timestamp before blocking.
+  The scan is bounded to a recent log window, but sized to tolerate noisy Codex
+  skill-loader output between the search call and the Stop hook.
 
 These are runtime platform limits, not installation defects.
 
@@ -8533,10 +8574,10 @@ The `--profile` flag controls how much of each editor's native surface is activa
 `ai-toolkit install --editors <name>` can write global files only for editors
 with documented, file-based config surfaces:
 
-- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md`
+- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md`
 - `gemini`: `~/.gemini/GEMINI.md`
 - `augment`: `~/.augment/rules/ai-toolkit.md`
-- `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md`
+- `cline`: `~/.cline/rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
 - `roo`: `~/.roo/rules/ai-toolkit-*.md`
 - `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
 - `codex`: `~/AGENTS.md`, `~/.agents/rules/*`, `~/.agents/skills/*`, `~/.codex/hooks.json`
@@ -8839,9 +8880,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.3"
+version: "1.5.5"
 created: "2026-03-27"
-last_updated: "2026-05-21"
+last_updated: "2026-05-25"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -8948,11 +8989,13 @@ and can provide a lightweight governance reminder: plan mode for architectural
 work, evidence-first debugging, KB-first research, and validation expectations.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`. The bundled `app/hooks.json`
-registers this command with `AI_TOOLKIT_HOOK_QUIET=1`, so it still arms or
-clears the per-session search-first flag but suppresses the informational
-reminder output. In plain-text mode, informational reminders are silent by
-default and require `AI_TOOLKIT_HOOK_VERBOSE=1`; JSON hook output remains
-available with `AI_TOOLKIT_HOOK_FORMAT=json`.
+registers this command with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json`.
+This keeps the hook visually quiet (`suppressOutput: true`) while still
+injecting `hookSpecificOutput.additionalContext` before Claude starts working.
+That context is the proactive half of search-first enforcement; the paired
+`stop-search-check.sh` remains the corrective half. In plain-text mode,
+informational reminders are silent by default and require
+`AI_TOOLKIT_HOOK_VERBOSE=1`.
 
 ### UserPromptSubmit (usage tracking) — `track-usage.sh`
 
@@ -9229,7 +9272,7 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 | Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
 | Fires | After any search-style tool call |
 
-**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Search provider detection parses actual MCP server names from `mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and permission allowlists do not count as providers. Together the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
+**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Search provider detection parses actual MCP server names from `mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and permission allowlists do not count as providers. Codex Stop enforcement also scans the recent `~/.codex/log/codex-tui.log` window for `ToolCall: mcp__...__smart_query` and `tool.name="smart_query"`-style entries because Codex MCP tool calls may not fire the shared `PostToolUse` tracker. Together the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
 
 Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9280,7 +9323,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
 | `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
 | `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
-| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. Honors `AI_TOOLKIT_HOOK_QUIET=1` and `AI_TOOLKIT_HOOK_VERBOSE=1` for non-blocking context output. |
+| `app/hooks/_hook-io.sh` | Shared bash helper that normalizes hook payloads across Claude, Augment, Gemini, Windsurf, and Cursor-style JSON. JSON context output takes precedence over `AI_TOOLKIT_HOOK_QUIET=1`, so quiet hooks can still emit `additionalContext` with `suppressOutput: true`; plain-text output requires `AI_TOOLKIT_HOOK_VERBOSE=1`. |
 | `app/hooks/_search-capability.sh` | Shared bash helper that enables search-first blocking only when RAG/Web is configured or strict mode is requested. |
 
 ## Runtime Profiles
@@ -11671,9 +11714,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.2.1"
+version: "1.3.0"
 created: "2026-04-23"
-last_updated: "2026-04-28"
+last_updated: "2026-05-25"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -11715,9 +11758,9 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Docs | https://cursor.com/docs |
 | Changelog | https://cursor.com/changelog |
 | Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
-| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json` |
-| Compat read paths | `.claude/skills/`, `.claude/agents/`, `.agents/skills/` (Cursor cross-reads these so ai-toolkit's Claude/Codex installs work automatically) |
-| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (profile=full), `scripts/generate_cursor_agents.py` (profile=full) |
+| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `~/.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json` |
+| Compat read paths | `.agents/skills/`, `~/.agents/skills/`, `.claude/skills/`, `~/.claude/skills/`, `.codex/skills/`, `~/.codex/skills/` |
+| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (profile=full), `scripts/generate_cursor_agents.py` (profile=full), `scripts/generate_cursor_skills.py` (profile=full pointer) |
 | Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
 
 ### Windsurf
@@ -11728,10 +11771,10 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Docs | https://docs.windsurf.com |
 | Changelog | https://windsurf.com/changelog |
 | Stable docs mirror | https://docs.windsurf.com/llms.txt + per-page .md twins |
-| Config paths | `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `AGENTS.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/mcp_config.json` |
+| Config paths | `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `.windsurf/skills/*/SKILL.md`, `AGENTS.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/skills/*/SKILL.md`, `~/.codeium/windsurf/mcp_config.json` |
 | Compat read paths | `.agents/skills/`, `~/.agents/skills/`, (with Claude Code config-reading) `.claude/skills/`, `~/.claude/skills/` |
-| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full) |
-| Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, MCP, memories, hooks |
+| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full), `scripts/generate_windsurf_skills.py` (global + profile=full pointer) |
+| Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, skills, MCP, memories, hooks |
 | Activation modes emitted | always_on (agents/security/quality), glob (testing + language rules), model_decision (code-style/workflow) |
 
 ### GitHub Copilot
@@ -11766,11 +11809,11 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `cline` |
 | Docs | https://docs.cline.bot |
 | Release notes | https://github.com/cline/cline/releases |
-| Config paths | `.clinerules/*.md`, `.clinerules/workflows/*.md`, `.clinerules/hooks/`, `.cline/skills/`, `~/.cline/data/settings/cline_mcp_settings.json`, `~/Documents/Cline/Rules/` |
-| Our generators | `scripts/generate_cline.py`, `scripts/generate_cline_rules.py` |
+| Config paths | `.clinerules/*.md` (compat), `.clinerules/workflows/*.md` (compat workflows), `.cline/rules/*.md`, `.cline/hooks/`, `.cline/skills/*/SKILL.md`, `~/.cline/rules/*.md`, `~/.cline/hooks/`, `~/.cline/skills/*/SKILL.md`, `~/.cline/data/settings/cline_mcp_settings.json` |
+| Our generators | `scripts/generate_cline.py`, `scripts/generate_cline_rules.py`, `scripts/generate_cline_skills.py` |
 | Tracked capabilities | `clinerules`, Plan Mode, Act Mode, MCP, custom modes, workflows, hooks, skills, subagents, conditional rules |
-| Notes | Conditional rules (`paths:` YAML frontmatter) are emitted for testing and language-specific rules since 2026-04. Skills (`.cline/skills/`) and hooks (`.clinerules/hooks/`) remain experimental upstream and are not yet generated. |
-| Global install | `ai-toolkit install --editors cline` writes only documented global rules under `~/Documents/Cline/Rules/`; MCP remains managed by `ai-toolkit mcp install --editor cline`. |
+| Notes | Conditional rules (`paths:` YAML frontmatter) are emitted for testing and language-specific rules since 2026-04. Project rules still use `.clinerules/` for compatibility; the documented `~/.cline/rules/` path is used for global install. Skills are emitted as a pointer catalogue in `profile=full` and global installs. |
+| Global install | `ai-toolkit install --editors cline` writes documented global rules under `~/.cline/rules/` and a skill pointer under `~/.cline/skills/`; MCP remains managed by `ai-toolkit mcp install --editor cline`. |
 
 ### Roo Code
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.3.3",
+  "version": "4.4.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.3.3",
+  "version": "4.4.0",
   "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/ecosystem_tools.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
-  "last_updated": "2026-04-23",
+  "last_updated": "2026-05-25",
   "tools": [
     {
       "id": "claude-code",
@@ -80,12 +80,20 @@
         ".cursor/mcp.json",
         "~/.cursor/mcp.json",
         ".cursor/skills/*/SKILL.md",
+        "~/.cursor/skills/*/SKILL.md",
+        ".agents/skills/*/SKILL.md",
+        "~/.agents/skills/*/SKILL.md",
+        ".claude/skills/*/SKILL.md",
+        "~/.claude/skills/*/SKILL.md",
+        ".codex/skills/*/SKILL.md",
+        "~/.codex/skills/*/SKILL.md",
         ".cursor/agents/*.md",
         ".cursor/hooks.json"
       ],
       "our_generators": [
         "scripts/generate_cursor_rules.py",
-        "scripts/generate_cursor_mdc.py"
+        "scripts/generate_cursor_mdc.py",
+        "scripts/generate_cursor_skills.py"
       ],
       "capability_markers": [
         "cursorrules",
@@ -114,14 +122,17 @@
         ".windsurfrules",
         ".windsurf/rules/*.md",
         ".windsurf/workflows/*.md",
+        ".windsurf/skills/*/SKILL.md",
         "AGENTS.md",
         "~/.codeium/windsurf/memories/global_rules.md",
+        "~/.codeium/windsurf/skills/*/SKILL.md",
         "~/.codeium/windsurf/mcp_config.json",
         "~/.codeium/windsurf/global_workflows/*.md"
       ],
       "our_generators": [
         "scripts/generate_windsurf.py",
-        "scripts/generate_windsurf_rules.py"
+        "scripts/generate_windsurf_rules.py",
+        "scripts/generate_windsurf_skills.py"
       ],
       "capability_markers": [
         "Cascade",
@@ -131,6 +142,8 @@
         "glob",
         "model_decision",
         "workflows",
+        "skills",
+        "SKILL.md",
         "MCP",
         "memories",
         "hooks"
@@ -225,14 +238,19 @@
       "config_paths": [
         ".clinerules/*.md",
         ".clinerules/workflows/*.md",
-        ".clinerules/hooks/",
-        ".cline/skills/",
+        ".cline/rules/*.md",
+        ".cline/hooks/",
+        ".cline/skills/*/SKILL.md",
+        "~/.cline/rules/*.md",
+        "~/.cline/hooks/",
+        "~/.cline/skills/*/SKILL.md",
         "~/.cline/data/settings/cline_mcp_settings.json",
-        "~/Documents/Cline/Rules/"
+        ".claude/skills/*/SKILL.md"
       ],
       "our_generators": [
         "scripts/generate_cline.py",
-        "scripts/generate_cline_rules.py"
+        "scripts/generate_cline_rules.py",
+        "scripts/generate_cline_skills.py"
       ],
       "capability_markers": [
         "clinerules",

package/scripts/generate_cline_skills.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Generate a Cline skill pointer under ``.cline/skills/``."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from skill_pointer import POINTER_SKILL_NAME, write_pointer_skill
+
+
+def generate(target_dir: Path, *, emit_skill_pointer: bool = True,
+             skill_root: str = ".cline/skills") -> None:
+    if not emit_skill_pointer:
+        return
+    write_pointer_skill(target_dir, skill_root, "Cline")
+    print(f"  Generated: {skill_root}/{POINTER_SKILL_NAME}/SKILL.md")
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_codex_hooks.py

@@ -25,6 +25,9 @@ from pathlib import Path
 
 
 HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_QUIET=1 "$HOME/.softspark/ai-toolkit/hooks/'
+HOOKS_JSON_CONTEXT_PREFIX = (
+    'AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json "$HOME/.softspark/ai-toolkit/hooks/'
+)
 
 # Hooks compatible with Codex, grouped by event.
 # Format: (matcher, script_name)
@@ -63,7 +66,12 @@ def build_hooks_json() -> dict:
     for event, entries in CODEX_HOOKS.items():
         hooks[event] = []
         for matcher, script in entries:
-            entry: dict = {"hooks": [{"type": "command", "command": f"{HOOKS_PREFIX}{script}\""}]}
+            prefix = (
+                HOOKS_JSON_CONTEXT_PREFIX
+                if event == "UserPromptSubmit" and script == "user-prompt-submit.sh"
+                else HOOKS_PREFIX
+            )
+            entry: dict = {"hooks": [{"type": "command", "command": f"{prefix}{script}\""}]}
             if matcher:
                 entry["matcher"] = matcher
             hooks[event].append(entry)

package/scripts/generate_cursor_skills.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+"""Generate a Cursor skill pointer under ``.cursor/skills/``."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from skill_pointer import POINTER_SKILL_NAME, write_pointer_skill
+
+
+def generate(target_dir: Path, *, emit_skill_pointer: bool = True) -> None:
+    if not emit_skill_pointer:
+        return
+    write_pointer_skill(target_dir, ".cursor/skills", "Cursor")
+    print(f"  Generated: .cursor/skills/{POINTER_SKILL_NAME}/SKILL.md")
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_windsurf_skills.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Generate a Windsurf skill pointer under ``.windsurf/skills/``."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from skill_pointer import POINTER_SKILL_NAME, write_pointer_skill
+
+
+def generate(target_dir: Path, *, emit_skill_pointer: bool = True,
+             skill_root: str = ".windsurf/skills") -> None:
+    if not emit_skill_pointer:
+        return
+    write_pointer_skill(target_dir, skill_root, "Windsurf")
+    print(f"  Generated: {skill_root}/{POINTER_SKILL_NAME}/SKILL.md")
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/install.py

@@ -12,9 +12,9 @@ Claude Code (~/.claude/):
   - Rules injected into ~/.claude/CLAUDE.md
 
 Other tools (global config locations):
-  - Windsurf: ~/.codeium/windsurf/memories/global_rules.md
+  - Windsurf: ~/.codeium/windsurf/memories/global_rules.md + ~/.codeium/windsurf/skills/
   - Gemini:   ~/.gemini/GEMINI.md
-  - Cline:    ~/Documents/Cline/Rules/
+  - Cline:    ~/.cline/rules/ + ~/.cline/skills/
   - Roo Code: ~/.roo/rules/
   - Aider:    ~/.aider.conf.yml (created only if absent)
   - Augment:  ~/.augment/rules/ai-toolkit.md

package/scripts/install_steps/ai_tools.py

@@ -54,11 +54,11 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
     # in the requested set, install it unconditionally.
 
     if "windsurf" in eds:
-        windsurf_file = target_dir / ".codeium" / "windsurf" / "memories" / "global_rules.md"
         if dry_run:
             print("  Would inject: ~/.codeium/windsurf/memories/global_rules.md")
+            print("  Would generate: ~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md")
         else:
-            inject_with_rules("generate-windsurf.sh", windsurf_file, rules_dir)
+            _install_windsurf_global(target_dir, rules_dir)
         installed.append("windsurf")
 
     if "gemini" in eds:
@@ -79,7 +79,8 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
 
     if "cline" in eds:
         if dry_run:
-            print("  Would generate: ~/Documents/Cline/Rules/ai-toolkit-*.md")
+            print("  Would generate: ~/.cline/rules/ai-toolkit-*.md")
+            print("  Would generate: ~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md")
         else:
             _install_cline_global(target_dir, rules_dir)
         installed.append("cline")
@@ -149,11 +150,23 @@ def _install_codex_global(target_dir: Path, rules_dir: Path) -> None:
     _install_codex_skills(target_dir)
 
 
+def _install_windsurf_global(target_dir: Path, rules_dir: Path) -> None:
+    """Install Windsurf global rules plus an Agent Skills catalogue pointer."""
+    windsurf_file = target_dir / ".codeium" / "windsurf" / "memories" / "global_rules.md"
+    inject_with_rules("generate-windsurf.sh", windsurf_file, rules_dir)
+
+    from generate_windsurf_skills import generate as gen_windsurf_skills
+    gen_windsurf_skills(
+        target_dir,
+        skill_root=".codeium/windsurf/skills",
+    )
+
+
 def _install_cline_global(target_dir: Path, rules_dir: Path) -> None:
-    """Install Cline global rules in the documented user rules directory."""
+    """Install Cline global rules in the documented ~/.cline directory."""
     from generate_cline_rules import generate as gen_cline_rules
 
-    rules_root = target_dir / "Documents" / "Cline" / "Rules"
+    rules_root = target_dir / ".cline" / "rules"
     gen_cline_rules(
         target_dir,
         rules_dir=rules_dir,
@@ -161,7 +174,10 @@ def _install_cline_global(target_dir: Path, rules_dir: Path) -> None:
         emit_workflows=False,
         managed_scopes=("standard", "custom"),
     )
-    print("  Created: ~/Documents/Cline/Rules/ai-toolkit-*.md")
+    print("  Created: ~/.cline/rules/ai-toolkit-*.md")
+
+    from generate_cline_skills import generate as gen_cline_skills
+    gen_cline_skills(target_dir)
 
 
 def _install_roo_global(target_dir: Path, rules_dir: Path) -> None:
@@ -693,9 +709,11 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         print("  Would generate: .gemini/settings.json hooks (profile >= standard)")
     if add_native_surfaces:
         if "cursor" in eds:
-            print("  Would generate: .cursor/hooks.json + .cursor/agents/ (profile=full)")
+            print("  Would generate: .cursor/hooks.json + .cursor/agents/ + .cursor/skills/ (profile=full)")
         if "windsurf" in eds:
-            print("  Would generate: .windsurf/hooks.json (profile=full)")
+            print("  Would generate: .windsurf/hooks.json + .windsurf/skills/ (profile=full)")
+        if "cline" in eds:
+            print("  Would generate: .cline/skills/ (profile=full)")
         if "augment" in eds:
             print("  Would generate: .augment/agents/ + .augment/commands/ + "
                   "$HOME/.augment/settings.json + .augment/skills/ (profile=full)")
@@ -907,6 +925,7 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         if add_native_surfaces:
             _try_generator("generate_cursor_hooks", cwd)
             _try_generator("generate_cursor_agents", cwd)
+            _try_generator("generate_cursor_skills", cwd)
 
     if "windsurf" in eds:
         inject_with_rules(
@@ -919,6 +938,7 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
                            rules_dir=rules_dir)
         if add_native_surfaces:
             _try_generator("generate_windsurf_hooks", cwd)
+            _try_generator("generate_windsurf_skills", cwd)
 
     if "cline" in eds:
         # Migrate: remove legacy .clinerules single file (replaced by directory)
@@ -933,6 +953,8 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             rules_dir=rules_dir,
             managed_scopes=("standard", "lang", "custom"),
         )
+        if add_native_surfaces:
+            _try_generator("generate_cline_skills", cwd)
 
     if "roo" in eds:
         roo_output = run_script("generate-roo-modes.sh", capture=True)

package/scripts/skill_pointer.py

@@ -0,0 +1,49 @@
+"""Shared generator for editor-native ai-toolkit skill catalogue pointers."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from emission import emit_skills_bullets
+
+
+POINTER_SKILL_NAME = "ai-toolkit-skill-catalogue"
+
+
+def build_pointer_skill(editor_name: str) -> str:
+    """Build a SKILL.md pointer to the canonical ai-toolkit skill catalogue."""
+    body = (
+        "# AI Toolkit Skill Catalogue\n\n"
+        f"This workspace uses ai-toolkit with {editor_name}. Real skills are "
+        "installed alongside Claude Code at `.claude/skills/` (project "
+        "install) or `~/.claude/skills/` (global install). If those paths are "
+        "not present, use the catalogue below to identify the matching "
+        "ai-toolkit skill before recreating its workflow manually.\n\n"
+        "## When to use this skill\n\n"
+        "- The user's request maps to one of the catalogued skills below.\n"
+        "- You need to discover which ai-toolkit skill should guide the task.\n\n"
+        "## How to use a catalogue entry\n\n"
+        "1. Match the user's task to a skill name in the catalogue.\n"
+        "2. Read the skill's SKILL.md from `.claude/skills/<name>/SKILL.md` "
+        "or `~/.claude/skills/<name>/SKILL.md` when available.\n"
+        "3. Follow that skill's workflow, rules, gotchas, and exclusions.\n\n"
+        "## Catalogue\n\n"
+        f"{emit_skills_bullets()}\n"
+    )
+    return (
+        "---\n"
+        f"name: {POINTER_SKILL_NAME}\n"
+        "description: Index of ai-toolkit skills installed at .claude/skills/"
+        " or ~/.claude/skills/. Read this first when the user's request "
+        "matches a named skill.\n"
+        "---\n"
+        f"{body}"
+    )
+
+
+def write_pointer_skill(target_dir: Path, skill_root: str, editor_name: str) -> Path:
+    """Write a pointer skill under ``skill_root/<pointer>/SKILL.md``."""
+    skill_dir = target_dir / skill_root / POINTER_SKILL_NAME
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    skill_file = skill_dir / "SKILL.md"
+    skill_file.write_text(build_pointer_skill(editor_name), encoding="utf-8")
+    return skill_file