clementine-agent 1.18.123 → 1.18.124

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,38 @@ 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 {};
 //# sourceMappingURL=skill-store.d.ts.map

package/dist/agent/skill-store.js

@@ -647,4 +647,70 @@ 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 };
+}
 //# 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/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.124",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",