clementine-agent 1.18.171 → 1.18.173

package/dist/agent/chat-skill-resolver.js

@@ -58,10 +58,21 @@ import pino from 'pino';
 import { searchSkills } from './skill-extractor.js';
 const logger = pino({ name: 'clementine.chat-skill-resolver' });
 // ── Tunables ──────────────────────────────────────────────────────────
-/** Default minimum score to consider a skill match real. Mirrors the
- *  legacy `assistant.ts:1492` threshold. Skill auto-match is heuristic;
- *  this filter keeps weak matches from injecting unrelated tooling. */
+/** Default minimum score for user-authored skill matches. Mirrors the
+ *  legacy `assistant.ts:1492` threshold. */
 const DEFAULT_MIN_SCORE = 4;
+/** Higher threshold applied when ALL matches are auto-generated MCP-derived
+ *  skills (no user-authored signal). 1.18.171 hotfix: a vague chat message
+ *  ("did our changes break it?") matched three unrelated auto-skills
+ *  (ElevenLabs + apify) at score 5.5 each because semantic-only matching
+ *  drifted toward whatever embeddings were closest. Bumping the bar for
+ *  auto-only match-sets keeps that noise out of the system prompt. */
+const AUTO_ONLY_MIN_SCORE = 8;
+/** When ALL matches are auto-generated AND they reference this many or
+ *  more distinct servers, the cluster is treated as semantic-noise and
+ *  the injection is skipped entirely. Three different services have no
+ *  business being "all relevant" to a single user message. */
+const AUTO_ONLY_SERVER_NOISE_THRESHOLD = 3;
 /** Default top-K matches to aggregate. Single-tool requests usually
  *  return one strong match; category requests ("salesforce") return
  *  several similarly-scored auto-skills. Top-3 covers both. Raising
@@ -228,9 +239,36 @@ export function resolveSkillsForChat(userMessage, opts = {}) {
         logger.debug({ err }, 'chat-skill-resolver: searchSkills failed (non-fatal)');
         return empty;
     }
-    const matches = candidates
-        .filter((m) => m.score >= minScore)
+    // 1.18.171 hotfix: detect auto-only match-sets and apply the higher
+    // threshold + noise-cluster filter so vague chat messages don't surface
+    // unrelated MCP context. See the comment block on AUTO_ONLY_MIN_SCORE.
+    const isAutoMatch = (m) => m.name.startsWith('auto-');
+    const candidatesAllAuto = candidates.length > 0 && candidates.every(isAutoMatch);
+    const effectiveMinScore = candidatesAllAuto
+        ? Math.max(minScore, AUTO_ONLY_MIN_SCORE)
+        : minScore;
+    let matches = candidates
+        .filter((m) => m.score >= effectiveMinScore)
         .slice(0, limit);
+    // Auto-only noise cluster filter: when every survivor is auto AND they
+    // collectively reference too many distinct servers (no semantic
+    // clustering on a single service), treat as drift and drop.
+    if (matches.length >= 2 && matches.every(isAutoMatch)) {
+        const seenServers = new Set();
+        for (const m of matches) {
+            for (const s of extractMcpServersFromMatch(m))
+                seenServers.add(s);
+        }
+        if (seenServers.size >= AUTO_ONLY_SERVER_NOISE_THRESHOLD) {
+            logger.info({
+                droppedMatches: matches.map(m => ({ name: m.name, score: Number(m.score.toFixed(2)) })),
+                distinctServers: [...seenServers],
+                reason: 'auto_only_server_cluster_too_wide',
+                queryChars,
+            }, 'chat-skill-resolver: dropped match-set (semantic noise)');
+            matches = [];
+        }
+    }
     if (matches.length === 0) {
         return {
             ...empty,

package/dist/agent/run-agent.js

@@ -86,6 +86,7 @@ export function invalidateMcpStatusEntry(name) {
 }
 import { BASE_DIR, PKG_DIR, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY as CONFIG_ANTHROPIC_API_KEY, normalizeClaudeSdkOptionsForOneMillionContext, TOOL_OUTPUT_GUARD, } from '../config.js';
 import { buildGuardHooks } from './tool-output-guard.js';
+import { buildDedupHook } from './tool-call-dedup.js';
 import { buildAgentMap } from './agent-definitions.js';
 import { buildExecutionToolPolicy, } from './execution-policy.js';
 const MCP_SERVER_SCRIPT = path.join(PKG_DIR, 'dist', 'tools', 'mcp-server.js');
@@ -196,13 +197,20 @@ export async function runAgent(prompt, opts) {
         ? requestedBudget
         : undefined;
     const startedAt = Date.now();
-    // Build the AgentDefinition map. Caller can override; otherwise we
-    // use the standard system subagents + hired-agent profiles.
-    const agents = opts.agents ?? buildAgentMap({
+    // Build the AgentDefinition map.
+    // - Default: planner/researcher/cron-fixer + hired-agent profiles.
+    // - Caller-supplied agents (opts.agents) MERGE over the defaults rather
+    //   than REPLACE them (1.18.173). `runSkill`'s auto-delegation path
+    //   needs to inject a per-run `skill-worker` definition while keeping
+    //   the planner/researcher/etc. available for deeper delegation.
+    //   Tests that want a fully isolated map pass an explicit override
+    //   via the `replaceAgents` option below.
+    const defaultAgents = buildAgentMap({
         profileManager: opts.agentManager ?? undefined,
         isAutonomous: source === 'cron' || source === 'heartbeat',
         activeAgentSlug: opts.profile?.slug,
     });
+    const agents = opts.agents ? { ...defaultAgents, ...opts.agents } : defaultAgents;
     // Wrap prompt to direct Claude to a specific subagent when caller asks.
     // Per SDK docs: explicit invocation = "Use the X agent to..."
     const effectivePrompt = opts.forceSubagent && agents[opts.forceSubagent]
@@ -341,6 +349,34 @@ export async function runAgent(prompt, opts) {
             },
         })
         : { hooks: {}, stats: { inspected: 0, compressed: 0, ceilingHits: 0, bytesShed: 0, compactions: 0 } };
+    // ── Tool-call dedup hook (1.18.173) ─────────────────────────────────
+    // Breaks the "re-fetch after compaction" loop that crashed the
+    // imessage-triage cron on 2026-05-11 (4× identical tool calls →
+    // SDK autocompact-thrashing abort). PreToolUse hook detects same
+    // (toolName, inputHash) within 60s: 2nd call gets a soft hint, 3rd+
+    // is denied so the model can't burn turns re-calling the same data.
+    // Defense-in-depth — the cleaner fix (delegating to a subagent so the
+    // parent never re-fetches in the first place) lives in run-skill.ts.
+    const dedup = buildDedupHook({
+        runId,
+        onDecision: (info) => {
+            if (info.decision === 'allow')
+                return;
+            writeEvent({
+                kind: 'error',
+                ts: new Date().toISOString(),
+                sessionId,
+                toolError: `_clementine_dedup:${info.decision} ${info.toolName} call#${info.callCount} @${info.sinceFirstMs}ms`,
+            });
+        },
+    });
+    // Merge hook maps from the two modules. SDK accepts arrays of
+    // HookCallbackMatcher per event; we concatenate.
+    const mergedHooks = { ...guard.hooks };
+    for (const [evt, matchers] of Object.entries(dedup.hooks)) {
+        const existing = mergedHooks[evt] ?? [];
+        mergedHooks[evt] = [...existing, ...matchers];
+    }
     // Apply 1M-context env normalization (existing infra)
     const sdkOptionsRaw = {
         systemPrompt: profileAppend
@@ -380,10 +416,11 @@ export async function runAgent(prompt, opts) {
         ...(opts.additionalDirectories && opts.additionalDirectories.length > 0
             ? { additionalDirectories: opts.additionalDirectories }
             : {}),
-        // 1.18.169 — install the tool-output guard hooks. SDK types accept
-        // `hooks` keyed by HookEvent; the empty object is a no-op when the
-        // guard is disabled.
-        ...(Object.keys(guard.hooks).length > 0 ? { hooks: guard.hooks } : {}),
+        // 1.18.169 — install the tool-output guard hooks.
+        // 1.18.173 — merged with the tool-call dedup hooks (PreToolUse).
+        // SDK types accept `hooks` keyed by HookEvent; the empty object is
+        // a no-op when both guards are disabled.
+        ...(Object.keys(mergedHooks).length > 0 ? { hooks: mergedHooks } : {}),
     };
     const sdkOptions = normalizeClaudeSdkOptionsForOneMillionContext(sdkOptionsRaw);
     logger.info({
@@ -640,6 +677,14 @@ export async function runAgent(prompt, opts) {
             compactions: guard.stats.compactions,
             ceilingHits: guard.stats.ceilingHits,
         } : undefined,
+        // 1.18.173 — tool-call dedup summary. Non-zero warned/blocked means
+        // the model tried to re-fetch identical data (typically a
+        // post-compaction refetch loop).
+        dedup: dedup.stats.inspected > 0 ? {
+            inspected: dedup.stats.inspected,
+            warned: dedup.stats.warned,
+            blocked: dedup.stats.blocked,
+        } : undefined,
     }, 'runAgent: query complete');
     // PRD §6 Phase 4e: subagent transcript backfill (Path C). The SDK persists
     // every subagent's full message stream to ~/.claude/projects/<encoded-cwd>/

package/dist/agent/run-skill.d.ts

@@ -145,6 +145,13 @@ export declare function buildSkillPrompt(skill: Skill, inputs: Record<string, st
  * After the SDK returns, `clementine.success.schema` (when set) is
  * ajv-validated against the response.
  *
+ * **Autonomous runs (1.18.173)**: When `source` is one of
+ * AUTONOMOUS_SOURCES, the skill runs through the auto-delegating
+ * wrapper: a thin parent dispatches to a `skill-worker` subagent which
+ * does all the work in its own context. Closes the
+ * "refetch-after-compaction" loop class permanently. Skills can opt out
+ * via frontmatter `clementine.execution.inline: true`.
+ *
  * This function never throws — failures (skill not found, SDK error,
  * timeout) are returned as `{ ok: false, error }`. The caller (chat,
  * cron, sub-agent, MCP tool) decides how to surface that.

package/dist/agent/run-skill.js

@@ -28,6 +28,7 @@ import path from 'node:path';
 import pino from 'pino';
 import { getSkill } from './skill-store.js';
 import { runAgent } from './run-agent.js';
+import { MODELS } from '../config.js';
 const logger = pino({ name: 'clementine.run-skill' });
 // ── Mustache substitution ─────────────────────────────────────────────
 /** Matches `{{var_name}}` with optional whitespace. var_name is
@@ -183,6 +184,133 @@ async function validateSkillOutput(output, schema) {
         return { tried: true, pass: false, errors: [`schema compile error: ${err}`] };
     }
 }
+// ── Autonomous delegation (1.18.173) ──────────────────────────────────
+/**
+ * Sources whose runs should default to the auto-delegating wrapper.
+ * In autonomous mode the parent agent immediately dispatches the entire
+ * skill body to a `skill-worker` subagent via the Agent tool. That keeps
+ * the parent's context tiny (no tool results ever land in it) so the SDK
+ * never has to compact mid-run, and post-compaction "refetch loops"
+ * become impossible — the parent never had the data to lose.
+ *
+ * Interactive sources ('chat', 'skill' invoked directly by a chat user)
+ * stay on the inline path: the user is waiting on output and the extra
+ * subagent dispatch latency is a worse UX tradeoff than the small
+ * compaction risk on a single conversational turn.
+ */
+const AUTONOMOUS_SOURCES = new Set([
+    'cron',
+    'scheduled-skill',
+    'heartbeat',
+    'team-task',
+]);
+/**
+ * Decide whether a runSkill call should use the auto-delegating
+ * (subagent) wrapper. Skills can opt out via frontmatter
+ * `clementine.execution.inline: true` for procedures the author has
+ * verified fit cleanly in one context (e.g., a 2-line script call).
+ */
+function shouldAutoDelegate(skill, source) {
+    if (!AUTONOMOUS_SOURCES.has(source))
+        return false;
+    const execMode = skill.frontmatter?.clementine?.execution?.inline;
+    if (execMode === true)
+        return false;
+    return true;
+}
+/**
+ * Resolve the model string to use for an autonomous run. The 1M-context
+ * variant gives the worker subagent 5× the room of the standard 200K
+ * window — enough headroom that compaction is rare and the
+ * "refetch-after-compact" loop pattern (seen in the 2026-05-11
+ * imessage-triage failures) never occurs in practice.
+ *
+ * The actual 1M routing is gated by the user's plan (see
+ * config.ts:usesOneMillionContext) and the model family — Haiku doesn't
+ * support 1M, and Sonnet 1M needs the [1m] suffix. We return the full
+ * Sonnet model ID with [1m] appended; downstream
+ * normalizeClaudeSdkOptionsForOneMillionContext strips it back off when
+ * the plan doesn't support it.
+ */
+function resolveAutonomousModel(explicitModel, skillModel) {
+    // Caller's explicit model wins.
+    if (explicitModel)
+        return explicitModel;
+    // Skill-declared model wins next.
+    if (skillModel)
+        return skillModel;
+    // Default: Sonnet [1m]. The normalizer will strip [1m] if the user's
+    // plan doesn't include it, falling back to standard Sonnet — still
+    // works, just with less headroom.
+    const base = MODELS.sonnet;
+    if (!base)
+        return undefined;
+    if (/\[1m\]/i.test(base))
+        return base;
+    return `${base}[1m]`;
+}
+/**
+ * Build the AgentDefinition for the `skill-worker` subagent that
+ * executes this skill in an isolated context. The subagent's system
+ * prompt is the skill body; its tools are the skill's computed
+ * allowlist; its model is the same 1M-context model the parent uses
+ * (the worker is where the real data flows — the parent stays tiny).
+ *
+ * `description` is what the SDK shows the parent for routing decisions.
+ * Since the parent is `forceSubagent`'d to this worker, the description
+ * mostly serves as transcript context.
+ */
+function buildSkillWorkerAgent(skill, effectiveTools, model, workerMaxTurns) {
+    const def = {
+        description: `Executes the "${skill.frontmatter.name}" scheduled skill end-to-end in an isolated context window. ` +
+            `Reads any data the skill needs, processes it, performs the skill's described delivery action ` +
+            `(e.g., sends a Discord/Slack notification), and returns a concise summary to the orchestrator.`,
+        prompt: `You are the worker subagent for the "${skill.frontmatter.name}" scheduled skill.\n\n` +
+            `Your job is to execute the procedure below from start to finish in a single subagent run. ` +
+            `You have your own isolated context window — do NOT save state for a parent agent; if the ` +
+            `procedure calls for sending a notification, YOU send it (you have the relevant tools).\n\n` +
+            `Return a single concise final response describing what happened (e.g., "Sent Discord DM about ` +
+            `2 actionable items, ignored 8 spam"). Do not return raw tool output; do not narrate every step. ` +
+            `If nothing actionable was found and the procedure says exit silently, return "No action needed."\n\n` +
+            `## Procedure\n\n${skill.body}`,
+        tools: effectiveTools,
+        // SDK accepts 'sonnet' / 'opus' / 'haiku' tier aliases OR full model
+        // IDs. We pass the full ID with [1m] when present; the SDK strips
+        // [1m] internally for plans that don't support it.
+        ...(model ? { model } : {}),
+        effort: 'medium',
+        maxTurns: workerMaxTurns,
+    };
+    return def;
+}
+/**
+ * Build the parent orchestrator's prompt. The parent has exactly one
+ * job: dispatch to `skill-worker` via the Agent tool and relay its
+ * return. Keeping this prompt under ~600 bytes is important — the
+ * parent's context grows by the parent prompt + the worker's final
+ * return text (typically <2KB). Total parent context per run: ~3KB.
+ * Well below any compaction threshold even on a 200K-window model.
+ */
+function buildOrchestratorPrompt(skill, callerContext) {
+    const parts = [
+        `## Scheduled Skill Execution`,
+        ``,
+        `Dispatch the "${skill.frontmatter.name}" skill to the \`skill-worker\` subagent via the Agent tool.`,
+        `The worker has the skill body as its system prompt and the tools required to perform the procedure end-to-end (including any notification delivery).`,
+        ``,
+        `## Your job`,
+        ``,
+        `1. Call the Agent tool ONCE, dispatching to "skill-worker" with this brief: "Execute the ${skill.frontmatter.name} procedure now."`,
+        `2. Wait for its return.`,
+        `3. Relay its summary as your final response — do not add commentary, do not re-do its work.`,
+        ``,
+        `Do NOT call any other tools directly. The worker handles all data access and delivery.`,
+    ];
+    if (callerContext && callerContext.trim()) {
+        parts.push('', '## Caller context (forward this to the worker if relevant)', '', callerContext.trim());
+    }
+    return parts.join('\n');
+}
 // ── The primitive ─────────────────────────────────────────────────────
 /**
  * Run a skill as a hard-allowlisted sub-call. Returns a structured result.
@@ -194,6 +322,13 @@ async function validateSkillOutput(output, schema) {
  * After the SDK returns, `clementine.success.schema` (when set) is
  * ajv-validated against the response.
  *
+ * **Autonomous runs (1.18.173)**: When `source` is one of
+ * AUTONOMOUS_SOURCES, the skill runs through the auto-delegating
+ * wrapper: a thin parent dispatches to a `skill-worker` subagent which
+ * does all the work in its own context. Closes the
+ * "refetch-after-compaction" loop class permanently. Skills can opt out
+ * via frontmatter `clementine.execution.inline: true`.
+ *
  * This function never throws — failures (skill not found, SDK error,
  * timeout) are returned as `{ ok: false, error }`. The caller (chat,
  * cron, sub-agent, MCP tool) decides how to surface that.
@@ -212,7 +347,17 @@ export async function runSkill(name, options = {}) {
     }
     const effectiveTools = computeSkillAllowlist(skill);
     const hasExplicitToolScope = skillHasExplicitToolScope(skill);
-    const prompt = buildSkillPrompt(skill, options.inputs, options.context);
+    const source = options.source ?? 'skill';
+    // 1.18.173: autonomous runs (cron, scheduled-skill, heartbeat,
+    // team-task) wrap the skill in a thin orchestrator that dispatches
+    // the entire procedure to a `skill-worker` subagent. The parent's
+    // context never grows past ~3KB regardless of how much data the
+    // skill reads, so post-compaction refetch loops are structurally
+    // impossible. See shouldAutoDelegate / buildSkillWorkerAgent above.
+    const autoDelegate = shouldAutoDelegate(skill, source);
+    const prompt = autoDelegate
+        ? buildOrchestratorPrompt(skill, options.context)
+        : buildSkillPrompt(skill, options.inputs, options.context);
     const limits = skill.frontmatter?.clementine?.limits;
     const maxTurns = options.maxTurns ?? limits?.maxTurns;
     const maxBudgetUsd = options.maxBudgetUsd ?? limits?.maxBudgetUsd;
@@ -225,6 +370,14 @@ export async function runSkill(name, options = {}) {
         ...(skill.layout === 'folder' ? [path.dirname(skill.filePath)] : []),
     ];
     const mutatingSkill = effectiveTools.some((t) => t === 'Write' || t === 'Edit' || t === 'Bash' || /__(write|edit|update|create|delete|send|post|patch|set)/i.test(t));
+    // 1.18.173: resolve the effective model. Autonomous runs default to
+    // Sonnet [1m] (1M context window) so the worker subagent has 5× the
+    // room of a standard 200K-window model. resolveAutonomousModel honors
+    // explicit overrides + skill-declared limits.model first.
+    const skillModel = skill.frontmatter?.clementine?.limits?.model;
+    const effectiveModel = autoDelegate
+        ? resolveAutonomousModel(options.model, skillModel)
+        : (options.model ?? skillModel);
     logger.info({
         skill: name,
         tools: effectiveTools,
@@ -232,6 +385,9 @@ export async function runSkill(name, options = {}) {
         maxBudgetUsd,
         inputKeys: Object.keys(options.inputs ?? {}),
         hasContext: !!options.context,
+        autoDelegate,
+        model: effectiveModel,
+        source,
     }, 'runSkill: invoking');
     let runResult;
     try {
@@ -245,24 +401,74 @@ export async function runSkill(name, options = {}) {
             ].filter(Boolean).join('\n\n'),
             profile: options.profile,
         });
-        const allowedToolsForRun = hasExplicitToolScope ? effectiveTools : undefined;
-        const sdkOpts = {
-            sessionKey,
-            source: options.source ?? 'skill',
-            ...(allowedToolsForRun ? { allowedTools: allowedToolsForRun } : {}),
-            profile: options.profile,
-            agentManager: options.agentManager,
-            memoryStore: options.memoryStore,
-            cwd: options.projectWorkDir,
-            extraMcpServers: mcp.servers,
-            enableFileCheckpointing: mutatingSkill || Boolean(options.projectWorkDir),
-            ...(options.model ? { model: options.model } : {}),
-            ...(typeof maxTurns === 'number' ? { maxTurns } : {}),
-            ...(typeof maxBudgetUsd === 'number' ? { maxBudgetUsd } : {}),
-            ...(additionalDirectories.length > 0 ? { additionalDirectories } : {}),
-            ...(options.onText ? { onText: options.onText } : {}),
-            ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
-        };
+        // ── Autonomous-delegation branch (1.18.173) ──────────────────────
+        // Parent: minimal allowedTools (Agent only) + forceSubagent to
+        // skill-worker. Worker: full tool surface + skill body as system
+        // prompt. Worker is the SDK AgentDefinition; the SDK wires its
+        // tools/model/prompt at query time.
+        let sdkOpts;
+        if (autoDelegate) {
+            // Worker gets enough turns to complete bulk work (skill author's
+            // maxTurns cap, or 30 as a safe default for triage-class work).
+            const workerMaxTurns = (typeof maxTurns === 'number' && maxTurns > 0) ? maxTurns : 30;
+            const workerDef = buildSkillWorkerAgent(skill, effectiveTools, effectiveModel, workerMaxTurns);
+            sdkOpts = {
+                sessionKey,
+                source,
+                // Parent's allowedTools: ONLY Agent (delegate-or-fail). Keeps
+                // the parent's context shape predictable and prevents it from
+                // doing data-heavy work itself even if the LLM disagrees.
+                allowedTools: ['Agent'],
+                // Force-routing: SDK wraps the prompt with "Use the skill-worker
+                // agent to handle this request" so dispatch is the natural
+                // first action.
+                forceSubagent: 'skill-worker',
+                // Inject the skill-worker into the agents map. runAgent merges
+                // its `buildAgentMap()` defaults with whatever's passed via
+                // opts.agents — see run-agent.ts:362.
+                agents: { 'skill-worker': workerDef },
+                profile: options.profile,
+                agentManager: options.agentManager,
+                memoryStore: options.memoryStore,
+                cwd: options.projectWorkDir,
+                extraMcpServers: mcp.servers,
+                enableFileCheckpointing: mutatingSkill || Boolean(options.projectWorkDir),
+                // Parent uses the same model family so MCP server reuse is clean
+                // (the SDK keys some cache state by model). Parent turns are
+                // tightly capped: it should dispatch and relay in ≤3 turns.
+                ...(effectiveModel ? { model: effectiveModel } : {}),
+                maxTurns: 5,
+                ...(typeof maxBudgetUsd === 'number' ? { maxBudgetUsd } : {}),
+                ...(additionalDirectories.length > 0 ? { additionalDirectories } : {}),
+                ...(options.onText ? { onText: options.onText } : {}),
+                ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+            };
+        }
+        else {
+            // ── Inline branch (interactive / opt-out skills) ────────────────
+            // Original 1.18.162 behavior — the SDK call runs the skill body
+            // directly as the main-agent prompt. Used for chat-invoked skills
+            // where the latency of a subagent dispatch is worse UX than the
+            // small compaction risk.
+            const allowedToolsForRun = hasExplicitToolScope ? effectiveTools : undefined;
+            sdkOpts = {
+                sessionKey,
+                source,
+                ...(allowedToolsForRun ? { allowedTools: allowedToolsForRun } : {}),
+                profile: options.profile,
+                agentManager: options.agentManager,
+                memoryStore: options.memoryStore,
+                cwd: options.projectWorkDir,
+                extraMcpServers: mcp.servers,
+                enableFileCheckpointing: mutatingSkill || Boolean(options.projectWorkDir),
+                ...(effectiveModel ? { model: effectiveModel } : {}),
+                ...(typeof maxTurns === 'number' ? { maxTurns } : {}),
+                ...(typeof maxBudgetUsd === 'number' ? { maxBudgetUsd } : {}),
+                ...(additionalDirectories.length > 0 ? { additionalDirectories } : {}),
+                ...(options.onText ? { onText: options.onText } : {}),
+                ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+            };
+        }
         runResult = await runAgent(prompt, sdkOpts);
     }
     catch (err) {

package/dist/agent/tool-call-dedup.d.ts

@@ -0,0 +1,93 @@
+/**
+ * tool-call-dedup — PreToolUse hook that detects same-call loops and
+ * nudges the model to stop re-fetching identical data.
+ *
+ * Why this exists (1.18.173)
+ * ──────────────────────────
+ * The Anthropic SDK's auto-compactor summarizes prior turns when context
+ * approaches the model's window. If the working data lived in those
+ * earlier turns, compaction loses it — and the model often responds by
+ * RE-CALLING the same tool with the same arguments to "re-load" the
+ * data. That refill triggers the next compaction, which loses the
+ * re-loaded data, which triggers another re-call, … and the SDK's
+ * thrashing detector aborts the run after 3 consecutive cycles.
+ *
+ * Real-world example (2026-05-11 imessage-triage 08:00 UTC, run
+ * 839a7d1a-…): four IDENTICAL calls to `get_unread_imessages({limit:20})`
+ * in 115 seconds, one after each compaction. The tool-output-guard from
+ * 1.18.169 didn't fire because each individual response was under the
+ * 30KB cap; the loop was structural, not size-based.
+ *
+ * What this hook does
+ * ───────────────────
+ * On every PreToolUse, hash `(toolName, JSON.stringify(input))` and look
+ * it up in a per-run cache (60s TTL by default).
+ *   • count = 1 (first call): let it through, record.
+ *   • count = 2 (second call within TTL): inject an `additionalContext`
+ *     hint into the next turn saying "you already called this; the
+ *     result hasn't changed; reuse it or change the inputs." Tool still
+ *     executes (the model might have legitimate reasons to re-poll).
+ *   • count = 3+ (third+ identical call): `permissionDecision: 'deny'`
+ *     with a reason that directs the model to either change inputs or
+ *     stop the loop. The model receives a denial result instead of new
+ *     tool data — breaks the refetch-after-compact cycle.
+ *
+ * Aligned with Anthropic SDK best practices: PreToolUse + permission
+ * decisions are the documented mechanism for controlling tool execution
+ * mid-run. `sdk.d.ts:2002-2008` — `PreToolUseHookSpecificOutput` carries
+ * `permissionDecision` ('allow'/'deny'/'ask'/'defer') + reason +
+ * additionalContext for exactly this case.
+ *
+ * Failure mode
+ * ────────────
+ * Never throws. Hash errors, cache errors, anything — degrades to
+ * letting the call through. Telemetry must never block execution.
+ */
+import type { HookCallbackMatcher, HookEvent } from '@anthropic-ai/claude-agent-sdk';
+export interface DedupHookOptions {
+    /** Stable run identifier — used to scope the cache per run. */
+    runId: string;
+    /** How long an identical call is considered "the same" (ms). */
+    ttlMs?: number;
+    /** Override the soft-warn threshold (default 2nd call). */
+    softWarnAt?: number;
+    /** Override the hard-block threshold (default 3rd call). */
+    hardBlockAt?: number;
+    /** Optional callback fired on every dedup decision. */
+    onDecision?: (info: {
+        toolName: string;
+        inputHash: string;
+        callCount: number;
+        decision: 'allow' | 'warn' | 'block';
+        sinceFirstMs: number;
+    }) => void;
+}
+export interface DedupRunStats {
+    /** Total PreToolUse invocations inspected. */
+    inspected: number;
+    /** Calls that were warned (let through with hint). */
+    warned: number;
+    /** Calls that were blocked outright. */
+    blocked: number;
+}
+export interface DedupHookHandles {
+    /** Hook map suitable for SDK `query({ options: { hooks } })`. */
+    hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    /** Aggregated telemetry — read after the run completes. */
+    stats: DedupRunStats;
+}
+/**
+ * Compute a stable hash of a tool call's input shape. JSON.stringify
+ * with a sorted-keys replacer so `{a:1,b:2}` and `{b:2,a:1}` collide
+ * (same semantic call); other minor differences (object key order) don't
+ * spuriously evade the dedup.
+ */
+export declare function hashToolInput(input: unknown): string;
+/**
+ * Build a PreToolUse dedup hook for a single runAgent invocation.
+ * Per-run cache (no cross-run state) — short-lived agentic runs don't
+ * need persistence and we don't want stale cache to deny legitimate
+ * post-restart re-polls.
+ */
+export declare function buildDedupHook(opts: DedupHookOptions): DedupHookHandles;
+//# sourceMappingURL=tool-call-dedup.d.ts.map

