clementine-agent 1.18.111 → 1.18.112

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

@@ -279,6 +279,13 @@ export async function buildSkillContext(jobName, jobPrompt, agentSlug, pinnedSki
         }
         if (prepared.length === 0)
             return { text: '', applied, missing };
+        // 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
+        // huge templates/ tree doesn't blow the context window — anything over
+        // the cap is left on disk and the LLM can Read it via the cron's cwd.
+        const BUNDLE_FILE_CAP = 5;
+        const BUNDLE_BYTES_CAP = 12000;
         const skillLines = prepared.map(s => {
             recordSkillUse(s.name);
             memoryStore?.logSkillUse?.({
@@ -292,7 +299,62 @@ export async function buildSkillContext(jobName, jobPrompt, agentSlug, pinnedSki
             let block = `### ${s.title}${s.source === 'pinned' ? ' _(pinned)_' : ''}\n${s.content}`;
             if (s.toolsUsed.length > 0)
                 block += `\n**Tools:** ${s.toolsUsed.join(', ')}`;
-            if (s.attachments.length > 0) {
+            // Folder-form skills (post-migration default): inline sibling .md
+            // files (templates/intro.md, reference.md, etc.) so the cron prompt
+            // actually sees them. SKILL.md itself is the body above. scripts/
+            // and other non-.md assets stay on disk — the cron's cwd has Bash
+            // access to them via the runtime working directory.
+            const folderPath = path.join(s.skillDir, s.name);
+            const skillEntry = path.join(folderPath, 'SKILL.md');
+            if (fs.existsSync(skillEntry)) {
+                let bytesUsed = 0;
+                let filesUsed = 0;
+                const collectMd = (subDir, label) => {
+                    if (filesUsed >= BUNDLE_FILE_CAP || bytesUsed >= BUNDLE_BYTES_CAP)
+                        return;
+                    let entries;
+                    try {
+                        entries = fs.readdirSync(subDir).sort();
+                    }
+                    catch {
+                        return;
+                    }
+                    for (const entry of entries) {
+                        if (filesUsed >= BUNDLE_FILE_CAP || bytesUsed >= BUNDLE_BYTES_CAP)
+                            break;
+                        if (entry === 'SKILL.md')
+                            continue;
+                        if (!entry.endsWith('.md'))
+                            continue;
+                        const full = path.join(subDir, entry);
+                        try {
+                            const content = fs.readFileSync(full, 'utf-8');
+                            const remaining = BUNDLE_BYTES_CAP - bytesUsed;
+                            const slice = content.slice(0, remaining);
+                            const labeled = label ? `${label}/${entry}` : entry;
+                            block += `\n\n#### ${labeled}\n${slice}`;
+                            bytesUsed += slice.length;
+                            filesUsed++;
+                        }
+                        catch { /* skip unreadable */ }
+                    }
+                };
+                // Top-level bundled .md files (reference.md, etc.)
+                collectMd(folderPath, '');
+                // Common sub-dirs: templates/, references/. One level deep only —
+                // we don't recurse to keep the budget predictable.
+                for (const sub of ['templates', 'references']) {
+                    if (filesUsed >= BUNDLE_FILE_CAP || bytesUsed >= BUNDLE_BYTES_CAP)
+                        break;
+                    const subPath = path.join(folderPath, sub);
+                    if (fs.existsSync(subPath) && fs.statSync(subPath).isDirectory()) {
+                        collectMd(subPath, sub);
+                    }
+                }
+            }
+            else if (s.attachments.length > 0) {
+                // Legacy flat form: attachments live under <skill>.files/ alongside
+                // the skill .md. Kept for backward compat with un-migrated skills.
                 const attDir = path.join(s.skillDir, s.name + '.files');
                 for (const attName of s.attachments.slice(0, 3)) {
                     const attPath = path.join(attDir, attName);

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

@@ -74,7 +74,10 @@ export declare function searchSkills(query: string, limit?: number, agentSlug?:
 export declare function loadSkillByName(name: string, agentSlug?: string, opts?: {
     suppressedNames?: Set<string>;
 }): SkillMatch | null;
-/** Record that a skill was used (bump use count). */
+/** Record that a skill was used (bump use count). Handles both flat and
+ *  folder-form skills. For folder form the counter lives under
+ *  `clementine.useCount` (Anthropic-canonical frontmatter keeps top-level
+ *  reserved for `name`/`description`). */
 export declare function recordSkillUse(skillName: string, agentSlug?: string): void;
 /** List all active skills (global + all agent-scoped). */
 export declare function listSkills(agentSlug?: string): Array<{

package/dist/agent/skill-extractor.js

@@ -325,11 +325,39 @@ async function mergeSkill(assistant, existing, incoming) {
  */
 const skillEmbeddingCache = new Map();
 /**
- * Recursively list every .md skill file under `dir`. Returns absolute
+ * Compute the canonical skill slug from a relative path.
+ *
+ * Two layouts are supported:
+ *   - Folder form (Anthropic spec): `<name>/SKILL.md` → `<name>`
+ *     (sibling .md files in that folder are bundled docs, not standalone skills)
+ *   - Flat form (legacy): `<name>.md` → `<name>`
+ *     (auto-generated MCP skills like `auto/discord/send.md` → `auto-discord-send`)
+ *
+ * NOTE: this is the single source of truth for "what slug should this file be
+ * loaded under." Both walkSkillFiles and loadSkillByName route through it so
+ * the dedupe/naming stays consistent.
+ */
+function slugFromRel(relPath) {
+    // Folder form: <a>/<b>/SKILL.md → <a>-<b>
+    if (/(?:^|[\\/])SKILL\.md$/.test(relPath)) {
+        const parts = relPath.replace(/[\\/]SKILL\.md$/, '').split(/[\\/]/);
+        return parts.join('-');
+    }
+    // Flat form: any other .md file
+    return relPath.replace(/\.md$/, '').replace(/[\\/]/g, '-');
+}
+/**
+ * Recursively list every skill file under `dir`. Returns absolute
  * paths, relative paths (for dedupe/naming), and an `isAuto` flag set
- * when the file lives under an `auto/` subtree. Used so auto-generated
- * MCP skills under `skills/auto/<server>/<tool>.md` surface in search
- * while user-authored top-level skills win on score tiebreak.
+ * when the file lives under an `auto/` subtree.
+ *
+ * Folder-form skills (`<name>/SKILL.md`) emit ONLY the SKILL.md and do
+ * not recurse — sibling .md files (templates/, reference docs) and
+ * subdirectories (scripts/) are bundled assets, not standalone skills.
+ *
+ * Flat-form skills (`<name>.md`, including auto-generated MCP skills
+ * under `auto/<server>/<tool>.md`) keep the legacy behavior so existing
+ * unmigrated installs don't regress.
  */
 function walkSkillFiles(root) {
     const out = [];
@@ -341,6 +369,20 @@ function walkSkillFiles(root) {
         catch {
             return;
         }
+        // Folder-form short-circuit: a sub-directory with a SKILL.md is a bundled
+        // skill folder. Emit just the SKILL.md and skip everything else inside —
+        // bundled docs/scripts are not separate skills.
+        if (rel) {
+            const skillEntry = entries.find(e => e.isFile() && e.name === 'SKILL.md');
+            if (skillEntry) {
+                out.push({
+                    filePath: path.join(dir, skillEntry.name),
+                    relPath: path.join(rel, skillEntry.name),
+                    isAuto: rel.split(path.sep)[0] === 'auto',
+                });
+                return;
+            }
+        }
         for (const ent of entries) {
             const name = ent.name;
             // Skip backup files and hidden files
@@ -401,9 +443,10 @@ export function searchSkills(query, limit = 3, agentSlug, opts) {
         // tiebreak even when both match the query.
         const files = walkSkillFiles(dir);
         for (const { filePath, relPath, isAuto } of files) {
-            // Use relPath (no .md, slashes → dashes) so same-name skills in
-            // different subdirs don't collide in the dedupe set.
-            const name = relPath.replace(/\.md$/, '').replace(/[\\/]/g, '-');
+            // Use slugFromRel so folder-form skills (`<name>/SKILL.md`) get
+            // their canonical name `<name>` and not `<name>-SKILL`. Same dedupe
+            // contract: distinct files cannot share a name.
+            const name = slugFromRel(relPath);
             if (seen.has(name))
                 continue;
             seen.add(name);
@@ -521,18 +564,61 @@ export function loadSkillByName(name, agentSlug, opts) {
     if (opts?.suppressedNames?.has(name))
         return null;
     for (const dir of dirs) {
+        // Fast path: folder form. `<dir>/<name>/SKILL.md` is the canonical
+        // Anthropic layout post-migration. Try it first so a slug like
+        // `morning-briefing` resolves to `morning-briefing/SKILL.md`.
+        const folderEntry = path.join(dir, name, 'SKILL.md');
+        if (existsSync(folderEntry)) {
+            try {
+                const raw = readFileSync(folderEntry, 'utf-8');
+                const parsed = matter(raw);
+                const fmTools = parsed.data?.clementine?.tools?.allow ?? parsed.data?.toolsUsed ?? [];
+                return {
+                    name,
+                    title: parsed.data.title ?? parsed.data.name ?? name,
+                    content: parsed.content, // full body — the runtime cap is gone
+                    score: 0,
+                    toolsUsed: Array.isArray(fmTools) ? fmTools : [],
+                    attachments: parsed.data.attachments ?? [],
+                    skillDir: dir,
+                };
+            }
+            catch {
+                return null;
+            }
+        }
+        // Fast path: flat form. `<dir>/<name>.md` (legacy + auto-discovery).
+        const flatEntry = path.join(dir, `${name}.md`);
+        if (existsSync(flatEntry)) {
+            try {
+                const raw = readFileSync(flatEntry, 'utf-8');
+                const parsed = matter(raw);
+                return {
+                    name,
+                    title: parsed.data.title ?? name,
+                    content: parsed.content, // full body — the runtime cap is gone
+                    score: 0,
+                    toolsUsed: parsed.data.toolsUsed ?? [],
+                    attachments: parsed.data.attachments ?? [],
+                    skillDir: dir,
+                };
+            }
+            catch {
+                return null;
+            }
+        }
+        // Fallback: walk for nested forms (e.g. `auto/discord/send` slug).
         const files = walkSkillFiles(dir);
         for (const { filePath, relPath } of files) {
-            const slug = relPath.replace(/\.md$/, '').replace(/[\\/]/g, '-');
-            if (slug !== name)
+            if (slugFromRel(relPath) !== name)
                 continue;
             try {
                 const raw = readFileSync(filePath, 'utf-8');
                 const parsed = matter(raw);
                 return {
-                    name: slug,
-                    title: parsed.data.title ?? slug,
-                    content: parsed.content.slice(0, 1500),
+                    name,
+                    title: parsed.data.title ?? name,
+                    content: parsed.content, // full body — the runtime cap is gone
                     score: 0,
                     toolsUsed: parsed.data.toolsUsed ?? [],
                     attachments: parsed.data.attachments ?? [],
@@ -546,21 +632,37 @@ export function loadSkillByName(name, agentSlug, opts) {
     }
     return null;
 }
-/** Record that a skill was used (bump use count). */
+/** Record that a skill was used (bump use count). Handles both flat and
+ *  folder-form skills. For folder form the counter lives under
+ *  `clementine.useCount` (Anthropic-canonical frontmatter keeps top-level
+ *  reserved for `name`/`description`). */
 export function recordSkillUse(skillName, agentSlug) {
     try {
-        // Check agent dir first, then global
         const dirs = agentSlug ? [agentSkillsDir(agentSlug), GLOBAL_SKILLS_DIR] : [GLOBAL_SKILLS_DIR];
         for (const dir of dirs) {
-            const filePath = path.join(dir, `${skillName}.md`);
-            if (!existsSync(filePath))
-                continue;
-            const raw = readFileSync(filePath, 'utf-8');
-            const parsed = matter(raw);
-            parsed.data.useCount = (parsed.data.useCount ?? 0) + 1;
-            parsed.data.lastUsed = new Date().toISOString();
-            writeFileSync(filePath, matter.stringify(parsed.content, parsed.data));
-            return;
+            // Folder form: <dir>/<skillName>/SKILL.md
+            const folderEntry = path.join(dir, skillName, 'SKILL.md');
+            if (existsSync(folderEntry)) {
+                const raw = readFileSync(folderEntry, 'utf-8');
+                const parsed = matter(raw);
+                parsed.data.clementine = (parsed.data.clementine && typeof parsed.data.clementine === 'object')
+                    ? parsed.data.clementine
+                    : {};
+                parsed.data.clementine.useCount = (parsed.data.clementine.useCount ?? 0) + 1;
+                parsed.data.clementine.lastUsed = new Date().toISOString();
+                writeFileSync(folderEntry, matter.stringify(parsed.content, parsed.data));
+                return;
+            }
+            // Flat form: <dir>/<skillName>.md
+            const flatEntry = path.join(dir, `${skillName}.md`);
+            if (existsSync(flatEntry)) {
+                const raw = readFileSync(flatEntry, 'utf-8');
+                const parsed = matter(raw);
+                parsed.data.useCount = (parsed.data.useCount ?? 0) + 1;
+                parsed.data.lastUsed = new Date().toISOString();
+                writeFileSync(flatEntry, matter.stringify(parsed.content, parsed.data));
+                return;
+            }
         }
     }
     catch { /* non-fatal */ }

package/package.json

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