clementine-agent 1.0.58 → 1.0.60

package/dist/agent/assistant.js

@@ -1423,6 +1423,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             mcpTool('list_allowed_tools'),
             mcpTool('disallow_tool'),
             mcpTool('refresh_tool_inventory'),
+            mcpTool('refresh_skills'),
             mcpTool('self_restart'),
             mcpTool('self_update'),
             mcpTool('where_is_source'),

package/dist/agent/auto-skills.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Auto-synthesize a skill document for every tool discovered via MCP
+ * schema fetching. Pure schema → markdown transform, no LLM call.
+ *
+ * User-authored skills under `skills/<name>.md` (top-level) always win
+ * on retrieval over auto-generated skills under `skills/auto/<server>/<tool>.md`.
+ * A user can shadow any auto-skill by dropping a hand-written file at
+ * top level — same triggers, their version serves.
+ *
+ * Regeneration: each auto-skill's frontmatter includes a `schemaHash`
+ * computed from the tool's inputSchema. On every boot we diff and only
+ * rewrite skills whose hash changed. User edits to auto-skills aren't
+ * preserved — they should shadow, not edit.
+ */
+import type { AllSchemas } from './mcp-schemas.js';
+/**
+ * Given the fetched schemas, write one auto-skill per tool. Idempotent —
+ * only writes when the schema hash changes or the file is missing.
+ * Prunes stale auto-skills for tools the server no longer declares.
+ */
+export declare function synthesizeSkillsFromSchemas(schemas: AllSchemas): {
+    written: number;
+    unchanged: number;
+    pruned: number;
+    toolCount: number;
+};
+//# sourceMappingURL=auto-skills.d.ts.map

package/dist/agent/auto-skills.js