package/dist/agent/tool-call-dedup.js

@@ -0,0 +1,168 @@
+/**
+ * tool-call-dedup — PreToolUse hook that detects same-call loops and
+ * nudges the model to stop re-fetching identical data.
+ *
+ * Why this exists (1.18.173)
+ * ──────────────────────────
+ * The Anthropic SDK's auto-compactor summarizes prior turns when context
+ * approaches the model's window. If the working data lived in those
+ * earlier turns, compaction loses it — and the model often responds by
+ * RE-CALLING the same tool with the same arguments to "re-load" the
+ * data. That refill triggers the next compaction, which loses the
+ * re-loaded data, which triggers another re-call, … and the SDK's
+ * thrashing detector aborts the run after 3 consecutive cycles.
+ *
+ * Real-world example (2026-05-11 imessage-triage 08:00 UTC, run
+ * 839a7d1a-…): four IDENTICAL calls to `get_unread_imessages({limit:20})`
+ * in 115 seconds, one after each compaction. The tool-output-guard from
+ * 1.18.169 didn't fire because each individual response was under the
+ * 30KB cap; the loop was structural, not size-based.
+ *
+ * What this hook does
+ * ───────────────────
+ * On every PreToolUse, hash `(toolName, JSON.stringify(input))` and look
+ * it up in a per-run cache (60s TTL by default).
+ *   • count = 1 (first call): let it through, record.
+ *   • count = 2 (second call within TTL): inject an `additionalContext`
+ *     hint into the next turn saying "you already called this; the
+ *     result hasn't changed; reuse it or change the inputs." Tool still
+ *     executes (the model might have legitimate reasons to re-poll).
+ *   • count = 3+ (third+ identical call): `permissionDecision: 'deny'`
+ *     with a reason that directs the model to either change inputs or
+ *     stop the loop. The model receives a denial result instead of new
+ *     tool data — breaks the refetch-after-compact cycle.
+ *
+ * Aligned with Anthropic SDK best practices: PreToolUse + permission
+ * decisions are the documented mechanism for controlling tool execution
+ * mid-run. `sdk.d.ts:2002-2008` — `PreToolUseHookSpecificOutput` carries
+ * `permissionDecision` ('allow'/'deny'/'ask'/'defer') + reason +
+ * additionalContext for exactly this case.
+ *
+ * Failure mode
+ * ────────────
+ * Never throws. Hash errors, cache errors, anything — degrades to
+ * letting the call through. Telemetry must never block execution.
+ */
+import { createHash } from 'node:crypto';
+import pino from 'pino';
+const logger = pino({ name: 'clementine.tool-call-dedup' });
+// ── Tunables ──────────────────────────────────────────────────────────
+/** Within this window (ms), identical calls are considered "the same". */
+const DEFAULT_TTL_MS = 60_000;
+/** Second identical call within TTL → soft warn (let it through with a hint). */
+const SOFT_WARN_AT = 2;
+/** Third+ identical call within TTL → hard block (deny). */
+const HARD_BLOCK_AT = 3;
+// ── Hashing ───────────────────────────────────────────────────────────
+/**
+ * Compute a stable hash of a tool call's input shape. JSON.stringify
+ * with a sorted-keys replacer so `{a:1,b:2}` and `{b:2,a:1}` collide
+ * (same semantic call); other minor differences (object key order) don't
+ * spuriously evade the dedup.
+ */
+export function hashToolInput(input) {
+    try {
+        const stable = JSON.stringify(input, replaceForStableHash);
+        return createHash('sha256').update(stable).digest('hex').slice(0, 16);
+    }
+    catch {
+        return 'unhashable';
+    }
+}
+function replaceForStableHash(_key, value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const sorted = {};
+        const keys = Object.keys(value).sort();
+        for (const k of keys)
+            sorted[k] = value[k];
+        return sorted;
+    }
+    return value;
+}
+// ── Hook builder ──────────────────────────────────────────────────────
+/**
+ * Build a PreToolUse dedup hook for a single runAgent invocation.
+ * Per-run cache (no cross-run state) — short-lived agentic runs don't
+ * need persistence and we don't want stale cache to deny legitimate
+ * post-restart re-polls.
+ */
+export function buildDedupHook(opts) {
+    const cache = new Map();
+    const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const softAt = opts.softWarnAt ?? SOFT_WARN_AT;
+    const hardAt = opts.hardBlockAt ?? HARD_BLOCK_AT;
+    const stats = { inspected: 0, warned: 0, blocked: 0 };
+    const preToolUse = async (input) => {
+        if (input.hook_event_name !== 'PreToolUse')
+            return {};
+        const evt = input;
+        const toolName = String(evt.tool_name ?? 'unknown');
+        const inputHash = hashToolInput(evt.tool_input);
+        const key = `${toolName}:${inputHash}`;
+        const now = Date.now();
+        stats.inspected += 1;
+        let entry = cache.get(key);
+        // Treat expired entries as fresh — drop and restart the count.
+        if (entry && now - entry.lastSeen > ttl) {
+            cache.delete(key);
+            entry = undefined;
+        }
+        if (!entry) {
+            cache.set(key, { count: 1, firstSeen: now, lastSeen: now });
+            opts.onDecision?.({ toolName, inputHash, callCount: 1, decision: 'allow', sinceFirstMs: 0 });
+            return {};
+        }
+        entry.count += 1;
+        entry.lastSeen = now;
+        const sinceFirstMs = now - entry.firstSeen;
+        if (entry.count >= hardAt) {
+            stats.blocked += 1;
+            logger.warn({
+                toolName,
+                inputHash,
+                callCount: entry.count,
+                sinceFirstMs,
+                runId: opts.runId,
+            }, 'tool-call-dedup: hard-blocking identical call');
+            opts.onDecision?.({ toolName, inputHash, callCount: entry.count, decision: 'block', sinceFirstMs });
+            return {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: `Tool \`${toolName}\` was already called with these exact arguments ${entry.count - 1} time(s) in the last ${Math.floor(sinceFirstMs / 1000)}s. ` +
+                        `The result has not changed. STOP re-calling — use the result from your earlier context, ` +
+                        `change the arguments to fetch different data, or finish the task with what you already know. ` +
+                        `If you genuinely need fresh data, wait at least ${Math.ceil(ttl / 1000)}s and try again.`,
+                },
+            };
+        }
+        if (entry.count >= softAt) {
+            stats.warned += 1;
+            logger.info({
+                toolName,
+                inputHash,
+                callCount: entry.count,
+                sinceFirstMs,
+                runId: opts.runId,
+            }, 'tool-call-dedup: warning on repeat call');
+            opts.onDecision?.({ toolName, inputHash, callCount: entry.count, decision: 'warn', sinceFirstMs });
+            return {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    additionalContext: `Note: you've already called \`${toolName}\` with these exact arguments ${entry.count - 1} time(s) in the last ${Math.floor(sinceFirstMs / 1000)}s. ` +
+                        `The result will be identical. Consider re-using the prior result rather than letting this call burn turns/budget. ` +
+                        `One more identical re-call will be blocked.`,
+                },
+            };
+        }
+        opts.onDecision?.({ toolName, inputHash, callCount: entry.count, decision: 'allow', sinceFirstMs });
+        return {};
+    };
+    return {
+        hooks: {
+            PreToolUse: [{ hooks: [preToolUse] }],
+        },
+        stats,
+    };
+}
+//# sourceMappingURL=tool-call-dedup.js.map

