@softspark/ai-toolkit 4.3.2 → 4.4.0

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`).
 
@@ -6928,7 +6965,7 @@ title: "AI Toolkit - Codex CLI Compatibility"
 category: reference
 service: ai-toolkit
 tags: [codex, compatibility, install, skills, hooks]
-version: "1.0.1"
+version: "1.0.2"
 created: "2026-04-12"
 last_updated: "2026-05-21"
 description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
@@ -7035,10 +7072,16 @@ 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
+outside the Codex UI.
 
 ## Behavioral Limits
 
@@ -7054,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.
 
@@ -8529,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`
@@ -8835,9 +8880,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.2"
+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."
 ---
 
@@ -8882,10 +8927,10 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 3. Loads session context from `.claude/session-context.md` (if exists)
 4. Loads active instincts from `.claude/instincts/*.md` (if any)
 
-When `AI_TOOLKIT_HOOK_QUIET=1`, the hook still performs session-state reset,
-stale search-flag cleanup, and update notification side effects, but suppresses
-all informational stdout so runtimes such as Codex do not show startup hook
-context in the UI.
+By default the hook performs session-state reset, stale search-flag cleanup, and
+update notification side effects without printing informational stdout. Set
+`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context
+for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
 
 ### Notification — `notify-waiting.sh`
 
@@ -8939,12 +8984,18 @@ context in the UI.
 | Script | `~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh` |
 | Fires | Before Claude starts working on a submitted prompt |
 
-**Action:** Adds a lightweight governance reminder: plan mode for architectural work, evidence-first debugging, KB-first research, and validation expectations.
+**Action:** Maintains the per-session search-first flag used by Stop enforcement
+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.
+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`
 
@@ -9221,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`.
 
@@ -9272,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` 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
@@ -9289,10 +9340,11 @@ Set in `.claude/settings.local.json`:
 | `standard` | All hooks (default) |
 | `strict` | Standard + mypy --strict on task completion |
 
-Set `AI_TOOLKIT_HOOK_QUIET=1` on hook commands to suppress non-blocking
-informational context while preserving side effects and blocking decisions.
-Codex-generated hooks use this mode by default, and Claude's bundled
-`UserPromptSubmit` entry uses it to avoid visible prompt hook context.
+Non-blocking informational context is silent in plain-text mode by default while
+side effects and blocking decisions still run. Set `AI_TOOLKIT_HOOK_VERBOSE=1`
+only when debugging hook context locally. `AI_TOOLKIT_HOOK_QUIET=1` keeps hook
+commands explicitly silent, and Codex-generated hooks plus Claude's bundled
+`UserPromptSubmit` entry use it to avoid visible prompt hook context.
 
 ## Architecture
 
@@ -11662,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."
 ---
 
@@ -11706,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
@@ -11719,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
@@ -11757,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.2",
+  "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.2",
+  "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