clementine-agent 1.18.123 → 1.18.125

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

@@ -43,6 +43,42 @@ export declare function computeEffectiveAllowedTools(jobAllow: string[] | undefi
  * MCP allowlist set.
  */
 export declare function applyMcpAllowlist<T>(servers: Record<string, T>, jobAllowedMcpServers: string[] | undefined): Record<string, T>;
+/**
+ * Widen the cron's tool allowlist with the union of pinned-skill
+ * `clementine.tools.allow` declarations.
+ *
+ * **Why this exists:** Pinning a skill is a positive user signal — "I want
+ * this skill, with the tools it declares it needs." Before 1.18.125 the
+ * skill's `tools.allow` was rendered into the prompt as text only; the SDK
+ * never saw it, so a skill pinned to a cron with a narrower allowlist would
+ * silently fail with tool-not-found errors.
+ *
+ * **Semantics:**
+ *   - Cron has no allowlist → return undefined (cron is unrestricted; pinned
+ *     skill tools flow through the profile/default fallback in `runAgent`).
+ *     We deliberately don't synthesize an allowlist out of just skill tools
+ *     here, because that would NARROW an unrestricted cron to "only what the
+ *     skills declared."
+ *   - Cron has allowlist + skills declared tools → return the union (skills
+ *     widen, never narrow, an existing constraint).
+ *   - Cron has allowlist + no pinned-skill tools → return the cron's allowlist
+ *     unchanged.
+ */
+export declare function widenAllowlistWithSkillTools(jobAllow: string[] | undefined, pinnedSkillTools: string[] | undefined): string[] | undefined;
+/**
+ * Extract every distinct `mcp__<server>__<tool>` server name referenced
+ * inside the bodies of pinned skills. Empty array when no references found.
+ */
+export declare function extractMcpServersFromSkillBodies(bodies: string[]): string[];
+/**
+ * Widen the cron's MCP-server allowlist with servers referenced inside
+ * pinned-skill bodies (e.g., a skill that calls `mcp__gmail__send_message`
+ * implicitly needs the `gmail` server connected).
+ *
+ * Same semantics as `widenAllowlistWithSkillTools`: only widens an existing
+ * allowlist; doesn't synthesize one when the cron is unrestricted.
+ */
+export declare function widenMcpAllowlistWithSkillRefs(jobMcpAllow: string[] | undefined, skillReferencedServers: string[]): string[] | undefined;
 export interface SkillContextResult {
     /** The rendered "Learned Procedures" block (or empty string when no skills loaded). */
     text: string;
@@ -54,6 +90,16 @@ export interface SkillContextResult {
     }>;
     /** Pinned slugs that didn't resolve (deleted/renamed/suppressed). Logged + surfaced. */
     missing: string[];
+    /** Union of every `clementine.tools.allow` entry from pinned skills. Used by
+     *  `buildCronExecutionPlan` to widen the cron's tool allowlist so a pinned
+     *  skill's declared tools survive into the SDK call. Empty array when no
+     *  pinned skill declared a `tools.allow` list. Auto-matched skills do NOT
+     *  contribute — only explicit pins widen scope. */
+    pinnedToolsRequested: string[];
+    /** Bodies of pinned skills only — used for `mcp__server__tool` reference
+     *  extraction so a skill's MCP usage propagates to `allowedMcpServers`.
+     *  Auto-matched skills excluded for the same reason as above. */
+    pinnedBodies: string[];
 }
 /**
  * Build the matched-skills block (procedures learned from prior successful runs).
@@ -196,6 +242,18 @@ export interface CronExecutionPlan {
      *  being set inside the skill folder. Deduped + filtered to existing
      *  paths. Empty when the trick has no addDirs and no folder-form pins. */
     additionalDirectories: string[];
+    /** Diagnostics: which scopes a pinned skill widened on this run. Empty
+     *  arrays when no widening happened. Surfaced in the Preview UI so users
+     *  see "this skill brought in `Bash` and `gmail` MCP" without reading
+     *  source. */
+    widenedFromSkills: {
+        /** Tool names a pinned skill's `clementine.tools.allow` added on top of
+         *  the cron's own allowlist. Empty when nothing was widened. */
+        tools: string[];
+        /** MCP server names a pinned skill's body referenced (`mcp__server__tool`)
+         *  that the cron's `allowedMcpServers` didn't already include. */
+        mcpServers: string[];
+    };
 }
 /**
  * Plan a cron run — assemble all context, resolve skills, intersect tool/MCP

package/dist/agent/run-agent-cron.js

@@ -72,6 +72,70 @@ export function applyMcpAllowlist(servers, jobAllowedMcpServers) {
     const allow = new Set(jobAllowedMcpServers);
     return Object.fromEntries(Object.entries(servers).filter(([name]) => allow.has(name)));
 }
+/**
+ * Widen the cron's tool allowlist with the union of pinned-skill
+ * `clementine.tools.allow` declarations.
+ *
+ * **Why this exists:** Pinning a skill is a positive user signal — "I want
+ * this skill, with the tools it declares it needs." Before 1.18.125 the
+ * skill's `tools.allow` was rendered into the prompt as text only; the SDK
+ * never saw it, so a skill pinned to a cron with a narrower allowlist would
+ * silently fail with tool-not-found errors.
+ *
+ * **Semantics:**
+ *   - Cron has no allowlist → return undefined (cron is unrestricted; pinned
+ *     skill tools flow through the profile/default fallback in `runAgent`).
+ *     We deliberately don't synthesize an allowlist out of just skill tools
+ *     here, because that would NARROW an unrestricted cron to "only what the
+ *     skills declared."
+ *   - Cron has allowlist + skills declared tools → return the union (skills
+ *     widen, never narrow, an existing constraint).
+ *   - Cron has allowlist + no pinned-skill tools → return the cron's allowlist
+ *     unchanged.
+ */
+export function widenAllowlistWithSkillTools(jobAllow, pinnedSkillTools) {
+    if (!jobAllow?.length)
+        return undefined;
+    if (!pinnedSkillTools?.length)
+        return [...jobAllow];
+    return [...new Set([...jobAllow, ...pinnedSkillTools])];
+}
+/** Match `mcp__SERVER__TOOL` references in skill body Markdown.
+ *  Server names can contain single underscores (`Bright_Data`,
+ *  `claude_ai_Microsoft_365`) but never `__` (double-underscore is the
+ *  delimiter). The regex captures the server segment between the leading
+ *  `mcp__` and the next `__`. Anchored on word boundaries so it doesn't
+ *  catch substrings of longer identifiers. */
+const MCP_TOOL_REF = /mcp__([A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*)__/g;
+/**
+ * Extract every distinct `mcp__<server>__<tool>` server name referenced
+ * inside the bodies of pinned skills. Empty array when no references found.
+ */
+export function extractMcpServersFromSkillBodies(bodies) {
+    const found = new Set();
+    for (const body of bodies) {
+        if (!body)
+            continue;
+        for (const m of body.matchAll(MCP_TOOL_REF))
+            found.add(m[1]);
+    }
+    return [...found];
+}
+/**
+ * Widen the cron's MCP-server allowlist with servers referenced inside
+ * pinned-skill bodies (e.g., a skill that calls `mcp__gmail__send_message`
+ * implicitly needs the `gmail` server connected).
+ *
+ * Same semantics as `widenAllowlistWithSkillTools`: only widens an existing
+ * allowlist; doesn't synthesize one when the cron is unrestricted.
+ */
+export function widenMcpAllowlistWithSkillRefs(jobMcpAllow, skillReferencedServers) {
+    if (!jobMcpAllow?.length)
+        return undefined;
+    if (!skillReferencedServers.length)
+        return [...jobMcpAllow];
+    return [...new Set([...jobMcpAllow, ...skillReferencedServers])];
+}
 function capContextItem(s) {
     if (!s)
         return '';
@@ -235,6 +299,8 @@ function buildCriteriaContext(successCriteria) {
 export async function buildSkillContext(jobName, jobPrompt, agentSlug, pinnedSkills, memoryStore, opts) {
     const applied = [];
     const missing = [];
+    const pinnedToolsRequested = [];
+    const pinnedBodies = [];
     try {
         const { searchSkills, recordSkillUse, loadSkillByName } = await import('./skill-extractor.js');
         const skillQuery = jobName + ' ' + jobPrompt.slice(0, 200);
@@ -305,8 +371,23 @@ export async function buildSkillContext(jobName, jobPrompt, agentSlug, pinnedSki
                 seen.add(m.name);
             }
         }
+        // 1.18.125 — collect pinned-skill tool declarations + bodies so the
+        // cron planner can widen `allowedTools` / `allowedMcpServers` with what
+        // the pinned skills explicitly need. Pins (not auto-matches) widen scope
+        // because pinning is the user's explicit signal of intent.
+        const pinnedSeen = new Set();
+        for (const s of prepared) {
+            if (s.source !== 'pinned')
+                continue;
+            if (pinnedSeen.has(s.name))
+                continue;
+            pinnedSeen.add(s.name);
+            for (const t of s.toolsUsed)
+                pinnedToolsRequested.push(t);
+            pinnedBodies.push(s.content);
+        }
         if (prepared.length === 0)
-            return { text: '', applied, missing };
+            return { text: '', applied, missing, pinnedToolsRequested: [], pinnedBodies: [] };
         // Folder-form bundled-file budget. Anthropic skill spec says the body
         // should be ≤500 lines; bundled files (templates/, reference docs)
         // load on top. We cap aggregate inlined bundle bytes so a skill with a
@@ -398,11 +479,11 @@ export async function buildSkillContext(jobName, jobPrompt, agentSlug, pinnedSki
             return block;
         });
         const text = `## Learned Procedures (from past successful executions)\nFollow these proven approaches when applicable:\n\n${skillLines.join('\n\n')}\n\n`;
-        return { text, applied, missing };
+        return { text, applied, missing, pinnedToolsRequested: [...new Set(pinnedToolsRequested)], pinnedBodies };
     }
     catch (err) {
         logger.debug({ err, jobName }, 'buildSkillContext failed (non-fatal)');
-        return { text: '', applied, missing };
+        return { text: '', applied, missing, pinnedToolsRequested: [], pinnedBodies: [] };
     }
 }
 /**
@@ -463,15 +544,25 @@ export async function buildCronExecutionPlan(opts) {
         ].filter(Boolean).join('\n\n'),
         profile: opts.profile,
     });
+    // 1.18.125 — pinned-skill scope widening (SDK alignment).
+    // A pinned skill that declares `clementine.tools.allow` or references
+    // `mcp__server__tool` in its body needs those tools/servers to actually
+    // be live for the SDK call — not just rendered into the prompt as text.
+    // We widen (never narrow) the cron's allowlists with what the pinned
+    // skills declared. Auto-matched skills don't widen scope (only explicit
+    // pins do — the user's positive signal).
+    const skillReferencedMcpServers = extractMcpServersFromSkillBodies(skillResult.pinnedBodies);
+    const widenedJobAllowedTools = widenAllowlistWithSkillTools(opts.allowedTools, skillResult.pinnedToolsRequested);
+    const widenedJobMcpAllowlist = widenMcpAllowlistWithSkillRefs(opts.allowedMcpServers, skillReferencedMcpServers);
     // Per-trick MCP allowlist: post-filter on the profile-narrowed map.
-    // Effective set = profile ∩ trick.
-    const mcpServerMap = applyMcpAllowlist(mcp.servers, opts.allowedMcpServers);
-    const allowSet = opts.allowedMcpServers?.length ? new Set(opts.allowedMcpServers) : null;
+    // Effective set = profile ∩ trick (widened).
+    const mcpServerMap = applyMcpAllowlist(mcp.servers, widenedJobMcpAllowlist);
+    const allowSet = widenedJobMcpAllowlist?.length ? new Set(widenedJobMcpAllowlist) : null;
     const composioConnected = allowSet ? mcp.composioConnected.filter(n => allowSet.has(n)) : mcp.composioConnected;
     const externalConnected = allowSet ? mcp.externalConnected.filter(n => allowSet.has(n)) : mcp.externalConnected;
     const mcpServersApplied = Object.keys(mcpServerMap);
-    // Per-trick tool allowlist intersection.
-    const effectiveAllowedTools = computeEffectiveAllowedTools(opts.allowedTools, opts.profile?.team?.allowedTools);
+    // Per-trick tool allowlist intersection (widened by pinned-skill needs).
+    const effectiveAllowedTools = computeEffectiveAllowedTools(widenedJobAllowedTools, opts.profile?.team?.allowedTools);
     // Per-tier cap from config (BUDGET.cronT1 / BUDGET.cronT2). 0 = uncapped.
     const configuredCap = tier >= 2 ? BUDGET.cronT2 : BUDGET.cronT1;
     const maxBudget = opts.maxBudgetUsd ?? (configuredCap > 0 ? configuredCap : undefined);
@@ -516,6 +607,12 @@ export async function buildCronExecutionPlan(opts) {
             return false;
         }
     });
+    // Diagnostics: what did the pinned skills add on top of what the cron
+    // already declared? Renders in the Preview UI as "Skill widened scope: …"
+    const baseToolSet = new Set(opts.allowedTools ?? []);
+    const widenedToolsFromSkills = skillResult.pinnedToolsRequested.filter(t => !baseToolSet.has(t));
+    const baseMcpSet = new Set(opts.allowedMcpServers ?? []);
+    const widenedMcpFromSkills = skillReferencedMcpServers.filter(s => !baseMcpSet.has(s));
     return {
         builtPrompt,
         contextBlocks: {
@@ -537,6 +634,13 @@ export async function buildCronExecutionPlan(opts) {
         ownerName,
         predictable,
         additionalDirectories,
+        widenedFromSkills: {
+            // Only surface widening when the cron actually had a base allowlist —
+            // otherwise the cron is unrestricted and "widening" isn't a meaningful
+            // concept (the skills' tools were already implicitly allowed).
+            tools: opts.allowedTools?.length ? widenedToolsFromSkills : [],
+            mcpServers: opts.allowedMcpServers?.length ? widenedMcpFromSkills : [],
+        },
     };
 }
 /**
@@ -565,6 +669,7 @@ export async function runAgentCron(opts) {
         skillsMissing: plan.skillsMissing.length,
         trickAllowedTools: effectiveAllowedTools?.length,
         trickAllowedMcp: opts.allowedMcpServers?.length,
+        widenedFromSkills: plan.widenedFromSkills,
     }, 'runAgentCron: dispatching to runAgent');
     const startedAt = Date.now();
     const result = await runAgent(builtPrompt, {

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

@@ -29,10 +29,10 @@ export declare function extractSkill(assistant: PersonalAssistant, context: {
     durationMs: number;
 }): Promise<SkillDocument | null>;
 /** Move a pending skill to the active skills directory. */
-export declare function approvePendingSkill(name: string): {
+export declare function approvePendingSkill(name: string): Promise<{
     ok: boolean;
     message: string;
-};
+}>;
 /** Delete a pending skill (reject it). */
 export declare function rejectPendingSkill(name: string): {
     ok: boolean;

package/dist/agent/skill-extractor.js

@@ -121,43 +121,44 @@ function savePendingSkill(skill) {
     logger.info({ name: skill.name, source: skill.source }, 'Skill queued for approval');
 }
 /** Save an approved skill as a formatted markdown file. Agent-scoped if agentSlug set. */
-function saveActiveSkill(skill) {
+// 1.18.124 — saveActiveSkill is now a thin wrapper around the shared
+// writeSkill helper. Auto-extracted skills used to land as legacy flat-
+// form (`<name>.md` with top-level triggers/toolsUsed/source) which the
+// Skills page tagged with the orange "LEGACY" badge — confusing on a
+// fresh install. Now they write the same Anthropic-canonical folder
+// form the dashboard + chat paths produce.
+//
+// Also drops the per-overwrite `.md.bak` leak — that was paranoia
+// before the skill catalog had proper provenance. The pending file
+// in PENDING_SKILLS_DIR is the rollback artifact.
+async function saveActiveSkill(skill) {
     ensureDirs();
-    const targetDir = skill.agentSlug ? agentSkillsDir(skill.agentSlug) : GLOBAL_SKILLS_DIR;
-    if (!existsSync(targetDir))
-        mkdirSync(targetDir, { recursive: true });
-    // gray-matter's YAML dumper throws on undefined values — omit them
-    const frontmatter = {
+    const { writeSkill } = await import('./skill-store.js');
+    // Map SkillDocument's source enum (which still has 'unleashed'/'cron'
+    // for back-compat with old pending-skill JSONs on disk) to the
+    // writeSkill source enum.
+    const writeSource = skill.source === 'unleashed' || skill.source === 'cron' ? 'auto'
+        : skill.source === 'chat' ? 'chat'
+            : 'manual';
+    const result = writeSkill({
+        name: skill.name,
         title: skill.title,
         description: skill.description,
+        // Procedure body only — title/description live in frontmatter
+        // under the new schema, no need to repeat them inside the body.
+        body: skill.steps,
+        tools: skill.toolsUsed,
         triggers: skill.triggers,
-        source: skill.source,
-        toolsUsed: skill.toolsUsed,
-        useCount: skill.useCount,
-        createdAt: skill.createdAt,
-        updatedAt: skill.updatedAt,
-    };
-    if (skill.sourceJob)
-        frontmatter.sourceJob = skill.sourceJob;
-    if (skill.agentSlug)
-        frontmatter.agentSlug = skill.agentSlug;
-    if (skill.lastUsed)
-        frontmatter.lastUsed = skill.lastUsed;
-    const content = matter.stringify(`\n# ${skill.title}\n\n${skill.description}\n\n## Procedure\n\n${skill.steps}\n`, frontmatter);
-    const filePath = path.join(targetDir, `${skill.name}.md`);
-    // Backup existing before overwrite
-    if (existsSync(filePath)) {
-        try {
-            copyFileSync(filePath, filePath.replace(/\.md$/, '.md.bak'));
-        }
-        catch { /* best-effort */ }
-    }
-    writeFileSync(filePath, content);
-    logger.info({ name: skill.name, source: skill.source, agentSlug: skill.agentSlug ?? 'global' }, 'Skill saved');
+        agentSlug: skill.agentSlug,
+        source: writeSource,
+        sourceJob: skill.sourceJob,
+        overwrite: true, // approve / merge always replaces in-place
+    });
+    logger.info({ name: skill.name, source: skill.source, agentSlug: skill.agentSlug ?? 'global', filePath: result.filePath, overwrote: result.overwrote }, 'Skill saved');
 }
 // ── Pending Skill Management ────────────────────────────────────────
 /** Move a pending skill to the active skills directory. */
-export function approvePendingSkill(name) {
+export async function approvePendingSkill(name) {
     ensureDirs();
     const pendingFile = path.join(PENDING_SKILLS_DIR, `${name}.json`);
     if (!existsSync(pendingFile)) {
@@ -166,7 +167,7 @@ export function approvePendingSkill(name) {
     try {
         const skill = JSON.parse(readFileSync(pendingFile, 'utf-8'));
         skill.updatedAt = new Date().toISOString();
-        saveActiveSkill(skill);
+        await saveActiveSkill(skill);
         unlinkSync(pendingFile);
         logger.info({ name }, 'Pending skill approved and activated');
         return { ok: true, message: `Skill **${skill.title}** is now active${skill.agentSlug ? ` for ${skill.agentSlug}` : ' (global)'}.` };
@@ -308,7 +309,7 @@ async function mergeSkill(assistant, existing, incoming) {
             updatedAt: new Date().toISOString(),
         };
         // Merges go directly to active (existing skill was already approved)
-        saveActiveSkill(merged);
+        await saveActiveSkill(merged);
         logger.info({ name: merged.name }, 'Skill merged and updated');
         return merged;
     }

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

@@ -77,5 +77,55 @@ export declare function migrateAllLegacySkills(): {
     migrated: MigrationResult[];
     skipped: MigrationResult[];
 };
+export interface WriteSkillInput {
+    /** Slug (lowercase letters/digits/dashes, ≤64 chars, Anthropic regex). */
+    name: string;
+    /** Human-readable display name. Optional. */
+    title?: string;
+    /** One-paragraph "what does this do, when should Claude run it" — required by spec. */
+    description: string;
+    /** Procedure body (Markdown). Required. */
+    body: string;
+    /** Where the skill came from. Drives lifecycle metadata + dashboard badge. */
+    source: 'manual' | 'chat' | 'auto' | 'imported';
+    /** Optional tool allowlist — stored under clementine.tools.allow. */
+    tools?: string[];
+    /** Optional NLP trigger phrases for auto-match — stored under clementine.triggers. */
+    triggers?: string[];
+    /** Optional agent scope. When set, writes to <agentsDir>/<slug>/skills/
+     *  instead of the global skills dir. Used by auto-extraction so each
+     *  hired agent's skills stay isolated by default. */
+    agentSlug?: string;
+    /** When true, allow overwriting an existing skill (used by update flows). */
+    overwrite?: boolean;
+    /** Optional source-job tag (auto-extraction provenance). */
+    sourceJob?: string;
+}
+export interface WriteSkillResult {
+    /** Absolute path to the written SKILL.md. */
+    filePath: string;
+    /** Slug (matches input name). */
+    name: string;
+    /** Whether an existing skill was overwritten. */
+    overwrote: boolean;
+}
+export declare function writeSkill(input: WriteSkillInput): WriteSkillResult;
+export interface SkillBackupSweepResult {
+    /** Files removed this pass. Absolute paths. */
+    removed: string[];
+    /** Files inspected (matched the pattern). Useful for "nothing to do" telemetry. */
+    inspected: number;
+    /** Files that matched the pattern but were younger than the cutoff (kept). */
+    keptFresh: number;
+}
+/**
+ * Sweep `.md.bak` skill backups older than `LEGACY_BAK_AGE_DAYS` from the
+ * global skills directory and from every per-agent skills directory under
+ * `00-System/agents/<slug>/skills/`. Best-effort: per-file errors are
+ * swallowed so a permission glitch on one file doesn't stop the sweep.
+ *
+ * Idempotent — safe to call repeatedly. Returns counts for logging.
+ */
+export declare function cleanupLegacySkillBackups(): SkillBackupSweepResult;
 export {};
 //# sourceMappingURL=skill-store.d.ts.map

package/dist/agent/skill-store.js

@@ -21,7 +21,7 @@
  * runner. Phase C wires runtime invocation. Phase E migrates legacy
  * crons → folder-form skills.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import matter from 'gray-matter';
@@ -647,4 +647,149 @@ export function migrateAllLegacySkills() {
     }
     return { migrated, skipped };
 }
+export function writeSkill(input) {
+    // Validate name per Anthropic spec — single guard for every caller.
+    if (!input.name || !NAME_PATTERN.test(input.name)) {
+        throw new Error('writeSkill: name must match ^[a-z0-9][a-z0-9-]{0,63}$');
+    }
+    if (input.name.length > NAME_MAX_LEN) {
+        throw new Error(`writeSkill: name exceeds ${NAME_MAX_LEN} chars`);
+    }
+    if (RESERVED_NAMES.has(input.name) || /\b(anthropic|claude)\b/i.test(input.name)) {
+        throw new Error(`writeSkill: name uses a reserved word`);
+    }
+    if (!input.description || !input.description.trim()) {
+        throw new Error('writeSkill: description is required');
+    }
+    if (input.description.length > DESCRIPTION_MAX_LEN) {
+        throw new Error(`writeSkill: description exceeds ${DESCRIPTION_MAX_LEN} chars`);
+    }
+    if (!input.body || !input.body.trim()) {
+        throw new Error('writeSkill: body is required');
+    }
+    // Resolve target directory. Agent-scoped writes land under the agent's
+    // skills folder so each hired agent's skill set is independent.
+    const base = process.env.CLEMENTINE_HOME || path.join(os.homedir(), '.clementine');
+    const targetDir = input.agentSlug
+        ? path.join(base, 'vault', '00-System', 'agents', input.agentSlug, 'skills')
+        : globalSkillsDir();
+    if (!existsSync(targetDir))
+        mkdirSync(targetDir, { recursive: true });
+    const folderPath = path.join(targetDir, input.name);
+    const entryPath = path.join(folderPath, 'SKILL.md');
+    const existed = existsSync(entryPath);
+    if (existed && !input.overwrite) {
+        throw new Error(`writeSkill: skill "${input.name}" already exists`);
+    }
+    mkdirSync(folderPath, { recursive: true });
+    // Build the frontmatter. Anthropic-canonical fields (name, description)
+    // top-level. Everything else under clementine:. The lifecycle metadata
+    // (createdAt / updatedAt / version) keeps the Skills page detail pane
+    // accurate without authors having to remember to set it by hand.
+    const now = new Date().toISOString();
+    const fm = {
+        name: input.name,
+        description: input.description.trim(),
+    };
+    if (input.title && input.title.trim())
+        fm.title = input.title.trim();
+    const ext = {
+        source: input.source,
+        useCount: 0,
+        createdAt: now,
+        updatedAt: now,
+        version: 1,
+    };
+    if (input.tools && input.tools.length > 0) {
+        ext.tools = { allow: input.tools.map(String).map(s => s.trim()).filter(Boolean) };
+    }
+    if (input.triggers && input.triggers.length > 0) {
+        ext.triggers = input.triggers.map(String).map(s => s.trim()).filter(Boolean);
+    }
+    if (input.sourceJob)
+        ext.sourceJob = input.sourceJob;
+    fm.clementine = ext;
+    const content = matter.stringify(input.body.endsWith('\n') ? input.body : input.body + '\n', fm);
+    writeFileSync(entryPath, content);
+    return { filePath: entryPath, name: input.name, overwrote: existed };
+}
+// ── Legacy backup janitor (1.18.125) ─────────────────────────────────
+//
+// Pre-1.18.124, `saveActiveSkill` wrote a per-overwrite `.md.bak` next to
+// every skill it updated. The new `writeSkill` path doesn't create these,
+// but the old ones rot in the vault forever unless something sweeps them.
+// `cleanupLegacySkillBackups` finds `.md.bak` files older than the cutoff
+// and removes them. Runs from the periodic memory-maintenance cycle so
+// users don't need to know it exists.
+//
+// Conservative: 30-day age floor + only the slug-named `.md.bak` pattern.
+// Anything mtime-recent stays put in case a user is mid-rollback.
+const LEGACY_BAK_AGE_DAYS = 30;
+const LEGACY_BAK_AGE_MS = LEGACY_BAK_AGE_DAYS * 24 * 60 * 60 * 1000;
+/**
+ * Sweep `.md.bak` skill backups older than `LEGACY_BAK_AGE_DAYS` from the
+ * global skills directory and from every per-agent skills directory under
+ * `00-System/agents/<slug>/skills/`. Best-effort: per-file errors are
+ * swallowed so a permission glitch on one file doesn't stop the sweep.
+ *
+ * Idempotent — safe to call repeatedly. Returns counts for logging.
+ */
+export function cleanupLegacySkillBackups() {
+    const result = { removed: [], inspected: 0, keptFresh: 0 };
+    const cutoff = Date.now() - LEGACY_BAK_AGE_MS;
+    const sweepRoots = [globalSkillsDir()];
+    // Per-agent skill dirs — discover via the agents/ folder.
+    try {
+        const base = process.env.CLEMENTINE_HOME || path.join(os.homedir(), '.clementine');
+        const agentsDir = path.join(base, 'vault', '00-System', 'agents');
+        if (existsSync(agentsDir)) {
+            for (const entry of readdirSync(agentsDir)) {
+                if (entry.startsWith('.'))
+                    continue;
+                const agentSkillsDir = path.join(agentsDir, entry, 'skills');
+                if (existsSync(agentSkillsDir))
+                    sweepRoots.push(agentSkillsDir);
+            }
+        }
+    }
+    catch { /* non-fatal — global sweep still runs */ }
+    for (const root of sweepRoots) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            // Match exactly the legacy pattern. Don't touch anything else — we
+            // never want to nuke `templates/old-draft.md.bak` inside a folder skill,
+            // for instance. The legacy writer only ever produced flat
+            // `<slug>.md.bak` siblings, so that's all we sweep.
+            if (!entry.endsWith('.md.bak'))
+                continue;
+            const full = path.join(root, entry);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            result.inspected++;
+            if (st.mtimeMs > cutoff) {
+                result.keptFresh++;
+                continue;
+            }
+            try {
+                unlinkSync(full);
+                result.removed.push(full);
+            }
+            catch { /* skip — permission or race; next sweep retries */ }
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=skill-store.js.map

package/dist/cli/dashboard.js

@@ -10293,7 +10293,7 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
     app.post('/api/skills/pending/:name/approve', async (req, res) => {
         try {
             const { approvePendingSkill } = await import('../agent/skill-extractor.js');
-            const result = approvePendingSkill(req.params.name);
+            const result = await approvePendingSkill(req.params.name);
             if (!result.ok) {
                 res.status(404).json(result);
                 return;
@@ -10318,63 +10318,43 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.status(500).json({ error: String(err) });
         }
     });
-    // POST /api/skills — create a new folder-form skill (1.18.115).
-    // Anthropic-compatible: top-level `name` + `description` required; the
-    // optional `tools` array goes under `clementine.tools.allow` so the
-    // frontmatter parses cleanly in vanilla Claude Agent SDK while still
-    // letting the cron runtime enforce the allowlist.
-    app.post('/api/skills', (req, res) => {
+    // POST /api/skills — create a new folder-form skill via the shared
+    // writeSkill helper (1.18.124). All three skill-creation paths
+    // (dashboard, MCP create_skill, auto-extraction) flow through the
+    // same write-once-validate-once code; this route is now a thin
+    // adapter over the helper.
+    app.post('/api/skills', async (req, res) => {
         try {
             const { name, title, description, body, tools } = req.body ?? {};
-            if (!name || typeof name !== 'string') {
-                res.status(400).json({ error: 'name is required' });
-                return;
-            }
-            if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
-                res.status(400).json({ error: 'name must match ^[a-z0-9][a-z0-9-]{0,63}$ (Anthropic spec)' });
-                return;
-            }
-            if (!description || typeof description !== 'string') {
-                res.status(400).json({ error: 'description is required' });
-                return;
-            }
-            if (description.length > 1024) {
-                res.status(400).json({ error: 'description must be ≤ 1024 chars (Anthropic spec)' });
+            if (typeof name !== 'string' || typeof description !== 'string' || typeof body !== 'string') {
+                res.status(400).json({ error: 'name, description, and body are required strings' });
                 return;
             }
-            if (!body || typeof body !== 'string' || !body.trim()) {
-                res.status(400).json({ error: 'body is required' });
-                return;
+            const { writeSkill } = await import('../agent/skill-store.js');
+            try {
+                const result = writeSkill({
+                    name,
+                    title: typeof title === 'string' ? title : undefined,
+                    description,
+                    body,
+                    tools: Array.isArray(tools) ? tools.map(String) : undefined,
+                    source: 'manual',
+                });
+                res.json({ ok: true, name: result.name, layout: 'folder', filePath: result.filePath });
             }
-            const skillsDir = path.join(VAULT_DIR, '00-System', 'skills');
-            if (!existsSync(skillsDir))
-                mkdirSync(skillsDir, { recursive: true });
-            const folderPath = path.join(skillsDir, name);
-            const entryPath = path.join(folderPath, 'SKILL.md');
-            if (existsSync(entryPath)) {
-                res.status(409).json({ error: 'Skill "' + name + '" already exists. Use PUT to update.' });
-                return;
+            catch (err) {
+                // writeSkill throws synchronously with a readable message for
+                // every validation failure (name regex, description length,
+                // already-exists, etc.). Surface them as 4xx; only unexpected
+                // I/O errors hit the outer 500 path below.
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes('already exists')) {
+                    res.status(409).json({ error: msg });
+                }
+                else {
+                    res.status(400).json({ error: msg });
+                }
             }
-            mkdirSync(folderPath, { recursive: true });
-            const now = new Date().toISOString();
-            const fm = { name, description };
-            if (title && typeof title === 'string' && title.trim())
-                fm.title = title.trim();
-            const allowed = Array.isArray(tools) ? tools.map(String).map(s => s.trim()).filter(Boolean) : [];
-            const clementineExt = {
-                source: 'manual',
-                useCount: 0,
-                createdAt: now,
-                updatedAt: now,
-                version: 1,
-            };
-            if (allowed.length > 0)
-                clementineExt.tools = { allow: allowed };
-            fm.clementine = clementineExt;
-            const matterMod = require('gray-matter');
-            const content = matterMod.stringify(body.endsWith('\n') ? body : body + '\n', fm);
-            writeFileSync(entryPath, content);
-            res.json({ ok: true, name, layout: 'folder', filePath: entryPath });
         }
         catch (err) {
             res.status(500).json({ error: String(err) });

package/dist/cli/index.js

@@ -2832,7 +2832,7 @@ skillsCmd
     try {
         process.env.CLEMENTINE_HOME = BASE_DIR;
         const { approvePendingSkill } = await import('../agent/skill-extractor.js');
-        const result = approvePendingSkill(name);
+        const result = await approvePendingSkill(name);
         if (result.ok) {
             console.log(`  ${GREEN}✓${RESET} ${result.message}`);
         }

package/dist/gateway/router.js

@@ -1068,7 +1068,7 @@ export class Gateway {
             case 'approve': {
                 if (!args?.name)
                     return 'Missing skill name.';
-                const result = approvePendingSkill(args.name);
+                const result = await approvePendingSkill(args.name);
                 return result.message;
             }
             case 'reject': {

package/dist/memory/maintenance.js

@@ -146,6 +146,19 @@ export async function runStartupMaintenance(store) {
     catch (err) {
         logger.warn({ err }, 'Startup janitor failed');
     }
+    // Vault janitor (1.18.125) — sweep legacy `.md.bak` skill backups so the
+    // first daemon boot after upgrade clears the existing leak instead of
+    // waiting 6h for the periodic cycle.
+    try {
+        const { cleanupLegacySkillBackups } = await import('../agent/skill-store.js');
+        const sweep = cleanupLegacySkillBackups();
+        if (sweep.removed.length > 0) {
+            logger.info({ removed: sweep.removed.length, inspected: sweep.inspected, keptFresh: sweep.keptFresh }, 'Startup .md.bak sweep');
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Startup .md.bak sweep failed');
+    }
     // Embedding warm-up — pre-embed the most-cited chunks in the background so
     // the first retrievals after startup don't pay cold-start latency. Fire
     // and forget; never blocks startup.
@@ -247,6 +260,20 @@ export async function runPeriodicCycle(store, llmCall) {
     catch (err) {
         logger.warn({ err }, 'Periodic janitor failed');
     }
+    // 6a. Vault janitor — sweep legacy `.md.bak` skill backups (1.18.125).
+    // Pre-1.18.124 saveActiveSkill wrote per-overwrite backups; the new
+    // writeSkill path doesn't, so the old ones rot in the vault. Cap age
+    // at 30 days to give rollback room. No-op when nothing to sweep.
+    try {
+        const { cleanupLegacySkillBackups } = await import('../agent/skill-store.js');
+        const sweep = cleanupLegacySkillBackups();
+        if (sweep.removed.length > 0) {
+            logger.info({ removed: sweep.removed.length, inspected: sweep.inspected, keptFresh: sweep.keptFresh }, 'Legacy skill .md.bak sweep');
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Legacy skill .md.bak sweep failed');
+    }
     // 6b. Integrity probes — FTS health, orphan derived_from, embedding gaps.
     try {
         const report = runIntegrityProbes(store);

package/dist/tools/skill-tools.js

@@ -17,16 +17,16 @@
  * description, body presence) is enforced by both the dashboard endpoint
  * and these tools, so you can't smuggle a bad skill through the chat path.
  */
-import { writeFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
 import matter from 'gray-matter';
 import { VAULT_DIR, textResult, logger } from './shared.js';
-// Anthropic spec — keep these in sync with skill-store.validateSkill.
+// 1.18.124 — name regex is the only validator skill-tools still uses
+// directly (for update_skill's pre-flight slug check). All other
+// validations + the file write live in skill-store.writeSkill.
 const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
-const NAME_MAX_LEN = 64;
 const DESCRIPTION_MAX_LEN = 1024;
-const RESERVED_NAMES = new Set(['anthropic', 'claude']);
 function globalSkillsDir() {
     return path.join(VAULT_DIR, '00-System', 'skills');
 }
@@ -50,65 +50,37 @@ export function registerSkillTools(server) {
         triggers: z.array(z.string()).optional()
             .describe('Optional natural-language phrases that should auto-match this skill at runtime (e.g. ["morning deal review", "check deals today"]). Stored under clementine.triggers. Pinned skills don\'t need triggers — they fire by name.'),
     }, async ({ name, title, description, body, tools, triggers }) => {
-        // Validate per Anthropic spec
-        if (!NAME_PATTERN.test(name)) {
-            return textResult(`❌ Name "${name}" doesn't match the spec. Use lowercase letters, digits, and dashes only — must start with a letter or digit, max 64 chars.`);
-        }
-        if (name.length > NAME_MAX_LEN) {
-            return textResult(`❌ Name is too long (${name.length} chars). Max is ${NAME_MAX_LEN}.`);
-        }
-        if (RESERVED_NAMES.has(name) || /\b(anthropic|claude)\b/i.test(name)) {
-            return textResult(`❌ Name "${name}" uses a reserved word ("anthropic" or "claude"). Pick another.`);
-        }
-        if (!description || !description.trim()) {
-            return textResult('❌ Description is required — Claude uses it to decide when to apply this skill.');
-        }
-        if (description.length > DESCRIPTION_MAX_LEN) {
-            return textResult(`❌ Description is too long (${description.length} chars). Max is ${DESCRIPTION_MAX_LEN}.`);
-        }
-        if (!body || !body.trim()) {
-            return textResult('❌ Procedure body is required — that\'s what Claude actually runs.');
-        }
-        const skillsDir = globalSkillsDir();
-        const folderPath = path.join(skillsDir, name);
-        const entryPath = path.join(folderPath, 'SKILL.md');
-        if (existsSync(entryPath)) {
-            return textResult(`❌ Skill "${name}" already exists at ${entryPath}. Use update_skill instead, or pick a different name.`);
-        }
+        // 1.18.124 — delegate to the shared writeSkill helper. Validation
+        // (name regex, length caps, reserved words, already-exists) is
+        // now centralized; the same checks run for the dashboard endpoint
+        // and the auto-extraction path.
         try {
-            mkdirSync(folderPath, { recursive: true });
-            const now = new Date().toISOString();
-            const fm = { name, description };
-            if (title && title.trim())
-                fm.title = title.trim();
-            const clementineExt = {
+            const { writeSkill } = await import('../agent/skill-store.js');
+            const result = writeSkill({
+                name,
+                title,
+                description,
+                body,
+                tools,
+                triggers,
                 source: 'chat',
-                useCount: 0,
-                createdAt: now,
-                updatedAt: now,
-                version: 1,
-            };
-            if (Array.isArray(tools) && tools.length > 0) {
-                clementineExt.tools = { allow: tools.map(String).map(s => s.trim()).filter(Boolean) };
-            }
-            if (Array.isArray(triggers) && triggers.length > 0) {
-                clementineExt.triggers = triggers.map(String).map(s => s.trim()).filter(Boolean);
-            }
-            fm.clementine = clementineExt;
-            const content = matter.stringify(body.endsWith('\n') ? body : body + '\n', fm);
-            writeFileSync(entryPath, content);
-            logger.info({ name, entryPath, source: 'chat' }, 'Skill created via chat');
+            });
+            logger.info({ name: result.name, entryPath: result.filePath, source: 'chat' }, 'Skill created via chat');
             const toolsLine = (tools && tools.length > 0) ? `\nAllowed tools: ${tools.slice(0, 5).join(', ')}${tools.length > 5 ? `, +${tools.length - 5} more` : ''}` : '';
             const triggersLine = (triggers && triggers.length > 0) ? `\nTriggers: ${triggers.slice(0, 4).join(', ')}${triggers.length > 4 ? `, +${triggers.length - 4} more` : ''}` : '';
-            return textResult(`✅ Created skill "${name}" at ${entryPath}\n` +
+            return textResult(`✅ Created skill "${result.name}" at ${result.filePath}\n` +
                 `Description: ${description.slice(0, 200)}${description.length > 200 ? '…' : ''}` +
                 toolsLine +
                 triggersLine +
-                `\n\nThe skill is ready to pin to any task — open the cron editor, go to Tools & MCP, click "+ Add skill" and select "${name}". Or invoke it directly in chat: "Run the ${title || name} skill."`);
+                `\n\nThe skill is ready to pin to any task — open the cron editor, go to Tools & MCP, click "+ Add skill" and select "${result.name}". Or invoke it directly in chat: "Run the ${title || result.name} skill."`);
         }
         catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('already exists')) {
+                return textResult(`❌ Skill "${name}" already exists. Use update_skill instead, or pick a different name.`);
+            }
             logger.error({ err, name }, 'create_skill failed');
-            return textResult(`❌ Failed to write the skill: ${err instanceof Error ? err.message : String(err)}`);
+            return textResult(`❌ ${msg}`);
         }
     });
     // ── update_skill ────────────────────────────────────────────────────

package/package.json

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