package/dist/cli/dashboard.js

@@ -21638,25 +21638,34 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
           </div>
         </div>
         <div style="display:flex;align-items:center;gap:8px;flex-shrink:0">
-          <button class="btn-secondary" onclick="openSkillStudio()" style="font-size:13px;padding:8px 14px;border-radius:6px;border:1px solid var(--border);background:var(--bg-secondary);color:var(--text-primary);font-weight:500;cursor:pointer;display:inline-flex;align-items:center;gap:6px" title="Open the conversational Skill Studio">
+          <button class="btn-secondary" onclick="openSkillStudio()" style="font-size:13px;padding:8px 14px;border-radius:6px;border:1px solid var(--border);background:var(--bg-secondary);color:var(--text-primary);font-weight:500;cursor:pointer;display:inline-flex;align-items:center;gap:6px" title="Open the natural-language Skill Studio">
             Open Studio
           </button>
-          <button class="btn-primary" onclick="openCreateSkillModalFromComposer()" style="font-size:13px;padding:8px 14px;border-radius:6px;border:none;background:var(--accent);color:#fff;font-weight:500;cursor:pointer;display:inline-flex;align-items:center;gap:6px" title="Open a clean blank skill editor">
-            Blank skill
+          <button class="btn-primary" onclick="openCreateSkillModalFromComposer()" style="font-size:13px;padding:8px 14px;border-radius:6px;border:none;background:var(--accent);color:#fff;font-weight:500;cursor:pointer;display:inline-flex;align-items:center;gap:6px" title="Open a blank SKILL.md editor">
+            Manual editor
           </button>
         </div>
       </div>
