sigmap 8.25.0 → 8.26.1

package/CHANGELOG.md

@@ -10,6 +10,30 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.26.1] — 2026-08-18
+
+Patch release — **"Trust Quick Wins II" (G1)**: the extraction layer gets the same honesty treatment the benchmarks got in v8.19.
+
+### Added
+- **`KNOWN_LIMITATIONS.md` + README extraction-honesty tiers (#520, PR #521):** one page stating plainly what each extractor tier can and cannot do — Tier 1 AST (Python via `python_ast.py`, regex fallback without `python3`), Tier 2 anchored regex (the 11 `withAnchor` brace languages, doc hints on 6), Tier 3 pattern/heuristic (the rest + generic fallback) — plus the truncation caps (25 signatures/file, 8 members/block) and what falls off, the nested-paren regex gap (the stated G4/D1 precondition), and the honest `verify` implication: a real symbol missing from the index flags `fake-symbol` at **medium** confidence — a conservative false positive, never a silent pass. README carries a compact "Extraction honesty" tier label linking the page. A 6-check guard test drift-locks the doc's counts to `version.json` and cross-checks the Tier-2 count against the extractors that actually call `withAnchor`.
+
+### Changed
+- 6 new guard checks (133 test files). No runtime code changed; the npm tarball is unaffected.
+
+---
+
+## [8.26.0] — 2026-08-18
+
+Minor release — **"Agent Economy III" (v8.26, F3+F4)**: the optimal SigMap usage loop ships as installable agent skills in every client's native format — completing the Agent Economy pillar (F1 budget → F2 tune → F3+F4 skills).
+
+### Added
+- **`sigmap skills` (#517, PR #518):** new `src/skills/skills.js` — two canonical, deterministic skill documents: **sigmap-usage-maximizer** (F3 — the spend-minimizing loop: `ask` before any file read · `get_lines` for anchored ranges instead of whole files · `verify_suggestion` before trusting generated code · `squeeze` any big log/trace/JSON · checkpoint via `create_checkpoint`/`note` · check `get_budget` and, near budget, summarize-then-drop; token accounting reads the F1 ledger — no LLM calls) and **sigmap-config-optimizer** (the F2 playbook: `tune` → review the evidence-naming reasons → `tune --apply` → `validate`). Multi-client installer mirroring the `mcp/install.js` CLIENTS pattern: Claude Code (`.claude/skills/<skill>/SKILL.md`), Cursor (`.cursor/rules/*.mdc`), Windsurf (`.windsurf/rules/*.md`), GitHub Copilot (`.github/instructions/*.instructions.md`), and Codex — a marker-delimited block injected into `AGENTS.md` **above** the `## Auto-generated signatures` marker, so the codex adapter's regeneration preserves it (proven by an end-to-end regeneration test). Human content is never touched; every install is idempotent (`installed`/`updated`/`already`). CLI: `sigmap skills list` and `sigmap skills install [--client <name> | --all] [--json]` — plain `install` wires only clients whose parent artifact exists (the `--setup` only-touch-existing precedent); `--client`/`--all` create. Zero new dependencies.
+
+### Changed
+- 8 new integration tests (132 test files); bundle rebuilt (149 modules).
+
+---
+
 ## [8.25.0] — 2026-08-18
 
 Minor release — **"Agent Economy II" (v8.25, F2)**: the discovery stack becomes a config optimizer — one command that recommends (and can apply) the config a repo actually needs.

package/README.md

@@ -122,7 +122,7 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.25-main (21 repositories, including R language)
+Benchmark : sigmap-v8.26-main (21 repositories, including R language)
 Date      : 2026-08-17
 
 Hit@5          : 82.2%   (grep-agent baseline 44.0%  — 1.87× lift)
@@ -397,6 +397,18 @@ All implemented with zero external dependencies.
 
 [Full language table →](https://sigmap.io/guide/generalization.html)
 
+### Extraction honesty
+
+Not all 33 languages get the same depth — and we say so plainly:
+
+| Tier | Coverage | Depth |
+|------|----------|-------|
+| **AST** | Python (`python3` on PATH; regex fallback without) | Full parse |
+| **Anchored regex** | 11 brace languages (JS, TS, Go, Rust, Java, Kotlin, Swift, PHP, Scala, Dart, C#) | Declarations + `:start-end` line anchors; doc hints on 6 |
+| **Pattern/heuristic** | Everything else + generic fallback | Line-oriented patterns |
+
+Caps: 25 signatures/file · 8 members/block. Full details, known regex gaps, and what they mean for `verify`: **[KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md)**.
+
 ---
 
 ## License

package/gen-context.js

@@ -15195,7 +15195,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.25.0',
+    version: '8.26.1',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -18089,6 +18089,192 @@ __factories["./src/session/notes"] = function(module, exports) {
   
 };
 
+// ── ./src/skills/skills ──
+__factories["./src/skills/skills"] = function(module, exports) {
+  
+  /**
+   * sigmap skills — canonical agent playbooks + multi-client installer (F3+F4, #517).
+   *
+   * Two deterministic skill documents (the spend-minimizing usage loop and the
+   * config-optimizer playbook) emitted in each client's native skill/rules
+   * format — the `mcp/install.js` CLIENTS pattern applied to skills. File-based
+   * clients get sigmap-namespaced files we own outright; AGENTS.md (codex) gets
+   * a marker-delimited block inserted ABOVE the `## Auto-generated signatures`
+   * marker, since the codex adapter preserves content above it and replaces
+   * everything below. Idempotent; human content is never touched.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+
+  const START = '<!-- sigmap-skills:start -->';
+  const END = '<!-- sigmap-skills:end -->';
+  const SIGNATURES_MARKER = '## Auto-generated signatures';
+
+  const SKILLS = {
+    'sigmap-usage-maximizer': {
+      title: 'SigMap usage maximizer',
+      description: 'Spend-minimizing loop for agents in a SigMap-indexed repo: ask before reading, read ranges, verify before trusting, squeeze big pastes, checkpoint, watch the budget.',
+      body: [
+        'Follow this loop before any file exploration in a repo with SigMap installed.',
+        '',
+        '1. **Ask before reading.** `sigmap ask "<task>"` (or the `query_context` MCP tool) ranks the relevant files as ~hundreds of tokens of signatures instead of thousands of raw-file tokens. Never open files to "look around".',
+        '2. **Read ranges, not files.** Use the `get_lines` MCP tool with the `:start-end` line anchors carried on every signature to pull only the lines you need.',
+        '3. **Ground before trusting.** Run the `verify_suggestion` MCP tool (or `sigmap verify-ai-output`) on generated code before applying it — it flags fabricated files, imports, symbols, and npm scripts against the live index.',
+        '4. **Squeeze big pastes.** Any stack trace, CI/build log, or JSON blob goes through `sigmap squeeze` (or the `squeeze_output` MCP tool) before it enters context — the signal survives, the noise does not.',
+        '5. **Checkpoint progress.** Use the `create_checkpoint` MCP tool or `sigmap note "<decision>"` so a follow-up session resumes without re-deriving state.',
+        '6. **Watch the budget.** Check the `get_budget` MCP tool or `sigmap budget` (estimates from SigMap\'s local ledger — no LLM calls). Near the budget: summarize-then-drop older context instead of accumulating, and prefer terse output.',
+      ].join('\n'),
+    },
+    'sigmap-config-optimizer': {
+      title: 'SigMap config optimizer',
+      description: 'Playbook for getting a correct SigMap config on any repo: detect with sigmap tune, review the per-change reasons, apply, validate.',
+      body: [
+        'Playbook for configuring SigMap on a new or misconfigured repo.',
+        '',
+        '1. **Detect.** `sigmap tune` prints a recommended config diff — srcDirs pin, monorepo mode, adapters, excludes, budget — with one evidence-naming reason per change. Read-only.',
+        '2. **Review.** Every reason names its evidence (workspace marker, client artifact, vendored dir, file-count estimate). Explicit user config is never proposed against.',
+        '3. **Apply.** `sigmap tune --apply` merges the recommendations into `gen-context.config.json`, preserving every existing key. Idempotent — a second `tune` proposes nothing.',
+        '4. **Validate.** `sigmap validate` confirms the generated context matches the config; `sigmap doctor` diagnoses anything left.',
+      ].join('\n'),
+    },
+  };
+
+  // Client registry — parent = artifact whose presence means "user uses this
+  // client" (the `--setup` only-touch-existing rule for plain `skills install`).
+  const SKILL_CLIENTS = {
+    claude:   { label: 'Claude Code',    parent: ['.claude'],
+                target: (cwd, skill) => path.join(cwd, '.claude', 'skills', skill, 'SKILL.md') },
+    cursor:   { label: 'Cursor',         parent: ['.cursor'],
+                target: (cwd, skill) => path.join(cwd, '.cursor', 'rules', `${skill}.mdc`) },
+    windsurf: { label: 'Windsurf',       parent: ['.windsurf'],
+                target: (cwd, skill) => path.join(cwd, '.windsurf', 'rules', `${skill}.md`) },
+    copilot:  { label: 'GitHub Copilot', parent: ['.github'],
+                target: (cwd, skill) => path.join(cwd, '.github', 'instructions', `${skill}.instructions.md`) },
+    codex:    { label: 'Codex CLI (AGENTS.md)', parent: ['AGENTS.md'],
+                target: (cwd) => path.join(cwd, 'AGENTS.md'), inject: true },
+  };
+
+  function _footer(version) {
+    const ver = version ? ` v${version}` : '';
+    return `<sub>Generated by SigMap${ver} · run \`sigmap skills install\` to refresh.</sub>`;
+  }
+
+  /** Render one skill's client-specific file content. */
+  function renderSkill(client, skillName, version) {
+    const skill = SKILLS[skillName];
+    const body = `# ${skill.title}\n\n${skill.body}\n\n${_footer(version)}\n`;
+    if (client === 'claude') {
+      return `---\nname: ${skillName}\ndescription: ${skill.description}\n---\n\n${body}`;
+    }
+    if (client === 'cursor') {
+      return `---\ndescription: ${skill.description}\nalwaysApply: false\n---\n\n${body}`;
+    }
+    if (client === 'copilot') {
+      return `---\napplyTo: "**"\n---\n\n${body}`;
+    }
+    return body; // windsurf: plain markdown
+  }
+
+  /** Render the combined AGENTS.md block (both skills, marker-delimited). */
+  function renderAgentsBlock(version) {
+    const parts = [START, '## SigMap agent skills', ''];
+    for (const name of Object.keys(SKILLS)) {
+      parts.push(`### ${SKILLS[name].title}`, '', SKILLS[name].body, '');
+    }
+    parts.push(_footer(version), END);
+    return parts.join('\n');
+  }
+
+  /**
+   * Inject (or replace) the skills block in AGENTS.md content.
+   * A new block is inserted ABOVE the `## Auto-generated signatures` marker —
+   * the codex adapter's write() preserves content above that marker and
+   * replaces everything below it. Never touches content outside the markers.
+   */
+  function injectSkillsBlock(existing, block) {
+    const src = String(existing || '');
+    const startIdx = src.indexOf(START);
+    if (startIdx !== -1) {
+      const endIdx = src.indexOf(END, startIdx);
+      if (endIdx !== -1) {
+        return src.slice(0, startIdx) + block + src.slice(endIdx + END.length);
+      }
+    }
+    const sigIdx = src.indexOf(SIGNATURES_MARKER);
+    if (sigIdx !== -1) {
+      return src.slice(0, sigIdx) + block + '\n\n' + src.slice(sigIdx);
+    }
+    if (src.trim() === '') return block + '\n';
+    return src + (src.endsWith('\n') ? '\n' : '\n\n') + block + '\n';
+  }
+
+  function _writeIfChanged(filePath, content) {
+    if (fs.existsSync(filePath)) {
+      const existing = fs.readFileSync(filePath, 'utf8');
+      if (existing === content) return 'already';
+      fs.writeFileSync(filePath, content);
+      return 'updated';
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+    return 'installed';
+  }
+
+  /**
+   * Install both skills for one client.
+   * @returns {{ client, label, results: Array<{skill, path, status}> }}
+   *          status: 'installed' | 'updated' | 'already'; or { status:'unknown', valid } for a bad client.
+   */
+  function installSkills(client, opts = {}) {
+    const spec = SKILL_CLIENTS[client];
+    if (!spec) return { client, status: 'unknown', valid: Object.keys(SKILL_CLIENTS) };
+    const cwd = opts.cwd || process.cwd();
+    const version = opts.version || null;
+    const results = [];
+
+    if (spec.inject) {
+      const filePath = spec.target(cwd);
+      const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+      const next = injectSkillsBlock(existing, renderAgentsBlock(version));
+      let status;
+      if (next === existing) status = 'already';
+      else { fs.writeFileSync(filePath, next); status = existing ? 'updated' : 'installed'; }
+      results.push({ skill: Object.keys(SKILLS).join(' + '), path: filePath, status });
+    } else {
+      for (const skillName of Object.keys(SKILLS)) {
+        const filePath = spec.target(cwd, skillName);
+        results.push({ skill: skillName, path: filePath, status: _writeIfChanged(filePath, renderSkill(client, skillName, version)) });
+      }
+    }
+    return { client, label: spec.label, results };
+  }
+
+  /** True when the client's parent artifact exists (plain-install eligibility). */
+  function clientPresent(client, cwd) {
+    const spec = SKILL_CLIENTS[client];
+    return !!spec && fs.existsSync(path.join(cwd, ...spec.parent));
+  }
+
+  /** List clients with target paths, presence, and installed state. */
+  function listSkillClients(opts = {}) {
+    const cwd = opts.cwd || process.cwd();
+    return Object.keys(SKILL_CLIENTS).map((client) => {
+      const spec = SKILL_CLIENTS[client];
+      const targets = spec.inject
+        ? [spec.target(cwd)]
+        : Object.keys(SKILLS).map((s) => spec.target(cwd, s));
+      const installed = spec.inject
+        ? (fs.existsSync(targets[0]) && fs.readFileSync(targets[0], 'utf8').includes(START))
+        : targets.every((t) => fs.existsSync(t));
+      return { client, label: spec.label, present: clientPresent(client, cwd), installed, targets };
+    });
+  }
+
+  module.exports = { SKILLS, SKILL_CLIENTS, renderSkill, renderAgentsBlock, injectSkillsBlock, installSkills, listSkillClients, clientPresent, START, END };
+  
+};
+
 // ── ./src/squeeze/cilog ──
 __factories["./src/squeeze/cilog"] = function(module, exports) {
   
@@ -20621,7 +20807,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.25.0';
+const VERSION = '8.26.1';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -22511,6 +22697,8 @@ Usage:
   ${cmd} redact [file]                     Mask secrets in a file or stdin (10-pattern bank); redacted text to stdout (--json)
   ${cmd} tune                              Recommend config from repo detection — srcDirs, monorepo, adapters, exclude, budget (--json)
   ${cmd} tune --apply                      Write the recommendations into gen-context.config.json (merges; your keys preserved)
+  ${cmd} skills list                       List skill clients (Claude/Cursor/Windsurf/Copilot/AGENTS.md) and install state (--json)
+  ${cmd} skills install                    Install the SigMap agent playbooks for detected clients (--client <name> | --all)
   ${cmd} note "<text>"                     Append a note to the cross-session decision log
   ${cmd} note                              List recent notes (also: note --list <N>)
   ${cmd} status                            Show repo state — branch, dirty files, index freshness, notes
@@ -23940,6 +24128,64 @@ function main() {
     process.exit(0);
   }
 
+  // `sigmap skills list|install [--client <name>|--all] [--json]` — install the
+  // agent playbooks (usage-maximizer, config-optimizer) in each client's native
+  // skill/rules format. Plain `install` touches only clients whose parent
+  // artifact exists; --client/--all create. Idempotent.
+  if (args[0] === 'skills') {
+    const { installSkills, listSkillClients, SKILL_CLIENTS } = requireSourceOrBundled('./src/skills/skills');
+    const sub = args[1];
+    const jsonOut = args.includes('--json');
+
+    if (sub === 'list' || sub === undefined) {
+      const clients = listSkillClients({ cwd });
+      if (jsonOut) {
+        process.stdout.write(JSON.stringify(clients, null, 2) + '\n');
+        process.exit(0);
+      }
+      console.log('Supported skill clients:\n');
+      for (const c of clients) {
+        const state = c.installed ? 'installed' : (c.present ? 'client present, skills not installed' : 'client not detected');
+        console.log(`  ${c.client.padEnd(10)} ${c.label.padEnd(24)} ${state}`);
+        for (const t of c.targets) console.log(`             ${path.relative(cwd, t)}`);
+      }
+      console.log('\nInstall with: sigmap skills install [--client <name> | --all]');
+      process.exit(0);
+    }
+
+    if (sub === 'install') {
+      const cIdx = args.indexOf('--client');
+      const one = cIdx !== -1 ? args[cIdx + 1] : null;
+      let targets;
+      if (one) targets = [one];
+      else if (args.includes('--all')) targets = Object.keys(SKILL_CLIENTS);
+      else targets = listSkillClients({ cwd }).filter((c) => c.present).map((c) => c.client);
+      if (targets.length === 0) {
+        console.error('[sigmap] skills: no clients detected — use --client <name> or --all (see: sigmap skills list)');
+        process.exit(1);
+      }
+      const out = targets.map((c) => installSkills(c, { cwd, version: VERSION }));
+      const bad = out.find((r) => r.status === 'unknown');
+      if (bad) {
+        console.error(`[sigmap] skills: unknown client "${bad.client}" — valid: ${bad.valid.join(', ')}`);
+        process.exit(1);
+      }
+      if (jsonOut) {
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+        process.exit(0);
+      }
+      for (const r of out) {
+        for (const res of r.results) {
+          console.log(`  ${r.client.padEnd(10)} ${res.status.padEnd(10)} ${path.relative(cwd, res.path)}`);
+        }
+      }
+      process.exit(0);
+    }
+
+    console.error('[sigmap] usage: sigmap skills [list | install [--client <name> | --all]] [--json]');
+    process.exit(1);
+  }
+
   // `sigmap note "<text>"` — append to the cross-session decision log.
   // With no text, lists recent notes (also `note --list [N]`).
   // `sigmap memory` — one view over the cross-session stores in .context/.

package/llms-full.txt

@@ -11,13 +11,13 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.25.0 | Benchmark: sigmap-v8.25-main (2026-08-17)
+# Version: 8.26.1 | Benchmark: sigmap-v8.26-main (2026-08-17)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v8.25-main, 2026-08-17)
+## Core metrics (benchmark: sigmap-v8.26-main, 2026-08-17)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
@@ -130,6 +130,8 @@ sigmap budget --budget <tokens>          One-off budget override (config: sessio
 sigmap redact [file]                     Mask secrets in a file or stdin (10-pattern bank); redacted text to stdout (--json)
 sigmap tune                              Recommend config from repo detection — srcDirs, monorepo, adapters, exclude, budget (--json)
 sigmap tune --apply                      Write the recommendations into gen-context.config.json (merges; your keys preserved)
+sigmap skills list                       List skill clients (Claude/Cursor/Windsurf/Copilot/AGENTS.md) and install state (--json)
+sigmap skills install                    Install the SigMap agent playbooks for detected clients (--client <name> | --all)
 sigmap note "<text>"                     Append a note to the cross-session decision log
 sigmap note                              List recent notes (also: note --list <N>)
 sigmap status                            Show repo state — branch, dirty files, index freshness, notes

package/llms.txt

@@ -11,7 +11,7 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.25.0 | Benchmark: sigmap-v8.25-main (2026-08-17)
+# Version: 8.26.1 | Benchmark: sigmap-v8.26-main (2026-08-17)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -23,7 +23,7 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v8.25-main, 2026-08-17)
+## Core metrics (benchmark: sigmap-v8.26-main, 2026-08-17)
 
 - hit@5 retrieval: 82.2% vs 44.0% single-shot grep baseline (1.87× lift)
 - Token reduction: 96.8% average across benchmark repos

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "8.25.0",
+  "version": "8.26.1",
   "description": "The deterministic, verifiable grounding layer for AI code work — a zero-dependency signature-and-evidence map that grounds Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP agents against your real code (repo + installed libraries) so they stop hallucinating files, imports & APIs. Runs offline via npx; byte-stable output; ~97% token reduction as proof.",
   "main": "packages/core/index.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "8.25.0",
+  "version": "8.26.1",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "8.25.0",
+  "version": "8.26.1",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '8.25.0',
+  version: '8.26.1',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/skills/skills.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * sigmap skills — canonical agent playbooks + multi-client installer (F3+F4, #517).
+ *
+ * Two deterministic skill documents (the spend-minimizing usage loop and the
+ * config-optimizer playbook) emitted in each client's native skill/rules
+ * format — the `mcp/install.js` CLIENTS pattern applied to skills. File-based
+ * clients get sigmap-namespaced files we own outright; AGENTS.md (codex) gets
+ * a marker-delimited block inserted ABOVE the `## Auto-generated signatures`
+ * marker, since the codex adapter preserves content above it and replaces
+ * everything below. Idempotent; human content is never touched.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const START = '<!-- sigmap-skills:start -->';
+const END = '<!-- sigmap-skills:end -->';
+const SIGNATURES_MARKER = '## Auto-generated signatures';
+
+const SKILLS = {
+  'sigmap-usage-maximizer': {
+    title: 'SigMap usage maximizer',
+    description: 'Spend-minimizing loop for agents in a SigMap-indexed repo: ask before reading, read ranges, verify before trusting, squeeze big pastes, checkpoint, watch the budget.',
+    body: [
+      'Follow this loop before any file exploration in a repo with SigMap installed.',
+      '',
+      '1. **Ask before reading.** `sigmap ask "<task>"` (or the `query_context` MCP tool) ranks the relevant files as ~hundreds of tokens of signatures instead of thousands of raw-file tokens. Never open files to "look around".',
+      '2. **Read ranges, not files.** Use the `get_lines` MCP tool with the `:start-end` line anchors carried on every signature to pull only the lines you need.',
+      '3. **Ground before trusting.** Run the `verify_suggestion` MCP tool (or `sigmap verify-ai-output`) on generated code before applying it — it flags fabricated files, imports, symbols, and npm scripts against the live index.',
+      '4. **Squeeze big pastes.** Any stack trace, CI/build log, or JSON blob goes through `sigmap squeeze` (or the `squeeze_output` MCP tool) before it enters context — the signal survives, the noise does not.',
+      '5. **Checkpoint progress.** Use the `create_checkpoint` MCP tool or `sigmap note "<decision>"` so a follow-up session resumes without re-deriving state.',
+      '6. **Watch the budget.** Check the `get_budget` MCP tool or `sigmap budget` (estimates from SigMap\'s local ledger — no LLM calls). Near the budget: summarize-then-drop older context instead of accumulating, and prefer terse output.',
+    ].join('\n'),
+  },
+  'sigmap-config-optimizer': {
+    title: 'SigMap config optimizer',
+    description: 'Playbook for getting a correct SigMap config on any repo: detect with sigmap tune, review the per-change reasons, apply, validate.',
+    body: [
+      'Playbook for configuring SigMap on a new or misconfigured repo.',
+      '',
+      '1. **Detect.** `sigmap tune` prints a recommended config diff — srcDirs pin, monorepo mode, adapters, excludes, budget — with one evidence-naming reason per change. Read-only.',
+      '2. **Review.** Every reason names its evidence (workspace marker, client artifact, vendored dir, file-count estimate). Explicit user config is never proposed against.',
+      '3. **Apply.** `sigmap tune --apply` merges the recommendations into `gen-context.config.json`, preserving every existing key. Idempotent — a second `tune` proposes nothing.',
+      '4. **Validate.** `sigmap validate` confirms the generated context matches the config; `sigmap doctor` diagnoses anything left.',
+    ].join('\n'),
+  },
+};
+
+// Client registry — parent = artifact whose presence means "user uses this
+// client" (the `--setup` only-touch-existing rule for plain `skills install`).
+const SKILL_CLIENTS = {
+  claude:   { label: 'Claude Code',    parent: ['.claude'],
+              target: (cwd, skill) => path.join(cwd, '.claude', 'skills', skill, 'SKILL.md') },
+  cursor:   { label: 'Cursor',         parent: ['.cursor'],
+              target: (cwd, skill) => path.join(cwd, '.cursor', 'rules', `${skill}.mdc`) },
+  windsurf: { label: 'Windsurf',       parent: ['.windsurf'],
+              target: (cwd, skill) => path.join(cwd, '.windsurf', 'rules', `${skill}.md`) },
+  copilot:  { label: 'GitHub Copilot', parent: ['.github'],
+              target: (cwd, skill) => path.join(cwd, '.github', 'instructions', `${skill}.instructions.md`) },
+  codex:    { label: 'Codex CLI (AGENTS.md)', parent: ['AGENTS.md'],
+              target: (cwd) => path.join(cwd, 'AGENTS.md'), inject: true },
+};
+
+function _footer(version) {
+  const ver = version ? ` v${version}` : '';
+  return `<sub>Generated by SigMap${ver} · run \`sigmap skills install\` to refresh.</sub>`;
+}
+
+/** Render one skill's client-specific file content. */
+function renderSkill(client, skillName, version) {
+  const skill = SKILLS[skillName];
+  const body = `# ${skill.title}\n\n${skill.body}\n\n${_footer(version)}\n`;
+  if (client === 'claude') {
+    return `---\nname: ${skillName}\ndescription: ${skill.description}\n---\n\n${body}`;
+  }
+  if (client === 'cursor') {
+    return `---\ndescription: ${skill.description}\nalwaysApply: false\n---\n\n${body}`;
+  }
+  if (client === 'copilot') {
+    return `---\napplyTo: "**"\n---\n\n${body}`;
+  }
+  return body; // windsurf: plain markdown
+}
+
+/** Render the combined AGENTS.md block (both skills, marker-delimited). */
+function renderAgentsBlock(version) {
+  const parts = [START, '## SigMap agent skills', ''];
+  for (const name of Object.keys(SKILLS)) {
+    parts.push(`### ${SKILLS[name].title}`, '', SKILLS[name].body, '');
+  }
+  parts.push(_footer(version), END);
+  return parts.join('\n');
+}
+
+/**
+ * Inject (or replace) the skills block in AGENTS.md content.
+ * A new block is inserted ABOVE the `## Auto-generated signatures` marker —
+ * the codex adapter's write() preserves content above that marker and
+ * replaces everything below it. Never touches content outside the markers.
+ */
+function injectSkillsBlock(existing, block) {
+  const src = String(existing || '');
+  const startIdx = src.indexOf(START);
+  if (startIdx !== -1) {
+    const endIdx = src.indexOf(END, startIdx);
+    if (endIdx !== -1) {
+      return src.slice(0, startIdx) + block + src.slice(endIdx + END.length);
+    }
+  }
+  const sigIdx = src.indexOf(SIGNATURES_MARKER);
+  if (sigIdx !== -1) {
+    return src.slice(0, sigIdx) + block + '\n\n' + src.slice(sigIdx);
+  }
+  if (src.trim() === '') return block + '\n';
+  return src + (src.endsWith('\n') ? '\n' : '\n\n') + block + '\n';
+}
+
+function _writeIfChanged(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, 'utf8');
+    if (existing === content) return 'already';
+    fs.writeFileSync(filePath, content);
+    return 'updated';
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return 'installed';
+}
+
+/**
+ * Install both skills for one client.
+ * @returns {{ client, label, results: Array<{skill, path, status}> }}
+ *          status: 'installed' | 'updated' | 'already'; or { status:'unknown', valid } for a bad client.
+ */
+function installSkills(client, opts = {}) {
+  const spec = SKILL_CLIENTS[client];
+  if (!spec) return { client, status: 'unknown', valid: Object.keys(SKILL_CLIENTS) };
+  const cwd = opts.cwd || process.cwd();
+  const version = opts.version || null;
+  const results = [];
+
+  if (spec.inject) {
+    const filePath = spec.target(cwd);
+    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    const next = injectSkillsBlock(existing, renderAgentsBlock(version));
+    let status;
+    if (next === existing) status = 'already';
+    else { fs.writeFileSync(filePath, next); status = existing ? 'updated' : 'installed'; }
+    results.push({ skill: Object.keys(SKILLS).join(' + '), path: filePath, status });
+  } else {
+    for (const skillName of Object.keys(SKILLS)) {
+      const filePath = spec.target(cwd, skillName);
+      results.push({ skill: skillName, path: filePath, status: _writeIfChanged(filePath, renderSkill(client, skillName, version)) });
+    }
+  }
+  return { client, label: spec.label, results };
+}
+
+/** True when the client's parent artifact exists (plain-install eligibility). */
+function clientPresent(client, cwd) {
+  const spec = SKILL_CLIENTS[client];
+  return !!spec && fs.existsSync(path.join(cwd, ...spec.parent));
+}
+
+/** List clients with target paths, presence, and installed state. */
+function listSkillClients(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  return Object.keys(SKILL_CLIENTS).map((client) => {
+    const spec = SKILL_CLIENTS[client];
+    const targets = spec.inject
+      ? [spec.target(cwd)]
+      : Object.keys(SKILLS).map((s) => spec.target(cwd, s));
+    const installed = spec.inject
+      ? (fs.existsSync(targets[0]) && fs.readFileSync(targets[0], 'utf8').includes(START))
+      : targets.every((t) => fs.existsSync(t));
+    return { client, label: spec.label, present: clientPresent(client, cwd), installed, targets };
+  });
+}
+
+module.exports = { SKILLS, SKILL_CLIENTS, renderSkill, renderAgentsBlock, injectSkillsBlock, installSkills, listSkillClients, clientPresent, START, END };