@softspark/ai-toolkit 4.3.3 → 4.4.1

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.1",
   "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.1",
   "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,7 +25,6 @@ from pathlib import Path
 
 
 HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_QUIET=1 "$HOME/.softspark/ai-toolkit/hooks/'
-
 # Hooks compatible with Codex, grouped by event.
 # Format: (matcher, script_name)
 CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {

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)