+      <div id="skill-composer-home">
       <div id="skill-composer" style="margin:0 0 16px;border:1px solid var(--border);border-radius:8px;background:var(--bg-secondary);padding:14px 16px">
-        <div style="display:grid;grid-template-columns:minmax(280px,1.2fr) minmax(260px,0.8fr);gap:14px;align-items:start">
+        <div style="display:flex;align-items:flex-start;justify-content:space-between;gap:14px;margin-bottom:12px">
+          <div style="min-width:0">
+            <div style="font-size:14px;font-weight:600;color:var(--text-primary);margin-bottom:3px">Skill Studio</div>
+            <div style="font-size:12px;color:var(--text-muted);line-height:1.45">Describe reusable work in plain language. Optional starting points only seed the draft; nothing runs until you save or test it.</div>
+          </div>
+          <div style="font-size:10px;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;white-space:nowrap;margin-top:2px">Natural language first</div>
+        </div>
+        <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:14px;align-items:start">
           <div>
-            <label for="skill-composer-text" style="display:block;font-size:11px;font-weight:600;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;margin-bottom:6px">Describe the skill</label>
-            <textarea id="skill-composer-text" rows="4" oninput="updateSkillComposerDraftState()" placeholder="Review my Asana tasks, update a Google Sheet, verify four source systems, then report back in Asana." style="width:100%;box-sizing:border-box;padding:10px 12px;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);color:var(--text-primary);font-size:13px;line-height:1.45;resize:vertical;min-height:92px"></textarea>
+            <label for="skill-composer-text" style="display:block;font-size:11px;font-weight:600;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;margin-bottom:6px">What should Clementine learn?</label>
+            <textarea id="skill-composer-text" rows="5" oninput="updateSkillComposerDraftState()" placeholder="Find Salesforce contacts I have not touched in 15 days, enrich the accounts with DataForSEO signals, draft cold prospecting emails, then report the drafts back for review." style="width:100%;box-sizing:border-box;padding:10px 12px;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);color:var(--text-primary);font-size:13px;line-height:1.45;resize:vertical;min-height:112px"></textarea>
+            <div style="margin-top:8px;font-size:11px;color:var(--text-muted);line-height:1.45">Good skills name the repeatable outcome, required tools or data, approval boundaries, and what counts as done.</div>
           </div>
           <div>