@@ -0,0 +1,298 @@
+/**
+ * Auto-synthesize a skill document for every tool discovered via MCP
+ * schema fetching. Pure schema → markdown transform, no LLM call.
+ *
+ * User-authored skills under `skills/<name>.md` (top-level) always win
+ * on retrieval over auto-generated skills under `skills/auto/<server>/<tool>.md`.
+ * A user can shadow any auto-skill by dropping a hand-written file at
+ * top level — same triggers, their version serves.
+ *
+ * Regeneration: each auto-skill's frontmatter includes a `schemaHash`
+ * computed from the tool's inputSchema. On every boot we diff and only
+ * rewrite skills whose hash changed. User edits to auto-skills aren't
+ * preserved — they should shadow, not edit.
+ */
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from 'node:fs';
+import matter from 'gray-matter';
+import { VAULT_DIR } from '../config.js';
+import { logger } from '../tools/shared.js';
+import { loadToolInventory } from './mcp-bridge.js';
+const SKILLS_ROOT = path.join(VAULT_DIR, '00-System', 'skills');
+const AUTO_ROOT = path.join(SKILLS_ROOT, 'auto');
+function schemaHash(schema) {
+    return createHash('sha1').update(JSON.stringify(schema ?? {})).digest('hex').slice(0, 16);
+}
+/**
+ * Split a snake_case/camelCase identifier into readable words.
+ * `read_imessages` → "read imessages", `pageSize` → "page size"
+ */
+function humanize(s) {
+    return s
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .toLowerCase()
+        .trim();
+}
+/**
+ * Derive trigger phrases a user might use to invoke this tool. Every trigger
+ * must include the server name (or a server-specific noun derived from the
+ * tool name) so generic verbs like "list", "check", "read" don't trip skills
+ * across all connectors. The server name is the disambiguator.
+ */
+function deriveTriggers(server, tool) {
+    // Normalize the server name for use in triggers. claude_ai_Google_Drive →
+    // "google drive"; Bright_Data → "bright data"; imessage → "imessage".
+    const rawServer = server.replace(/^claude_ai_/, '');
+    const serverWords = humanize(rawServer);
+    const toolWords = humanize(tool.name);
+    // Alias shortening for common server names so user phrasings match.
+    // "Google Drive" → also match "drive", "Microsoft 365" → also match "outlook", etc.
+    const serverAliases = new Set([serverWords]);
+    const aliasMap = {
+        'google drive': ['drive', 'gdrive', 'google drive'],
+        'google calendar': ['calendar', 'gcal'],
+        'gmail': ['gmail', 'email', 'mail'],
+        'microsoft 365': ['outlook', 'microsoft', 'office'],
+        'imessage': ['imessage', 'messages', 'texts', 'text messages', 'sms'],
+        'figma': ['figma', 'design'],
+        'hostinger-mcp': ['hostinger'],
+        'bright data': ['brightdata'],
+        'dataforseo': ['seo', 'serp'],
+        'elevenlabs': ['voice', 'tts', 'text to speech'],
+        'supabase': ['database', 'postgres'],
+    };
+    for (const alias of aliasMap[serverWords] ?? [])
+        serverAliases.add(alias);
+    const triggers = new Set();
+    // Every trigger is a phrase, not a single generic verb. The server name
+    // (or an alias) is always present to scope the match to this connector.
+    for (const alias of serverAliases) {
+        triggers.add(`${toolWords} ${alias}`);
+        triggers.add(`${alias} ${toolWords}`);
+        // Natural phrasings a user would actually type
+        triggers.add(`my ${alias}`);
+        triggers.add(`check ${alias}`);
+        // If the tool name starts with a verb (read/send/list/get/search/create/
+        // update/delete/list), pair it with the alias for a clean trigger.
+        const firstWord = toolWords.split(/\s+/)[0];
+        if (['read', 'send', 'list', 'get', 'search', 'create', 'update', 'delete', 'find', 'show'].includes(firstWord)) {
+            triggers.add(`${firstWord} ${alias}`);
+            triggers.add(`${firstWord} my ${alias}`);
+        }
+    }
+    // The server name alone is a useful single-word trigger (e.g. "imessage")
+    // — specific enough to not overmatch generic tool-list queries.
+    for (const alias of serverAliases)
+        triggers.add(alias);
+    return Array.from(triggers).filter(t => t.length > 0);
+}
+function renderArgsTable(schema) {
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    const entries = Object.entries(props);
+    if (entries.length === 0)
+        return '_No arguments._';
+    const rows = entries.map(([name, spec]) => {
+        const type = spec.type ?? 'any';
+        const req = required.has(name) ? '**required**' : 'optional';
+        const enumHint = Array.isArray(spec.enum) && spec.enum.length > 0
+            ? ` (one of: ${spec.enum.map(v => `\`${v}\``).join(', ')})`
+            : '';
+        const desc = (spec.description ?? '').replace(/\n/g, ' ').slice(0, 140);
+        return `| \`${name}\` | \`${type}\` | ${req} | ${desc}${enumHint} |`;
+    });
+    return ['| Arg | Type | Required | Description |', '|-----|------|----------|-------------|', ...rows].join('\n');
+}
+function renderExample(schema) {
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    const example = {};
+    for (const [name, spec] of Object.entries(props)) {
+        if (!required.has(name) && Object.keys(example).length >= 2)
+            continue;
+        switch (spec.type) {
+            case 'string':
+                example[name] = Array.isArray(spec.enum) && spec.enum.length > 0 ? spec.enum[0] : `<${name}>`;
+                break;
+            case 'number':
+            case 'integer':
+                example[name] = 3;
+                break;
+            case 'boolean':
+                example[name] = true;
+                break;
+            case 'array':
+                example[name] = [];
+                break;
+            default:
+                example[name] = null;
+        }
+    }
+    return Object.keys(example).length > 0
+        ? '```json\n' + JSON.stringify(example, null, 2) + '\n```'
+        : '```json\n{}\n```';
+}
+function renderSkillBody(server, tool) {
+    const fullName = `mcp__${server}__${tool.name}`;
+    const schema = tool.inputSchema ?? { type: 'object', properties: {} };
+    return [
+        `# ${humanize(server)} — ${humanize(tool.name)}`,
+        '',
+        tool.description || '_(no description provided by the server)_',
+        '',
+        '## Tool call',
+        '',
+        `\`${fullName}\``,
+        '',
+        '## Arguments',
+        '',
+        renderArgsTable(schema),
+        '',
+        '## Minimal example',
+        '',
+        renderExample(schema),
+        '',
+        '## Notes',
+        '',
+        '- The arg names above come directly from the MCP server\'s `tools/list` schema — use them exactly. If a call returns an error like "unknown field", the error text names the allowed args; correct the call and retry.',
+        '- Per-call errors (invalid args, auth, rate limits) are not connector failures. Do not declare the connector "broken" or "unavailable" unless the MCP server itself is unreachable.',
+        '',
+        '---',
+        '',
+        `*Auto-generated from the MCP server\'s schema. To override, create \`skills/<your-slug>.md\` at the top level with your own triggers — user skills take precedence at retrieval time.*`,
+    ].join('\n');
+}
+function writeAutoSkill(server, tool) {
+    const serverDir = path.join(AUTO_ROOT, sanitizePathSegment(server));
+    if (!existsSync(serverDir))
+        mkdirSync(serverDir, { recursive: true });
+    const filePath = path.join(serverDir, `${sanitizePathSegment(tool.name)}.md`);
+    const hash = schemaHash(tool.inputSchema);
+    const now = new Date().toISOString();
+    const frontmatter = {
+        title: `${humanize(server)} — ${humanize(tool.name)}`,
+        description: tool.description || `Auto-generated skill for ${tool.name}`,
+        triggers: deriveTriggers(server, tool),
+        source: 'auto-mcp-schema',
+        server,
+        tool: `mcp__${server}__${tool.name}`,
+        schemaHash: hash,
+        generatedAt: now,
+    };
+    // Skip write if hash matches existing.
+    if (existsSync(filePath)) {
+        try {
+            const existing = matter(readFileSync(filePath, 'utf-8'));
+            if (existing.data.schemaHash === hash) {
+                return { wrote: false, unchanged: true };
+            }
+        }
+        catch { /* regen on parse error */ }
+    }
+    const content = matter.stringify('\n' + renderSkillBody(server, tool) + '\n', frontmatter);
+    writeFileSync(filePath, content);
+    return { wrote: true, unchanged: false };
+}
+/** Safe path segment — strip anything that isn't alphanum/dash/dot/underscore. */
+function sanitizePathSegment(s) {
+    return s.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 80);
+}
+/**
+ * Given the fetched schemas, write one auto-skill per tool. Idempotent —
+ * only writes when the schema hash changes or the file is missing.
+ * Prunes stale auto-skills for tools the server no longer declares.
+ */
+export function synthesizeSkillsFromSchemas(schemas) {
+    let written = 0;
+    let unchanged = 0;
+    let pruned = 0;
+    let toolCount = 0;
+    if (!existsSync(AUTO_ROOT))
+        mkdirSync(AUTO_ROOT, { recursive: true });
+    // Current tools we expect to exist on disk
+    const expected = new Set();
+    // Phase 1: full-schema skills from stdio probes.
+    for (const [server, s] of Object.entries(schemas.servers)) {
+        if (!s.tools || s.tools.length === 0)
+            continue;
+        for (const tool of s.tools) {
+            toolCount++;
+            const res = writeAutoSkill(server, tool);
+            if (res.wrote)
+                written++;
+            if (res.unchanged)
+                unchanged++;
+            expected.add(`${sanitizePathSegment(server)}/${sanitizePathSegment(tool.name)}.md`);
+        }
+    }
+    // Phase 2: minimal skills for remote connectors (claude_ai_*, etc.) whose
+    // schemas we couldn't fetch directly — we only have the tool name from
+    // the SDK inventory. The skill has no args table, but triggers still
+    // derive from tool name + server alias so retrieval works. Users can
+    // override with a hand-written skill at skills/<name>.md.
+    try {
+        const inv = loadToolInventory();
+        if (inv?.tools) {
+            const knownServers = new Set(Object.keys(schemas.servers));
+            for (const fullName of inv.tools) {
+                const m = fullName.match(/^mcp__([^_]+(?:_[^_]+)*)__(.+)$/);
+                if (!m)
+                    continue;
+                const [, server, toolName] = m;
+                // Skip if the stdio probe already wrote a full-schema skill.
+                if (knownServers.has(server))
+                    continue;
+                // Skip Clementine's own server + plugin tools (both documented elsewhere).
+                if (server === 'clementine-tools' || server.startsWith('plugin_'))
+                    continue;
+                const tool = {
+                    name: toolName,
+                    description: '',
+                    inputSchema: { type: 'object', properties: {} },
+                };
+                const res = writeAutoSkill(server, tool);
+                if (res.wrote)
+                    written++;
+                if (res.unchanged)
+                    unchanged++;
+                toolCount++;
+                expected.add(`${sanitizePathSegment(server)}/${sanitizePathSegment(toolName)}.md`);
+            }
+        }
+    }
+    catch (err) {
+        logger.debug({ err }, 'Minimal-skill pass (remote connectors) failed — non-fatal');
+    }
+    // Phase 3: single prune pass. Walk skills/auto/ and remove any .md whose
+    // path isn't in `expected`. We never touch anything outside skills/auto/,
+    // so user-authored top-level skills are preserved.
+    try {
+        if (existsSync(AUTO_ROOT)) {
+            for (const serverDir of readdirSync(AUTO_ROOT, { withFileTypes: true })) {
+                if (!serverDir.isDirectory())
+                    continue;
+                const dir = path.join(AUTO_ROOT, serverDir.name);
+                for (const file of readdirSync(dir)) {
+                    if (!file.endsWith('.md'))
+                        continue;
+                    const rel = `${serverDir.name}/${file}`;
+                    if (!expected.has(rel)) {
+                        try {
+                            rmSync(path.join(dir, file));
+                            pruned++;
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Auto-skill prune pass failed (non-fatal)');
+    }
+    logger.info({ written, unchanged, pruned, toolCount }, 'Auto-skills synthesized from MCP schemas');
+    return { written, unchanged, pruned, toolCount };
+}
+//# sourceMappingURL=auto-skills.js.map

package/dist/agent/contradiction-validator.js

@@ -15,7 +15,7 @@
 const ARG_ERROR_RE = /\b(invalid|unknown field|required|missing parameter|schema|unrecognized|unexpected property)\b/i;
 const AUTH_ERROR_RE = /\b(unauthori[sz]ed|401|not authenticated|token expired|token has expired|invalid[_ ]?token|access denied)\b/i;
 /** Regex matching reply phrasings that claim a connector-wide failure. */
-export const CONTRADICTION_RE = /(dead\s*end|doesn'?t exist|not in (the |my )?schema|schema[- ]level|not available|isn'?t loaded|tools array is empty|MCP server still connecting|connector is (a )?dead|no such tool available|tool doesn't exist)/i;
+export const CONTRADICTION_RE = /(dead\s*end|doesn'?t exist|not in (the |my )?schema|schema[- ]level|aren'?t loading into|(not|isn'?t|aren'?t) (loaded|wired|available|coming through|responding)|connector[^.]{0,40}(dropped|is (a )?dead)|tools? array is empty|MCP server (still connecting|dropped|not responding)|no such tool available|tool doesn'?t exist|both directions are blocked)/i;
 export function classifyResult(content, isError) {
     if (!isError)
         return 'success';
@@ -101,7 +101,13 @@ export function detectContradiction(reply, calls) {
     const match = reply.match(CONTRADICTION_RE);
     if (!match)
         return null;
-    const connectorCalls = calls.filter(c => c.name.startsWith('mcp__claude_ai_'));
+    // Cover every connector — claude_ai_* (remote), imessage/figma/hostinger/etc.
+    // (Desktop Extensions + stdio servers), everything except Clementine's own
+    // tools server and plugins. Earlier versions only filtered claude_ai_*,
+    // which let "isn't loaded" replies slip through for iMessage etc.
+    const connectorCalls = calls.filter(c => c.name.startsWith('mcp__') &&
+        !c.name.startsWith('mcp__clementine-tools__') &&
+        !c.name.startsWith('mcp__plugin_'));
     const recoverable = connectorCalls.find(c => c.resultClass === 'success' || c.resultClass === 'arg_error');
     if (!recoverable)
         return null;

package/dist/agent/mcp-schemas.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-server MCP schema fetcher.
+ *
+ * Spawns each discovered stdio MCP server, issues `initialize` + `tools/list`,
+ * captures the full inputSchema per tool, and writes everything to
+ * `~/.clementine/.tool-schemas.json`. Per-server 10s timeout so one flaky
+ * server doesn't block the rest.
+ *
+ * Why per-server instead of one big SDK probe: the SDK's init message only
+ * returns tool name strings, not schemas. And the SDK probe is flaky under
+ * concurrent MCP server spawn — iMessage routinely missed the init window.
+ * Direct per-server probes are deterministic and give us canonical schemas.
+ *
+ * This is the ground-truth source for auto-skill synthesis downstream.
+ */
+export interface ToolSchema {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+export interface ServerSchemas {
+    /** How the server was spawned — for regenerate-on-change detection */
+    command?: string;
+    args?: string[];
+    /** ISO timestamp of last successful fetch */
+    fetchedAt: string;
+    /** Tools the server declared */
+    tools: ToolSchema[];
+    /** Set when the probe failed; diagnostic only */
+    error?: string;
+}
+export interface AllSchemas {
+    fetchedAt: string;
+    servers: Record<string, ServerSchemas>;
+}
+/** Load cached schemas from disk, or null if not yet fetched. */
+export declare function loadSchemas(): AllSchemas | null;
+/**
+ * Fetch schemas from every discovered stdio server in parallel.
+ * Merges with any existing cache — servers that errored this round keep
+ * their last successful schemas (fail-soft).
+ */
+export declare function fetchAllSchemas(): Promise<AllSchemas>;
+/** Flat list of every tool with its schema and originating server. */
+export declare function flattenSchemas(all: AllSchemas): Array<{
+    server: string;
+    tool: ToolSchema;
+}>;
+//# sourceMappingURL=mcp-schemas.d.ts.map

package/dist/agent/mcp-schemas.js

@@ -0,0 +1,150 @@
+/**
+ * Per-server MCP schema fetcher.
+ *
+ * Spawns each discovered stdio MCP server, issues `initialize` + `tools/list`,
+ * captures the full inputSchema per tool, and writes everything to
+ * `~/.clementine/.tool-schemas.json`. Per-server 10s timeout so one flaky
+ * server doesn't block the rest.
+ *
+ * Why per-server instead of one big SDK probe: the SDK's init message only
+ * returns tool name strings, not schemas. And the SDK probe is flaky under
+ * concurrent MCP server spawn — iMessage routinely missed the init window.
+ * Direct per-server probes are deterministic and give us canonical schemas.
+ *
+ * This is the ground-truth source for auto-skill synthesis downstream.
+ */
+import path from 'node:path';
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { BASE_DIR } from '../config.js';
+import { logger } from '../tools/shared.js';
+import { discoverMcpServers } from './mcp-bridge.js';
+const SCHEMAS_FILE = path.join(BASE_DIR, '.tool-schemas.json');
+const PER_SERVER_TIMEOUT_MS = 10_000;
+/** Load cached schemas from disk, or null if not yet fetched. */
+export function loadSchemas() {
+    try {
+        if (!existsSync(SCHEMAS_FILE))
+            return null;
+        return JSON.parse(readFileSync(SCHEMAS_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveSchemas(s) {
+    try {
+        writeFileSync(SCHEMAS_FILE, JSON.stringify(s, null, 2));
+    }
+    catch (err) {
+        logger.warn({ err }, 'Failed to persist .tool-schemas.json');
+    }
+}
+/** Fetch schemas from a single stdio server. Returns null if it failed/timed out. */
+async function fetchOneServer(name, command, args, env) {
+    const started = Date.now();
+    let client = null;
+    let transport = null;
+    try {
+        transport = new StdioClientTransport({
+            command,
+            args,
+            env: { ...process.env, ...env },
+            stderr: 'ignore',
+        });
+        client = new Client({ name: 'clementine-schema-probe', version: '1.0.0' }, { capabilities: {} });
+        // Race the connect+list against a timeout. stdio servers that hang or
+        // crash on startup shouldn't block the whole discovery pass.
+        const work = (async () => {
+            await client.connect(transport);
+            const listed = await client.listTools();
+            return listed.tools;
+        })();
+        const timeout = new Promise((_, rej) => setTimeout(() => rej(new Error(`timeout after ${PER_SERVER_TIMEOUT_MS}ms`)), PER_SERVER_TIMEOUT_MS));
+        const tools = await Promise.race([work, timeout]);
+        logger.debug({ server: name, toolCount: tools.length, ms: Date.now() - started }, 'Fetched MCP schemas');
+        return {
+            command,
+            args,
+            fetchedAt: new Date().toISOString(),
+            tools: tools.map((t) => ({
+                name: t.name,
+                description: t.description ?? '',
+                inputSchema: t.inputSchema ?? { type: 'object', properties: {} },
+            })),
+        };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        logger.debug({ server: name, err: errMsg, ms: Date.now() - started }, 'MCP schema fetch failed');
+        return {
+            command,
+            args,
+            fetchedAt: new Date().toISOString(),
+            tools: [],
+            error: errMsg,
+        };
+    }
+    finally {
+        try {
+            await client?.close();
+        }
+        catch { /* ignore */ }
+        try {
+            await transport?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Fetch schemas from every discovered stdio server in parallel.
+ * Merges with any existing cache — servers that errored this round keep
+ * their last successful schemas (fail-soft).
+ */
+export async function fetchAllSchemas() {
+    const existing = loadSchemas();
+    const result = {
+        fetchedAt: new Date().toISOString(),
+        servers: { ...(existing?.servers ?? {}) },
+    };
+    const servers = discoverMcpServers().filter(s => s.enabled && s.type === 'stdio' && s.command);
+    if (servers.length === 0) {
+        saveSchemas(result);
+        return result;
+    }
+    const fetches = servers.map(async (s) => {
+        const fetched = await fetchOneServer(s.name, s.command, s.args ?? [], s.env ?? {});
+        return { name: s.name, fetched };
+    });
+    const settled = await Promise.allSettled(fetches);
+    let ok = 0, failed = 0;
+    for (const r of settled) {
+        if (r.status !== 'fulfilled' || !r.value.fetched) {
+            failed++;
+            continue;
+        }
+        const { name, fetched } = r.value;
+        // Only overwrite on success — preserve last-good schemas on transient failure.
+        if (fetched.tools.length > 0 || !result.servers[name]) {
+            result.servers[name] = fetched;
+        }
+        if (fetched.error)
+            failed++;
+        else
+            ok++;
+    }
+    logger.info({ ok, failed, total: servers.length }, 'MCP schema fetch pass complete');
+    saveSchemas(result);
+    return result;
+}
+/** Flat list of every tool with its schema and originating server. */
+export function flattenSchemas(all) {
+    const out = [];
+    for (const [server, s] of Object.entries(all.servers)) {
+        for (const tool of s.tools)
+            out.push({ server, tool });
+    }
+    return out;
+}
+//# sourceMappingURL=mcp-schemas.js.map

package/dist/agent/skill-extractor.js

@@ -324,6 +324,42 @@ async function mergeSkill(assistant, existing, incoming) {
  * edits require a restart, same as the rest of the skill pipeline).
  */
 const skillEmbeddingCache = new Map();
+/**
+ * Recursively list every .md skill file under `dir`. Returns absolute
+ * paths, relative paths (for dedupe/naming), and an `isAuto` flag set
+ * when the file lives under an `auto/` subtree. Used so auto-generated
+ * MCP skills under `skills/auto/<server>/<tool>.md` surface in search
+ * while user-authored top-level skills win on score tiebreak.
+ */
+function walkSkillFiles(root) {
+    const out = [];
+    function walk(dir, rel) {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            const name = ent.name;
+            // Skip backup files and hidden files
+            if (name.endsWith('.bak') || name.startsWith('.'))
+                continue;
+            const full = path.join(dir, name);
+            const nextRel = rel ? path.join(rel, name) : name;
+            if (ent.isDirectory()) {
+                walk(full, nextRel);
+            }
+            else if (ent.isFile() && name.endsWith('.md')) {
+                const isAuto = nextRel.split(path.sep)[0] === 'auto';
+                out.push({ filePath: full, relPath: nextRel, isAuto });
+            }
+        }
+    }
+    walk(root, '');
+    return out;
+}
 function getSkillEmbedding(filePath, triggers, title, description) {
     const cached = skillEmbeddingCache.get(filePath);
     if (cached)
@@ -359,9 +395,15 @@ export function searchSkills(query, limit = 3, agentSlug, opts) {
     const useSemantic = embeddingsReady();
     const queryVec = useSemantic ? embedText(query) : null;
     for (const { dir, boost } of dirs) {
-        const files = readdirSync(dir).filter(f => f.endsWith('.md'));
-        for (const file of files) {
-            const name = file.replace('.md', '');
+        // Walk recursively so skills/auto/<server>/<tool>.md gets indexed
+        // alongside top-level user-authored skills. Track whether a given
+        // file lives under an `auto/` subtree so user-authored wins on
+        // tiebreak even when both match the query.
+        const files = walkSkillFiles(dir);
+        for (const { filePath, relPath, isAuto } of files) {
+            // Use relPath (no .md, slashes → dashes) so same-name skills in
+            // different subdirs don't collide in the dedupe set.
+            const name = relPath.replace(/\.md$/, '').replace(/[\\/]/g, '-');
             if (seen.has(name))
                 continue;
             seen.add(name);
@@ -369,7 +411,6 @@ export function searchSkills(query, limit = 3, agentSlug, opts) {
             // negative user feedback (see store.getSkillsToSuppress).
             if (suppressed?.has(name))
                 continue;
-            const filePath = path.join(dir, file);
             try {
                 const raw = readFileSync(filePath, 'utf-8');
                 const parsed = matter(raw);
@@ -384,11 +425,35 @@ export function searchSkills(query, limit = 3, agentSlug, opts) {
                 const triggerLower = triggers
                     .filter((t) => typeof t === 'string' && t.length > 0)
                     .map(t => t.toLowerCase());
-                for (const word of queryWords) {
-                    for (const trigger of triggerLower) {
-                        if (trigger.includes(word) || word.includes(trigger))
-                            score += 3;
+                const queryLower = query.toLowerCase();
+                // Tokenize into whole words so "list" the trigger-word doesn't
+                // match every "list X" trigger when a single query word "list"
+                // shows up in a totally unrelated query.
+                for (const trigger of triggerLower) {
+                    // Full-phrase substring hit (rare but strongest signal)
+                    if (trigger.length >= 4 && queryLower.includes(trigger)) {
+                        score += 5;
+                        continue;
+                    }
+                    // Word-coverage: fraction of trigger words present in the query
+                    // (with loose substring match per word to catch plurals etc).
+                    const tWords = trigger.split(/\s+/).filter(w => w.length > 2);
+                    if (tWords.length === 0)
+                        continue;
+                    let matched = 0;
+                    for (const tw of tWords) {
+                        if (queryWords.some(qw => qw.includes(tw) || tw.includes(qw)))
+                            matched++;
                     }
+                    const coverage = matched / tWords.length;
+                    // Require ≥50% of the trigger's words to appear. This is what
+                    // stops "list supabase" from matching "list my imessages" — the
+                    // word "supabase" isn't in the query so coverage = 0.5, which
+                    // lands at a tiny score; a fully covered trigger lands strong.
+                    if (coverage >= 0.5)
+                        score += coverage * 3;
+                }
+                for (const word of queryWords) {
                     if (title.toLowerCase().includes(word))
                         score += 2;
                     if (description.toLowerCase().includes(word))
@@ -408,13 +473,18 @@ export function searchSkills(query, limit = 3, agentSlug, opts) {
                             semanticScore = cos * 4;
                     }
                 }
+                // Auto-skills get a small penalty so user-authored skills win
+                // when both match. Still surface auto-skills when nothing else
+                // does — they're the only source of canonical MCP tool knowledge
+                // for connectors the user hasn't explicitly documented.
+                const autoPenalty = isAuto ? -0.5 : 0;
                 const totalScore = score + semanticScore;
                 if (totalScore > 0) {
                     results.push({
                         name,
                         title,
                         content: parsed.content.slice(0, 1500),
-                        score: totalScore + boost,
+                        score: totalScore + boost + autoPenalty,
                         toolsUsed: parsed.data.toolsUsed ?? [],
                         attachments: parsed.data.attachments ?? [],
                         skillDir: dir,

package/dist/index.js

@@ -554,7 +554,7 @@ async function asyncMain() {
         // have been taken with a stale probe config (e.g. before we started
         // passing mcpServers to the probe). Re-probe fresh so Extensions and
         // per-query MCP servers are discovered and whitelisted immediately.
-        probeAvailableTools(true).then(inv => {
+        probeAvailableTools(true).then(async (inv) => {
             const integrations = new Set();
             for (const t of inv.tools) {
                 const m = t.match(/^mcp__claude_ai_([^_]+(?:_[^_]+)*)__/);
@@ -564,6 +564,20 @@ async function asyncMain() {
             if (integrations.size > 0) {
                 logger.info({ integrations: [...integrations].sort(), toolCount: inv.tools.length }, '🦞 Claude Desktop integrations detected');
             }
+            // After inventory is live, fetch canonical schemas from every stdio
+            // MCP server we can reach, then synthesize auto-skills for every
+            // tool. This is the load-bearing pipeline for "Clementine knows how
+            // to call any connector the user has" — no per-tool hardcoding.
+            try {
+                const { fetchAllSchemas } = await import('./agent/mcp-schemas.js');
+                const { synthesizeSkillsFromSchemas } = await import('./agent/auto-skills.js');
+                const schemas = await fetchAllSchemas();
+                const result = synthesizeSkillsFromSchemas(schemas);
+                logger.info(result, '📚 Auto-skills synthesized from MCP schemas');
+            }
+            catch (err) {
+                logger.warn({ err }, 'Auto-skill synthesis failed (non-fatal)');
+            }
         }).catch(() => { });
     }
     catch { /* non-fatal */ }

package/dist/tools/admin-tools.js

@@ -382,6 +382,23 @@ export function registerAdminTools(server) {
             return textResult(`Probe failed: ${String(err).slice(0, 200)}`);
         }
     });
+    server.tool('refresh_skills', 'Re-fetch canonical schemas from every MCP server and regenerate auto-skills under ~/.clementine/vault/00-System/skills/auto/. Runs automatically on daemon boot; use this tool mid-session when the owner adds a new connector or updates an MCP server. Owner-DM only. Returns counts of skills written/unchanged/pruned.', {}, async () => {
+        const gate = requireOwnerDm();
+        if (!gate.ok)
+            return textResult(gate.message);
+        try {
+            const { fetchAllSchemas } = await import('../agent/mcp-schemas.js');
+            const { synthesizeSkillsFromSchemas } = await import('../agent/auto-skills.js');
+            const schemas = await fetchAllSchemas();
+            const result = synthesizeSkillsFromSchemas(schemas);
+            const serverLines = Object.entries(schemas.servers).map(([name, s]) => `- **${name}**: ${s.tools.length} tools${s.error ? ` (error: ${s.error.slice(0, 80)})` : ''}`);
+            return textResult(`Fetched schemas from ${Object.keys(schemas.servers).length} MCP servers.\n${serverLines.join('\n')}\n\n` +
+                `**Skills:** ${result.written} written, ${result.unchanged} unchanged, ${result.pruned} pruned. Total tools indexed: ${result.toolCount}.`);
+        }
+        catch (err) {
+            return textResult(`Skill refresh failed: ${String(err).slice(0, 300)}`);
+        }
+    });
     server.tool('list_allowed_tools', 'Show the current self-managed allowedTools extras (tools you added via allow_tool on top of the built-in whitelist). Owner-DM only.', {}, async () => {
         const gate = requireOwnerDm();
         if (!gate.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.58",
+  "version": "1.0.60",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",