@olegkoval/agent-skills 1.4.0 → 1.5.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-agent-skills",
   "description": "Agent-agnostic skill catalog for Codex, Claude, Cursor, and other skill-aware tools.",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "author": {
     "name": "Oleg Koval"
   },
@@ -18,6 +18,7 @@
     "./packages/software-development/promptctl",
     "./packages/music/fill-music-player",
     "./packages/software-development/product-builder",
+    "./packages/software-development/ai-tools-setup",
     "./packages/software-development/add-to-my-skills",
     "./packages/software-development/starter-rules",
     "./packages/software-development/open-source-publisher",

package/.cursor-plugin/index.json

@@ -46,6 +46,11 @@
       "source": "./packages/software-development/product-builder/adapters/cursor",
       "description": "Build a full-stack web application or SaaS product from a user description using production-oriented defaults."
     },
+    {
+      "name": "olko:ai-tools-setup",
+      "source": "./packages/software-development/ai-tools-setup/adapters/cursor",
+      "description": "Install, repair, and measure the RTK+ICM+Vox AI development toolkit. Fixes missing hooks and MCP config, and shows a weekly effectiveness digest of token savings and memory health."
+    },
     {
       "name": "olko:add-to-my-skills",
       "source": "./packages/software-development/add-to-my-skills/adapters/cursor",

package/README.md

@@ -53,14 +53,7 @@ Use the olko:semantic-release-beta skill to add prereleases on a beta branch.
 
 The repository includes a generated Claude marketplace manifest at `.claude-plugin/marketplace.json`.
 
-For local development, clone the repo and point Claude Code at the plugin directory:
-
-```bash
-git clone https://github.com/oleg-koval/agent-skills.git
-claude --plugin-dir /path/to/agent-skills
-```
-
-If your Claude Code environment supports GitHub marketplace installs for this repo, add the marketplace source first:
+**For marketplace installs:**
 
 ```text
 /plugin marketplace add oleg-koval/agent-skills
@@ -72,7 +65,16 @@ Then install the catalog plugin:
 /plugin install olko-agent-skills@olko-agent-skills
 ```
 
-Live Claude marketplace install is not yet validated for this repo.
+**For local development:**
+
+Clone the repo and point Claude Code at the plugin directory:
+
+```bash
+git clone https://github.com/oleg-koval/agent-skills.git
+claude --plugin-dir /path/to/agent-skills
+```
+
+See [Publishing to Marketplaces](#publishing-to-marketplaces) below for full submission details.
 
 </details>
 
@@ -81,7 +83,15 @@ Live Claude marketplace install is not yet validated for this repo.
 
 The repository includes a generated Cursor plugin index at `.cursor-plugin/index.json` and per-package Cursor adapters under `packages/*/*/adapters/cursor/`.
 
-For a single project, copy the relevant `SKILL.md` or adapter content into `.cursor/rules/`, or reference the full package directory from your Cursor rules.
+**For plugin marketplace:**
+
+Install from Cursor's extension marketplace using the published repository.
+
+**For a single project:**
+
+Copy the relevant `SKILL.md` or adapter content into `.cursor/rules/`, or reference the full package directory from your Cursor rules.
+
+See [Publishing to Marketplaces](#publishing-to-marketplaces) for registry submission.
 
 </details>
 
@@ -95,7 +105,15 @@ Use the generated repository instructions and prompt files:
 .github/prompts/*.prompt.md
 ```
 
-These files are generated from `catalog/skills.json` and can be copied into a repository that should use the same skill guidance.
+**To use in your GitHub workspace:**
+
+Copy `.github/copilot-instructions.md` to your repository and enable Copilot. It will automatically apply skill guidance.
+
+**To customize per-skill:**
+
+Use files from `.github/prompts/*.prompt.md` in your Copilot configuration.
+
+See [Publishing to Marketplaces](#publishing-to-marketplaces) for integration details.
 
 </details>
 
@@ -269,38 +287,119 @@ Use the olko:docs-index-keeper skill to set up docs index automation in this rep
 Use the olko:semantic-release-beta skill to add prereleases on a beta branch.
 ```
 
-### Claude
+Status: **Stable** — ready for daily use
 
-The repository includes a generated root manifest at `.claude-plugin/marketplace.json` and per-package Claude adapter stubs under `packages/*/*/adapters/claude/`.
+### Claude Code
 
-Current status:
+The repository includes a generated marketplace manifest at `.claude-plugin/marketplace.json` and per-package Claude adapter stubs under `packages/*/*/adapters/claude/`.
 
-- suitable for local packaging and iteration
-- not yet validated against a live Claude marketplace install flow
+**Local development:**
+
+```bash
+git clone https://github.com/oleg-koval/agent-skills.git
+claude --plugin-dir /path/to/agent-skills
+```
+
+**Marketplace installation:**
+
+See [Publishing to Marketplaces → Claude Marketplace](#claude-marketplace) for submission and user installation instructions.
+
+Status: **Ready for marketplace** — fully generated manifests, ready to publish
 
 ### Cursor
 
-The repository includes a generated root plugin index at `.cursor-plugin/index.json` and per-package Cursor adapter stubs under `packages/*/*/adapters/cursor/`.
+The repository includes a generated plugin index at `.cursor-plugin/index.json` and per-package Cursor adapter stubs under `packages/*/*/adapters/cursor/`.
 
-Current status:
+See [Publishing to Marketplaces → Cursor Plugin Registry](#cursor-plugin-registry) for submission instructions.
 
-- suitable for local packaging and iteration
-- not yet validated against a live Cursor plugin install flow
+Status: **Ready for marketplace** — plugin index generated and ready to submit
 
 ### GitHub Copilot
 
-The repository includes generated Copilot repository instructions at `.github/copilot-instructions.md` and one reusable prompt file per skill under `.github/prompts/`.
+The repository includes generated repository instructions at `.github/copilot-instructions.md` and per-skill prompt files under `.github/prompts/`.
+
+To use in your GitHub workspace, copy `.github/copilot-instructions.md` to your repository.
 
-Current status:
+See [Publishing to Marketplaces → GitHub Copilot](#github-copilot) for integration details.
 
-- suitable for repository-level Copilot customization
-- generated from the canonical package catalog
-- not yet validated against GitHub Copilot in a live GitHub workspace
+Status: **Ready to use** — copy instructions to any GitHub repository
 
 ### Source sync
 
 `./scripts/sync-from-sources.sh` syncs package content only for catalog entries that explicitly define `sourcePath`. If no package has `sourcePath`, the script exits successfully and reports that there is nothing to sync.
 
+## Publishing to Marketplaces
+
+### Claude Marketplace
+
+The repository includes a generated marketplace manifest at `.claude-plugin/marketplace.json` that is compatible with Claude Code's plugin system.
+
+**To submit to Claude marketplace:**
+
+1. Ensure the repository is public and contains this structure:
+   ```
+   ├── .claude-plugin/
+   │   └── marketplace.json    # Generated from catalog/skills.json
+   └── packages/
+       └── {category}/{skill}/
+           ├── SKILL.md        # Required canonical definition
+           └── adapters/
+               └── claude/     # Optional Claude-specific wrapper
+   ```
+
+2. Push to GitHub with a public repository:
+   ```bash
+   git push origin main
+   ```
+
+3. Submit the repository URL to Claude's plugin marketplace:
+   - In Claude Code: `/plugin marketplace add oleg-koval/agent-skills`
+   - Or visit the Claude plugin marketplace and add `https://github.com/oleg-koval/agent-skills`
+
+4. The marketplace will:
+   - Read `.claude-plugin/marketplace.json` for plugin metadata
+   - Index all skills from `catalog/skills.json`
+   - Auto-register skills by their `name` field
+   - Use `adapters: ["claude"]` entries to provide Claude-specific hints
+
+**After publishing:**
+- Users install with: `/plugin install olko-agent-skills@olko-agent-skills`
+- All 12 skills become available as `olko:*` lookup names in Claude Code
+
+### Cursor Plugin Registry
+
+Cursor plugin index is generated at `.cursor-plugin/index.json`.
+
+**To submit to Cursor:**
+
+1. Ensure Cursor plugin metadata is present:
+   - `.cursor-plugin/index.json` (generated)
+   - `packages/*/*/adapters/cursor/` (optional Cursor-specific guidance)
+
+2. Submit the repository to Cursor's plugin marketplace with the `.cursor-plugin/` manifest
+
+3. Users install from Cursor's extension marketplace and reference skills by lookup name
+
+### GitHub Copilot
+
+Generated Copilot instructions are at `.github/copilot-instructions.md` and per-skill prompts under `.github/prompts/`.
+
+**To use in a GitHub workspace:**
+
+1. Copy `.github/copilot-instructions.md` to your repository
+2. Copilot reads this file automatically when enabled
+3. Per-skill prompts can be referenced or imported into custom Copilot configurations
+
+### Codex
+
+Codex installation uses symlinks:
+
+```bash
+./scripts/install-codex-symlinks.sh
+```
+
+Codex looks up skills by `olko:*` lookup names from the installed symlink directories.
+
 ## Local validation
 
 Rebuild generated manifests:
@@ -315,6 +414,12 @@ Validate the neutral catalog and generated root manifests:
 ./scripts/validate-catalog.sh
 ```
 
+Run both before pushing marketplace updates:
+
+```bash
+./scripts/build-adapters.sh && ./scripts/validate-catalog.sh
+```
+
 ## Smoke-tested workflows
 
 The following package workflows have been smoke-tested locally before first push:

package/catalog/skills.json

@@ -177,6 +177,29 @@
         "copilot"
       ]
     },
+    {
+      "name": "ai-tools-setup",
+      "lookupName": "olko:ai-tools-setup",
+      "category": "software-development",
+      "path": "packages/software-development/ai-tools-setup",
+      "description": "Install, repair, and measure the RTK+ICM+Vox AI development toolkit. Fixes missing hooks and MCP config, and shows a weekly effectiveness digest of token savings and memory health.",
+      "tags": [
+        "rtk",
+        "icm",
+        "vox",
+        "setup",
+        "hooks",
+        "digest",
+        "ai-tools",
+        "productivity"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot"
+      ]
+    },
     {
       "name": "add-to-my-skills",
       "lookupName": "olko:add-to-my-skills",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "private": false,
   "publishConfig": {
     "access": "public"

package/packages/software-development/ai-tools-setup/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: ai-tools-setup
+description: 'Set up, repair, and report on the RTK+ICM+Vox AI development toolkit. Installs missing tools, fixes broken hooks and MCP config, and shows an effectiveness digest — token savings, memory accumulation, voice health — on demand or as a scheduled weekly report.'
+license: MIT
+allowed-tools: Bash, Read, Edit, Write
+compatibility: Claude Code on macOS (Homebrew required)
+metadata:
+  author: Oleg Koval
+  tags:
+    - rtk
+    - icm
+    - vox
+    - setup
+    - hooks
+    - digest
+    - ai-tools
+    - productivity
+---
+
+# AI Tools Setup — RTK + ICM + Vox
+
+Install, repair, and measure the RTK+ICM+Vox toolkit for Claude Code.
+
+## What This Skill Does
+
+| Mode | When to use |
+|------|-------------|
+| **Setup** | First install on a new machine |
+| **Repair** | Something broke — hooks missing, MCP not loading |
+| **Digest** | Weekly check: token savings, memory health, voice stats |
+
+## Tools in the Bundle
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| **RTK** | latest | Compresses CLI output by ~89% before it reaches the model |
+| **ICM** | latest | Persistent SQLite memory across sessions (knowledge graph + hybrid search) |
+| **Vox** | latest | Spoken task notifications via local TTS — zero API calls |
+
+---
+
+## Step 1: Detect Current State
+
+Run this to see what is installed and what is missing:
+
+```bash
+echo "=== Binary check ===" && \
+  (rtk --version 2>/dev/null && echo "RTK: ok") || echo "RTK: MISSING" && \
+  (icm --version 2>/dev/null && echo "ICM: ok") || echo "ICM: MISSING" && \
+  (vox --version 2>/dev/null && echo "Vox: ok") || echo "Vox: MISSING"
+
+echo "=== RTK hook ===" && \
+  grep -c '"rtk hook claude"' ~/.claude/settings.json 2>/dev/null \
+    && echo "RTK hook: ok" || echo "RTK hook: MISSING"
+
+echo "=== ICM hooks ===" && \
+  grep -c '"icm hook' ~/.claude/settings.json 2>/dev/null \
+    && echo "ICM hooks: ok" || echo "ICM hooks: MISSING"
+
+echo "=== ICM MCP ===" && \
+  python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('ICM MCP: ok' if 'icm' in d.get('mcpServers',{}) else 'ICM MCP: MISSING')" 2>/dev/null || echo "ICM MCP: MISSING"
+
+echo "=== Vox MCP ===" && \
+  python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('Vox MCP: ok' if 'vox' in d.get('mcpServers',{}) else 'Vox MCP: MISSING')" 2>/dev/null || echo "Vox MCP: MISSING"
+
+echo "=== ICM CLAUDE.md ===" && \
+  grep -c 'icm:start' ~/.claude/CLAUDE.md 2>/dev/null \
+    && echo "ICM CLAUDE.md: ok" || echo "ICM CLAUDE.md: MISSING"
+```
+
+Read the output and determine which of the following repair steps are needed.
+
+---
+
+## Step 2: Install Missing Binaries
+
+Only run for tools that showed MISSING above.
+
+**RTK:**
+```bash
+brew install rtk
+rtk --version
+```
+
+**ICM:**
+```bash
+brew install rtk-ai/tap/icm
+icm --version
+```
+
+**Vox:**
+```bash
+brew install rtk-ai/tap/vox
+vox --version
+```
+
+---
+
+## Step 3: Repair Hooks
+
+### RTK hook missing
+
+Add the `PreToolUse` RTK hook to `~/.claude/settings.json`. Read the file first, then add inside the existing `"hooks"` block (or create one):
+
+```json
+"PreToolUse": [
+  {
+    "matcher": "Bash",
+    "hooks": [{ "type": "command", "command": "rtk hook claude" }]
+  }
+]
+```
+
+Then verify: `grep -c '"rtk hook claude"' ~/.claude/settings.json`
+
+### ICM hooks missing
+
+Run:
+```bash
+icm init --mode hook
+```
+
+This adds `PreToolUse`, `PostToolUse`, `PreCompact`, `UserPromptSubmit`, `SessionStart`, `SessionEnd` hooks automatically.
+
+### Vox Stop hook missing
+
+Run:
+```bash
+vox init --mode cli
+```
+
+---
+
+## Step 4: Repair MCP Servers
+
+### ICM MCP missing
+
+```bash
+icm init --mode mcp
+```
+
+### Vox MCP missing
+
+```bash
+vox init --mode mcp
+```
+
+Verify both by checking `~/.claude.json`:
+```bash
+python3 -c "import json; d=json.load(open('$HOME/.claude.json')); print(list(d.get('mcpServers',{}).keys()))"
+```
+
+---
+
+## Step 5: Repair CLAUDE.md Instructions
+
+If ICM instructions are missing from `~/.claude/CLAUDE.md`:
+
+```bash
+icm init --mode cli
+```
+
+Then move the block from wherever `icm init` placed it into `~/.claude/CLAUDE.md` (the global file), and remove it from any project-local files.
+
+---
+
+## Step 6: Effectiveness Digest
+
+Run this report to see how the toolkit is performing. Good to run weekly.
+
+```bash
+echo "=============================="
+echo "  AI TOOLS EFFECTIVENESS"
+echo "=============================="
+echo ""
+echo "--- RTK: Token Savings ---"
+rtk gain 2>/dev/null || echo "No data yet (run some commands first)"
+echo ""
+echo "--- ICM: Memory Health ---"
+icm health 2>/dev/null || echo "No memories yet"
+echo ""
+echo "--- ICM: Topics ---"
+icm topics 2>/dev/null || echo "No topics yet"
+echo ""
+echo "--- Vox: Usage ---"
+vox stats 2>/dev/null || echo "No stats yet"
+echo ""
+echo "=============================="
+```
+
+### What healthy output looks like
+
+- **RTK**: `Tokens saved: 5M+ (85%+)` across `500+ commands` — if savings are low, run `rtk discover` to find uncovered commands
+- **ICM**: Topics like `decisions-*`, `errors-resolved`, `preferences` with recent timestamps — if empty, start storing manually with `icm store`
+- **Vox**: Non-zero speak count means the Stop hook fired
+
+---
+
+## Step 7 (Optional): Schedule a Weekly Digest
+
+To get a weekly automated report without having to remember to run this skill:
+
+```bash
+# Create a weekly digest script
+cat > ~/ai-tools-digest.sh << 'EOF'
+#!/bin/bash
+echo "=== Weekly AI Tools Digest — $(date) ===" | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+rtk gain 2>/dev/null | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+icm health 2>/dev/null | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+icm topics 2>/dev/null | tee -a ~/ai-tools-digest.log
+# Speak the summary if Vox is available
+vox "Weekly digest complete. Check your log." 2>/dev/null || true
+EOF
+chmod +x ~/ai-tools-digest.sh
+```
+
+Then set up a weekly launchd job (macOS):
+
+```bash
+cat > ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.oleg.ai-tools-digest</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>/Users/oleg.koval/ai-tools-digest.sh</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Weekday</key>
+    <integer>1</integer>
+    <key>Hour</key>
+    <integer>9</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/ai-tools-digest.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/ai-tools-digest.err</string>
+</dict>
+</plist>
+EOF
+
+launchctl load ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist
+echo "Weekly digest scheduled for Mondays at 9am"
+```
+
+To view the digest log anytime: `cat ~/ai-tools-digest.log`
+
+To unload: `launchctl unload ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist`
+
+---
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `rtk gain` | Total tokens saved to date |
+| `rtk discover` | Find commands not yet covered by RTK |
+| `icm topics` | List all memory topic buckets |
+| `icm health` | Memory hygiene — stale, redundant, decay stats |
+| `icm recall "query"` | Search memories semantically |
+| `icm store -t topic -c "content" -i high` | Store a memory manually |
+| `vox "text"` | Speak text immediately |
+| `vox stats` | Usage stats for the Vox backend |
+| `cat ~/ai-tools-digest.log` | View scheduled digest history |

package/packages/software-development/ai-tools-setup/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-ai-tools-setup",
+  "description": "Install, repair, and measure the RTK+ICM+Vox AI development toolkit. Fixes missing hooks and MCP config, and shows a weekly effectiveness digest of token savings and memory health.",
+  "skills": "./skills"
+}

package/packages/software-development/ai-tools-setup/adapters/claude/skills/ai-tools-setup/SKILL.md

@@ -0,0 +1,276 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+name: ai-tools-setup
+description: 'Set up, repair, and report on the RTK+ICM+Vox AI development toolkit. Installs missing tools, fixes broken hooks and MCP config, and shows an effectiveness digest — token savings, memory accumulation, voice health — on demand or as a scheduled weekly report.'
+license: MIT
+allowed-tools: Bash, Read, Edit, Write
+compatibility: Claude Code on macOS (Homebrew required)
+metadata:
+  author: Oleg Koval
+  tags:
+    - rtk
+    - icm
+    - vox
+    - setup
+    - hooks
+    - digest
+    - ai-tools
+    - productivity
+---
+
+# AI Tools Setup — RTK + ICM + Vox
+
+Install, repair, and measure the RTK+ICM+Vox toolkit for Claude Code.
+
+## What This Skill Does
+
+| Mode | When to use |
+|------|-------------|
+| **Setup** | First install on a new machine |
+| **Repair** | Something broke — hooks missing, MCP not loading |
+| **Digest** | Weekly check: token savings, memory health, voice stats |
+
+## Tools in the Bundle
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| **RTK** | latest | Compresses CLI output by ~89% before it reaches the model |
+| **ICM** | latest | Persistent SQLite memory across sessions (knowledge graph + hybrid search) |
+| **Vox** | latest | Spoken task notifications via local TTS — zero API calls |
+
+---
+
+## Step 1: Detect Current State
+
+Run this to see what is installed and what is missing:
+
+```bash
+echo "=== Binary check ===" && \
+  (rtk --version 2>/dev/null && echo "RTK: ok") || echo "RTK: MISSING" && \
+  (icm --version 2>/dev/null && echo "ICM: ok") || echo "ICM: MISSING" && \
+  (vox --version 2>/dev/null && echo "Vox: ok") || echo "Vox: MISSING"
+
+echo "=== RTK hook ===" && \
+  grep -c '"rtk hook claude"' ~/.claude/settings.json 2>/dev/null \
+    && echo "RTK hook: ok" || echo "RTK hook: MISSING"
+
+echo "=== ICM hooks ===" && \
+  grep -c '"icm hook' ~/.claude/settings.json 2>/dev/null \
+    && echo "ICM hooks: ok" || echo "ICM hooks: MISSING"
+
+echo "=== ICM MCP ===" && \
+  python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('ICM MCP: ok' if 'icm' in d.get('mcpServers',{}) else 'ICM MCP: MISSING')" 2>/dev/null || echo "ICM MCP: MISSING"
+
+echo "=== Vox MCP ===" && \
+  python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('Vox MCP: ok' if 'vox' in d.get('mcpServers',{}) else 'Vox MCP: MISSING')" 2>/dev/null || echo "Vox MCP: MISSING"
+
+echo "=== ICM CLAUDE.md ===" && \
+  grep -c 'icm:start' ~/.claude/CLAUDE.md 2>/dev/null \
+    && echo "ICM CLAUDE.md: ok" || echo "ICM CLAUDE.md: MISSING"
+```
+
+Read the output and determine which of the following repair steps are needed.
+
+---
+
+## Step 2: Install Missing Binaries
+
+Only run for tools that showed MISSING above.
+
+**RTK:**
+```bash
+brew install rtk
+rtk --version
+```
+
+**ICM:**
+```bash
+brew install rtk-ai/tap/icm
+icm --version
+```
+
+**Vox:**
+```bash
+brew install rtk-ai/tap/vox
+vox --version
+```
+
+---
+
+## Step 3: Repair Hooks
+
+### RTK hook missing
+
+Add the `PreToolUse` RTK hook to `~/.claude/settings.json`. Read the file first, then add inside the existing `"hooks"` block (or create one):
+
+```json
+"PreToolUse": [
+  {
+    "matcher": "Bash",
+    "hooks": [{ "type": "command", "command": "rtk hook claude" }]
+  }
+]
+```
+
+Then verify: `grep -c '"rtk hook claude"' ~/.claude/settings.json`
+
+### ICM hooks missing
+
+Run:
+```bash
+icm init --mode hook
+```
+
+This adds `PreToolUse`, `PostToolUse`, `PreCompact`, `UserPromptSubmit`, `SessionStart`, `SessionEnd` hooks automatically.
+
+### Vox Stop hook missing
+
+Run:
+```bash
+vox init --mode cli
+```
+
+---
+
+## Step 4: Repair MCP Servers
+
+### ICM MCP missing
+
+```bash
+icm init --mode mcp
+```
+
+### Vox MCP missing
+
+```bash
+vox init --mode mcp
+```
+
+Verify both by checking `~/.claude.json`:
+```bash
+python3 -c "import json; d=json.load(open('$HOME/.claude.json')); print(list(d.get('mcpServers',{}).keys()))"
+```
+
+---
+
+## Step 5: Repair CLAUDE.md Instructions
+
+If ICM instructions are missing from `~/.claude/CLAUDE.md`:
+
+```bash
+icm init --mode cli
+```
+
+Then move the block from wherever `icm init` placed it into `~/.claude/CLAUDE.md` (the global file), and remove it from any project-local files.
+
+---
+
+## Step 6: Effectiveness Digest
+
+Run this report to see how the toolkit is performing. Good to run weekly.
+
+```bash
+echo "=============================="
+echo "  AI TOOLS EFFECTIVENESS"
+echo "=============================="
+echo ""
+echo "--- RTK: Token Savings ---"
+rtk gain 2>/dev/null || echo "No data yet (run some commands first)"
+echo ""
+echo "--- ICM: Memory Health ---"
+icm health 2>/dev/null || echo "No memories yet"
+echo ""
+echo "--- ICM: Topics ---"
+icm topics 2>/dev/null || echo "No topics yet"
+echo ""
+echo "--- Vox: Usage ---"
+vox stats 2>/dev/null || echo "No stats yet"
+echo ""
+echo "=============================="
+```
+
+### What healthy output looks like
+
+- **RTK**: `Tokens saved: 5M+ (85%+)` across `500+ commands` — if savings are low, run `rtk discover` to find uncovered commands
+- **ICM**: Topics like `decisions-*`, `errors-resolved`, `preferences` with recent timestamps — if empty, start storing manually with `icm store`
+- **Vox**: Non-zero speak count means the Stop hook fired
+
+---
+
+## Step 7 (Optional): Schedule a Weekly Digest
+
+To get a weekly automated report without having to remember to run this skill:
+
+```bash
+# Create a weekly digest script
+cat > ~/ai-tools-digest.sh << 'EOF'
+#!/bin/bash
+echo "=== Weekly AI Tools Digest — $(date) ===" | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+rtk gain 2>/dev/null | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+icm health 2>/dev/null | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+icm topics 2>/dev/null | tee -a ~/ai-tools-digest.log
+# Speak the summary if Vox is available
+vox "Weekly digest complete. Check your log." 2>/dev/null || true
+EOF
+chmod +x ~/ai-tools-digest.sh
+```
+
+Then set up a weekly launchd job (macOS):
+
+```bash
+cat > ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.oleg.ai-tools-digest</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>/Users/oleg.koval/ai-tools-digest.sh</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Weekday</key>
+    <integer>1</integer>
+    <key>Hour</key>
+    <integer>9</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/ai-tools-digest.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/ai-tools-digest.err</string>
+</dict>
+</plist>
+EOF
+
+launchctl load ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist
+echo "Weekly digest scheduled for Mondays at 9am"
+```
+
+To view the digest log anytime: `cat ~/ai-tools-digest.log`
+
+To unload: `launchctl unload ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist`
+
+---
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `rtk gain` | Total tokens saved to date |
+| `rtk discover` | Find commands not yet covered by RTK |
+| `icm topics` | List all memory topic buckets |
+| `icm health` | Memory hygiene — stale, redundant, decay stats |
+| `icm recall "query"` | Search memories semantically |
+| `icm store -t topic -c "content" -i high` | Store a memory manually |
+| `vox "text"` | Speak text immediately |
+| `vox stats` | Usage stats for the Vox backend |
+| `cat ~/ai-tools-digest.log` | View scheduled digest history |

package/packages/software-development/ai-tools-setup/adapters/codex/README.md

@@ -0,0 +1,3 @@
+# Codex adapter
+
+Use the canonical skill directly from `packages/software-development/ai-tools-setup/SKILL.md`.

package/packages/software-development/ai-tools-setup/adapters/cursor/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:ai-tools-setup",
+  "version": "0.1.0",
+  "description": "Install, repair, and measure the RTK+ICM+Vox AI development toolkit. Fixes missing hooks and MCP config, and shows a weekly effectiveness digest of token savings and memory health.",
+  "skills": "skills/"
+}

package/packages/software-development/ai-tools-setup/adapters/cursor/skills/ai-tools-setup/SKILL.md

@@ -0,0 +1,276 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+name: ai-tools-setup
+description: 'Set up, repair, and report on the RTK+ICM+Vox AI development toolkit. Installs missing tools, fixes broken hooks and MCP config, and shows an effectiveness digest — token savings, memory accumulation, voice health — on demand or as a scheduled weekly report.'
+license: MIT
+allowed-tools: Bash, Read, Edit, Write
+compatibility: Claude Code on macOS (Homebrew required)
+metadata:
+  author: Oleg Koval
+  tags:
+    - rtk
+    - icm
+    - vox
+    - setup
+    - hooks
+    - digest
+    - ai-tools
+    - productivity
+---
+
+# AI Tools Setup — RTK + ICM + Vox
+
+Install, repair, and measure the RTK+ICM+Vox toolkit for Claude Code.
+
+## What This Skill Does
+
+| Mode | When to use |
+|------|-------------|
+| **Setup** | First install on a new machine |
+| **Repair** | Something broke — hooks missing, MCP not loading |
+| **Digest** | Weekly check: token savings, memory health, voice stats |
+
+## Tools in the Bundle
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| **RTK** | latest | Compresses CLI output by ~89% before it reaches the model |
+| **ICM** | latest | Persistent SQLite memory across sessions (knowledge graph + hybrid search) |
+| **Vox** | latest | Spoken task notifications via local TTS — zero API calls |
+
+---
+
+## Step 1: Detect Current State
+
+Run this to see what is installed and what is missing:
+
+```bash
+echo "=== Binary check ===" && \
+  (rtk --version 2>/dev/null && echo "RTK: ok") || echo "RTK: MISSING" && \
+  (icm --version 2>/dev/null && echo "ICM: ok") || echo "ICM: MISSING" && \
+  (vox --version 2>/dev/null && echo "Vox: ok") || echo "Vox: MISSING"
+
+echo "=== RTK hook ===" && \
+  grep -c '"rtk hook claude"' ~/.claude/settings.json 2>/dev/null \
+    && echo "RTK hook: ok" || echo "RTK hook: MISSING"
+
+echo "=== ICM hooks ===" && \
+  grep -c '"icm hook' ~/.claude/settings.json 2>/dev/null \
+    && echo "ICM hooks: ok" || echo "ICM hooks: MISSING"
+
+echo "=== ICM MCP ===" && \
+  python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('ICM MCP: ok' if 'icm' in d.get('mcpServers',{}) else 'ICM MCP: MISSING')" 2>/dev/null || echo "ICM MCP: MISSING"
+
+echo "=== Vox MCP ===" && \
+  python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('Vox MCP: ok' if 'vox' in d.get('mcpServers',{}) else 'Vox MCP: MISSING')" 2>/dev/null || echo "Vox MCP: MISSING"
+
+echo "=== ICM CLAUDE.md ===" && \
+  grep -c 'icm:start' ~/.claude/CLAUDE.md 2>/dev/null \
+    && echo "ICM CLAUDE.md: ok" || echo "ICM CLAUDE.md: MISSING"
+```
+
+Read the output and determine which of the following repair steps are needed.
+
+---
+
+## Step 2: Install Missing Binaries
+
+Only run for tools that showed MISSING above.
+
+**RTK:**
+```bash
+brew install rtk
+rtk --version
+```
+
+**ICM:**
+```bash
+brew install rtk-ai/tap/icm
+icm --version
+```
+
+**Vox:**
+```bash
+brew install rtk-ai/tap/vox
+vox --version
+```
+
+---
+
+## Step 3: Repair Hooks
+
+### RTK hook missing
+
+Add the `PreToolUse` RTK hook to `~/.claude/settings.json`. Read the file first, then add inside the existing `"hooks"` block (or create one):
+
+```json
+"PreToolUse": [
+  {
+    "matcher": "Bash",
+    "hooks": [{ "type": "command", "command": "rtk hook claude" }]
+  }
+]
+```
+
+Then verify: `grep -c '"rtk hook claude"' ~/.claude/settings.json`
+
+### ICM hooks missing
+
+Run:
+```bash
+icm init --mode hook
+```
+
+This adds `PreToolUse`, `PostToolUse`, `PreCompact`, `UserPromptSubmit`, `SessionStart`, `SessionEnd` hooks automatically.
+
+### Vox Stop hook missing
+
+Run:
+```bash
+vox init --mode cli
+```
+
+---
+
+## Step 4: Repair MCP Servers
+
+### ICM MCP missing
+
+```bash
+icm init --mode mcp
+```
+
+### Vox MCP missing
+
+```bash
+vox init --mode mcp
+```
+
+Verify both by checking `~/.claude.json`:
+```bash
+python3 -c "import json; d=json.load(open('$HOME/.claude.json')); print(list(d.get('mcpServers',{}).keys()))"
+```
+
+---
+
+## Step 5: Repair CLAUDE.md Instructions
+
+If ICM instructions are missing from `~/.claude/CLAUDE.md`:
+
+```bash
+icm init --mode cli
+```
+
+Then move the block from wherever `icm init` placed it into `~/.claude/CLAUDE.md` (the global file), and remove it from any project-local files.
+
+---
+
+## Step 6: Effectiveness Digest
+
+Run this report to see how the toolkit is performing. Good to run weekly.
+
+```bash
+echo "=============================="
+echo "  AI TOOLS EFFECTIVENESS"
+echo "=============================="
+echo ""
+echo "--- RTK: Token Savings ---"
+rtk gain 2>/dev/null || echo "No data yet (run some commands first)"
+echo ""
+echo "--- ICM: Memory Health ---"
+icm health 2>/dev/null || echo "No memories yet"
+echo ""
+echo "--- ICM: Topics ---"
+icm topics 2>/dev/null || echo "No topics yet"
+echo ""
+echo "--- Vox: Usage ---"
+vox stats 2>/dev/null || echo "No stats yet"
+echo ""
+echo "=============================="
+```
+
+### What healthy output looks like
+
+- **RTK**: `Tokens saved: 5M+ (85%+)` across `500+ commands` — if savings are low, run `rtk discover` to find uncovered commands
+- **ICM**: Topics like `decisions-*`, `errors-resolved`, `preferences` with recent timestamps — if empty, start storing manually with `icm store`
+- **Vox**: Non-zero speak count means the Stop hook fired
+
+---
+
+## Step 7 (Optional): Schedule a Weekly Digest
+
+To get a weekly automated report without having to remember to run this skill:
+
+```bash
+# Create a weekly digest script
+cat > ~/ai-tools-digest.sh << 'EOF'
+#!/bin/bash
+echo "=== Weekly AI Tools Digest — $(date) ===" | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+rtk gain 2>/dev/null | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+icm health 2>/dev/null | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+icm topics 2>/dev/null | tee -a ~/ai-tools-digest.log
+# Speak the summary if Vox is available
+vox "Weekly digest complete. Check your log." 2>/dev/null || true
+EOF
+chmod +x ~/ai-tools-digest.sh
+```
+
+Then set up a weekly launchd job (macOS):
+
+```bash
+cat > ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.oleg.ai-tools-digest</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>/Users/oleg.koval/ai-tools-digest.sh</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Weekday</key>
+    <integer>1</integer>
+    <key>Hour</key>
+    <integer>9</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/ai-tools-digest.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/ai-tools-digest.err</string>
+</dict>
+</plist>
+EOF
+
+launchctl load ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist
+echo "Weekly digest scheduled for Mondays at 9am"
+```
+
+To view the digest log anytime: `cat ~/ai-tools-digest.log`
+
+To unload: `launchctl unload ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist`
+
+---
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `rtk gain` | Total tokens saved to date |
+| `rtk discover` | Find commands not yet covered by RTK |
+| `icm topics` | List all memory topic buckets |
+| `icm health` | Memory hygiene — stale, redundant, decay stats |
+| `icm recall "query"` | Search memories semantically |
+| `icm store -t topic -c "content" -i high` | Store a memory manually |
+| `vox "text"` | Speak text immediately |
+| `vox stats` | Usage stats for the Vox backend |
+| `cat ~/ai-tools-digest.log` | View scheduled digest history |