-            <div style="font-size:11px;font-weight:600;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;margin-bottom:6px">Starting point</div>
+            <div style="font-size:11px;font-weight:600;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;margin-bottom:6px">Optional starting points</div>
             <div id="skill-composer-modes" style="display:grid;grid-template-columns:repeat(5,minmax(0,1fr));gap:4px;margin-bottom:10px">
               <button type="button" class="skill-composer-mode" data-kind="outcome" onclick="setSkillComposerMode('outcome')" style="padding:7px 6px;border:1px solid var(--accent);border-radius:6px;background:rgba(255,141,0,0.10);color:var(--accent);font-size:11px;font-weight:600;cursor:pointer">Outcome</button>
-              <button type="button" class="skill-composer-mode" data-kind="tool" onclick="setSkillComposerMode('tool')" style="padding:7px 6px;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);color:var(--text-secondary);font-size:11px;font-weight:600;cursor:pointer">Tool/MCP</button>
+              <button type="button" class="skill-composer-mode" data-kind="tool" onclick="setSkillComposerMode('tool')" style="padding:7px 6px;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);color:var(--text-secondary);font-size:11px;font-weight:600;cursor:pointer">MCP/API</button>
               <button type="button" class="skill-composer-mode" data-kind="cli" onclick="setSkillComposerMode('cli')" style="padding:7px 6px;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);color:var(--text-secondary);font-size:11px;font-weight:600;cursor:pointer">CLI</button>
               <button type="button" class="skill-composer-mode" data-kind="project" onclick="setSkillComposerMode('project')" style="padding:7px 6px;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);color:var(--text-secondary);font-size:11px;font-weight:600;cursor:pointer">Project</button>
               <button type="button" class="skill-composer-mode" data-kind="memory" onclick="setSkillComposerMode('memory')" style="padding:7px 6px;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);color:var(--text-secondary);font-size:11px;font-weight:600;cursor:pointer">Memory</button>
@@ -21670,12 +21679,13 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
             <div id="skill-composer-anchor-summary" style="margin-top:8px;min-height:22px;font-size:11px;color:var(--text-muted);line-height:1.45">No starting point selected.</div>
             <div id="skill-composer-preview" style="margin-top:10px;max-height:180px;overflow:auto;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);padding:10px 12px;font-size:11px;line-height:1.45;color:var(--text-secondary)"></div>
             <div style="display:flex;align-items:center;justify-content:flex-end;gap:8px;margin-top:12px">
-              <button type="button" class="btn-secondary" onclick="openSkillStudio()" style="font-size:12px;padding:7px 12px;border-radius:6px;border:1px solid var(--border);background:transparent;color:var(--text-primary);cursor:pointer">Open Studio</button>
-              <button type="button" class="btn-primary" id="skill-composer-draft-btn" onclick="startSkillComposerDraft()" disabled style="font-size:12px;padding:7px 14px;border-radius:6px;border:none;background:var(--accent);color:#fff;font-weight:600;cursor:pointer;opacity:0.55">Draft skill</button>
+              <button type="button" class="btn-secondary" onclick="startSkillComposerChat()" style="font-size:12px;padding:7px 12px;border-radius:6px;border:1px solid var(--border);background:transparent;color:var(--text-primary);cursor:pointer">Build in chat</button>
+              <button type="button" class="btn-primary" id="skill-composer-draft-btn" onclick="startSkillComposerDraft()" disabled style="font-size:12px;padding:7px 14px;border-radius:6px;border:none;background:var(--accent);color:#fff;font-weight:600;cursor:pointer;opacity:0.55">Review draft</button>
             </div>
           </div>
         </div>
       </div>
+      </div>
       <div style="display:grid;grid-template-columns:380px 1fr;gap:18px;height:calc(100vh - 360px);min-height:440px">
         <div id="skills-list-pane" style="overflow-y:auto;border:1px solid var(--border);border-radius:8px;background:var(--bg-secondary)">
           <div style="padding:14px 16px;border-bottom:1px solid var(--border);display:flex;align-items:center;gap:8px">
@@ -23906,7 +23916,7 @@ function openCommandK() {
     { kw: 'home activity',      page: 'home',     tab: 'activity',     label: 'Home · Activity' },
     { kw: 'build workflows workflow builder', page: 'build', tab: 'workflows', label: 'Build · Workflow Builder' },
     { kw: 'build crons schedules scheduled tasks operations automation', page: 'build', tab: 'crons', label: 'Build · Schedules' },
-    { kw: 'build skills',       page: 'build',    tab: 'skills',       label: 'Build · Skills' },
+    { kw: 'build skills skill studio create skill', page: 'skills', tab: '', label: 'Skills · Skill Studio' },
     { kw: 'build templates',    page: 'build',    tab: 'templates',    label: 'Build · Templates' },
     { kw: 'team roster',        page: 'team',     tab: 'roster',       label: 'Team · Roster' },
     { kw: 'team activity',      page: 'team',     tab: 'activity',     label: 'Team · Activity' },
@@ -29214,6 +29224,17 @@ function startSkillComposerDraft() {
   openCreateSkillModalFromComposer({ draft: true });
 }
 
+function startSkillComposerChat() {
+  var prompt = buildSkillComposerPrompt();
+  if (typeof askClementineWith !== 'function') {
+    toast('Chat is not ready yet. Try again after the dashboard finishes loading.', 'error');
+    return;
+  }
+  closeSkillStudio({ silent: true });
+  askClementineWith(prompt, { autoSend: false });
+  toast('Skill-creator prompt loaded in chat. Press send when you are ready.', 'info');
+}
+
 function openCreateSkillModalFromComposer(opts) {
   opts = opts || {};
   var text = ((document.getElementById('skill-composer-text') || {}).value || '').trim();
@@ -29223,6 +29244,7 @@ function openCreateSkillModalFromComposer(opts) {
     return;
   }
   var seed = buildSkillComposerDraftSeed();
+  closeSkillStudio({ silent: true });
   _openSkillModal({ mode: 'create', prefill: seed });
   if (seed.note && typeof toast === 'function') toast(seed.note, 'success');
 }
@@ -29948,6 +29970,30 @@ async function sbRunSkillTest() {
   }
 }
 
+function askSkillCreatorForDescription() {
+  var name = (document.getElementById('skill-modal-name')?.value || '').trim();
+  var title = (document.getElementById('skill-modal-title')?.value || '').trim();
+  var desc = (document.getElementById('skill-modal-desc')?.value || '').trim();
+  var body = (document.getElementById('skill-modal-body')?.value || '').trim();
+  var prompt = [
+    'Use skill-creator principles to help write the frontmatter description for this Clementine skill.',
+    '',
+    'Skill name: ' + (name || '(not set yet)'),
+    'Title: ' + (title || '(not set yet)'),
+    'Current description: ' + (desc || '(empty)'),
+    'Procedure preview:',
+    body ? body.slice(0, 1600) : '(empty)',
+    '',
+    'Return one concise description under 1024 characters. It must say what the skill does, when to use it, and trigger phrases. Do not rewrite the whole skill unless I ask.'
+  ].join('\\n');
+  if (typeof askClementineWith !== 'function') {
+    toast('Chat is not ready yet. Try again after the dashboard finishes loading.', 'error');
+    return;
+  }
+  askClementineWith(prompt, { autoSend: false });
+  toast('Description prompt loaded in chat. Press send when ready.', 'info');
+}
+
 async function _openSkillModal(opts) {
   opts = opts || {};
   var prefill = opts.mode === 'create' && opts.prefill ? opts.prefill : {};
@@ -30003,7 +30049,7 @@ async function _openSkillModal(opts) {
       +       '<strong style="color:var(--text-secondary);font-weight:600">Format:</strong> '
       +       '<code style="font-size:10px;background:var(--bg-secondary);padding:1px 4px;border-radius:3px">[WHAT it does] + [WHEN to use it] + [trigger phrases]</code>'
       +       ' &nbsp;·&nbsp; under 1024 chars · no <code style="font-size:10px">&lt; &gt;</code> · '
-      +       '<a href="javascript:void(0)" onclick="askClementineWith(\\x27Use skill-creator to help me write a great Anthropic-canonical description for the skill I am building.\\x27)" style="color:var(--accent);text-decoration:none">use skill-creator</a>'
+      +       '<a href="javascript:void(0)" onclick="askSkillCreatorForDescription()" style="color:var(--accent);text-decoration:none">use skill-creator</a>'
       +     '</div>'
       +     '<textarea id="skill-modal-desc" rows="2" oninput="updateSkillModalCounters()" placeholder="Example: Analyzes Outlook emails and drafts triage replies. Use when user asks to triage email or mentions inbox cleanup." style="width:100%;padding:8px 10px;font-size:13px;border:1px solid var(--border);border-radius:6px;background:var(--bg-secondary);color:var(--text-primary);margin-bottom:12px;font-family:inherit;resize:vertical"></textarea>'
       +     '<label style="display:block;font-size:12px;color:var(--text-secondary);margin-bottom:4px;font-weight:500">Allowed tools <span style="color:var(--text-muted)">(comma-separated, leave blank for default)</span></label>'
@@ -30023,7 +30069,9 @@ async function _openSkillModal(opts) {
       + '</div>';
     document.body.appendChild(modal);
   }
-  document.getElementById('skill-modal-heading').textContent = opts.mode === 'edit' ? 'Edit skill: ' + nameVal : 'New skill';
+  document.getElementById('skill-modal-heading').textContent = opts.mode === 'edit'
+    ? 'Edit skill: ' + nameVal
+    : (prefill.note ? 'Review skill draft' : 'Manual skill editor');
   document.getElementById('skill-modal-original-name').value = opts.mode === 'edit' ? nameVal : '';
   document.getElementById('skill-modal-name').value = nameVal;
   document.getElementById('skill-modal-name').disabled = opts.mode === 'edit';
@@ -30044,7 +30092,8 @@ async function _openSkillModal(opts) {
   var errEl = document.getElementById('skill-modal-error');
   if (errEl) { errEl.style.display = 'none'; errEl.textContent = ''; }
   modal.style.display = 'flex';
-  document.getElementById('skill-modal-name').focus();
+  var initialFocus = prefill.note ? document.getElementById('skill-modal-desc') : document.getElementById('skill-modal-name');
+  if (initialFocus) initialFocus.focus();
   if (typeof updateSkillModalCounters === 'function') updateSkillModalCounters();
   if (typeof renderSkillModalToolsPreview === 'function') renderSkillModalToolsPreview();
   // 1.18.168 — render the compact optional template seed in create mode only.
@@ -35396,7 +35445,7 @@ document.addEventListener('click', function(e) {
 // Back-compat shim — older call sites still reference loadProfiles().
 function loadProfiles() { return refreshChatAgentPicker(); }
 
-// ── Skill Studio — opens the Skills page composer ──────────
+// ── Skill Studio — opens the natural-language composer as a real modal ──────────
 
 function openSkillStudio() {
   navigateTo('skills');
@@ -35404,15 +35453,56 @@ function openSkillStudio() {
     try { initSkillComposer(); } catch (_) { /* non-fatal */ }
     var composer = document.getElementById('skill-composer');
     var input = document.getElementById('skill-composer-text');
-    if (composer && composer.scrollIntoView) composer.scrollIntoView({ behavior: 'smooth', block: 'start' });
-    if (composer) {
-      composer.style.boxShadow = '0 0 0 2px rgba(255,141,0,0.35)';
-      setTimeout(function() { composer.style.boxShadow = ''; }, 1400);
+    var modal = document.getElementById('skill-studio-modal');
+    if (!modal) {
+      modal = document.createElement('div');
+      modal.id = 'skill-studio-modal';
+      modal.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,0.42);z-index:1050;display:none;align-items:center;justify-content:center;padding:20px';
+      modal.innerHTML =
+        '<div style="width:min(1040px,96vw);max-height:92vh;background:var(--bg-primary);border:1px solid var(--border);border-radius:10px;box-shadow:0 18px 56px rgba(0,0,0,0.35);display:flex;flex-direction:column;overflow:hidden">'
+        + '<div style="display:flex;align-items:flex-start;justify-content:space-between;gap:14px;padding:16px 20px;border-bottom:1px solid var(--border);background:var(--bg-secondary)">'
+        +   '<div style="min-width:0">'
+        +     '<div style="font-size:16px;font-weight:600;color:var(--text-primary);margin-bottom:3px">Skill Studio</div>'
+        +     '<div style="font-size:12px;color:var(--text-muted);line-height:1.45">Start with the outcome. Add MCP, CLI, project, or memory anchors only when they are real dependencies. Review the generated SKILL.md before saving.</div>'
+        +   '</div>'
+        +   '<button type="button" onclick="closeSkillStudio()" title="Close Skill Studio" style="background:none;border:none;font-size:20px;color:var(--text-muted);cursor:pointer;padding:0 4px;line-height:1">&times;</button>'
+        + '</div>'
+        + '<div id="skill-studio-modal-body" style="padding:18px 20px;overflow:auto;flex:1;min-height:0"></div>'
+        + '<div style="display:flex;align-items:center;gap:8px;justify-content:flex-end;padding:14px 20px;border-top:1px solid var(--border);background:var(--bg-secondary)">'
+        +   '<button type="button" onclick="closeSkillStudio()" style="font-size:13px;padding:7px 14px;border-radius:6px;border:1px solid var(--border);background:transparent;color:var(--text-primary);cursor:pointer">Keep on page</button>'
+        +   '<button type="button" onclick="startSkillComposerChat()" style="font-size:13px;padding:7px 14px;border-radius:6px;border:1px solid var(--border);background:var(--bg-primary);color:var(--text-primary);cursor:pointer">Build in chat</button>'
+        +   '<button type="button" onclick="startSkillComposerDraft()" class="btn-primary" style="font-size:13px;padding:7px 16px;border-radius:6px;border:none;background:var(--accent);color:#fff;font-weight:600;cursor:pointer">Review draft</button>'
+        + '</div>'
+        + '</div>';
+      document.body.appendChild(modal);
     }
+    var body = document.getElementById('skill-studio-modal-body');
+    if (composer && body && composer.parentElement !== body) {
+      composer.dataset.originalMargin = composer.style.margin || '';
+      body.appendChild(composer);
+      composer.style.margin = '0';
+    }
+    modal.style.display = 'flex';
+    updateSkillComposerDraftState();
     if (input) input.focus();
   }, 80);
 }
 
+function closeSkillStudio(opts) {
+  opts = opts || {};
+  var modal = document.getElementById('skill-studio-modal');
+  var composer = document.getElementById('skill-composer');
+  var home = document.getElementById('skill-composer-home');
+  if (composer && home && composer.parentElement !== home) {
+    home.appendChild(composer);
+    composer.style.margin = composer.dataset.originalMargin || '0 0 16px';
+  }
+  if (modal) modal.style.display = 'none';
+  if (!opts.silent && composer && composer.scrollIntoView) {
+    composer.scrollIntoView({ behavior: 'smooth', block: 'start' });
+  }
+}
+
 function updateBuilderMode() {
   var type = (document.getElementById('builder-type') || {}).value || 'skill';
   var title = document.getElementById('builder-page-title');

package/package.json

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