clementine-agent 1.18.107 → 1.18.108

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

@@ -1,57 +1,63 @@
 /**
- * Skill store — Phase A (read-only) of the Skills-First redesign.
+ * Skill store — Phase A / A.5 of the Skills-First redesign.
  *
- * Discovers skill .md files from two locations and parses their
- * frontmatter into the Skill type. Phase A surfaces what's already on
- * disk; Phase B adds editing + testing; Phase C wires runtime invocation.
+ * Anthropic-compatible skill loader. Walks two skill directories and
+ * accepts both layouts:
  *
- * Discovery order:
- *   1. ~/.clementine/vault/00-System/skills/<name>.md  (global)
- *   2. <work_dir>/.clementine/skills/<name>.md         (per-project)
+ *   1. **Folder form** (Anthropic spec): <dir>/<skill-name>/SKILL.md
+ *      A capital-S SKILL.md is the entry point. Sibling .md files and
+ *      a scripts/ subdirectory are surfaced as bundled files.
  *
- * Per-project files win on name collision — they override global skills
- * for that project. The dashboard surfaces both pools and tags each
- * skill with its scope so the user can see which one will resolve.
+ *   2. **Flat form** (Clementine legacy): <dir>/<skill-name>.md
+ *      A single .md file with frontmatter + body. Bundled files
+ *      unsupported. Used by the 12 pre-redesign skill files we already
+ *      have on disk.
  *
- * Schema detection: a file is `v1` when its frontmatter declares any of
- * inputs / tools.allow / tools.deny / dataSources / stateKeys / success.
- * Otherwise (only legacy fields like title / triggers / toolsUsed) it's
- * `legacy` and the dashboard shows a migration badge.
+ * Discovery directories (per-project wins on name collision):
+ *   - global:      $CLEMENTINE_HOME/vault/00-System/skills/
+ *   - per-project: <work_dir>/.clementine/skills/
  *
- * Used-by join: Phase A reads the `skills:` array on CronJobDefinition
- * (the existing field) to populate Skill.usedByTriggers. Phase C will
- * extend this to read the new top-level `skill:` field on the trigger.
+ * Phase A is read-only. Phase B adds editing + a "Test this skill"
+ * runner. Phase C wires runtime invocation. Phase E migrates legacy
+ * crons → folder-form skills.
  */
-import type { Skill, SkillScope, CronJobDefinition } from '../types.js';
+import type { Skill, SkillScope, SkillValidationWarning, CronJobDefinition } from '../types.js';
+/** Run Anthropic-spec validations on a parsed skill. Errors are spec
+ *  violations (skill would be rejected by the Anthropic API); warnings
+ *  are best-practice hints (still loadable). Findings render in the
+ *  dashboard's detail pane. */
+export declare function validateSkill(skill: Skill): SkillValidationWarning[];
 interface ParseResult {
     skill: Skill;
     /** Set when the file existed but couldn't be parsed (bad YAML, etc.).
-     *  We still surface the file with a fallback frontmatter so the user
-     *  can see which one needs fixing. */
+     *  We still surface the skill with synthesized frontmatter so the
+     *  dashboard can render the offending file with an error banner. */
     parseError?: string;
 }
-/** Parse a single skill file. Returns a Skill record even when the
- *  frontmatter is malformed — the dashboard renders the parse error
- *  in-pane so the user can fix it without leaving the UI. */
+/** Parse a flat-form skill file (single .md). */
 export declare function parseSkillFile(filePath: string, scope: SkillScope): ParseResult;
+/** Parse a folder-form skill (Anthropic spec: <name>/SKILL.md plus optional
+ *  bundled files). The folder name is the canonical skill identifier. */
+export declare function parseSkillFolder(folderPath: string, scope: SkillScope): ParseResult;
 export interface ListSkillsOptions {
-    /** Optional per-project work_dir to also scan. Per-project skills
-     *  override global skills with the same filename. */
+    /** Optional per-project work_dir to scan. Per-project skills shadow
+     *  global ones with the same identifier. */
     projectWorkDir?: string;
-    /** Optional cron jobs list — when provided, the loader populates the
-     *  usedByTriggers field on each skill via the existing skills[] array
-     *  on CronJobDefinition (Phase A's join). */
+    /** Optional cron jobs for the usedByTriggers join (via skills[]). */
     jobs?: CronJobDefinition[];
 }
-/** Top-level discovery API. Returns the merged list of skills across
- *  global + per-project pools, with per-project taking precedence on
- *  name collision. usedByTriggers is populated when jobs are passed in. */
+/** Top-level discovery API. Merges global + per-project pools, with
+ *  per-project taking precedence. Populates usedByTriggers when jobs
+ *  are passed. Returned list is sorted alphabetically by name. */
 export declare function listSkills(opts?: ListSkillsOptions): Skill[];
-/** Get a single skill by name, with the same global/project precedence
- *  as listSkills. Returns null if neither pool has the skill. */
+/** Get one skill by name, applying per-project precedence. Returns
+ *  null when neither pool has the skill. */
 export declare function getSkill(name: string, opts?: ListSkillsOptions): Skill | null;
-/** Test-only: where the loader looked. Useful in unit tests + the
- *  dashboard's diagnostics surface. */
+/** Read one bundled file's contents — used by Phase B's preview pane.
+ *  Defends against directory traversal: rejects paths that escape the
+ *  skill folder. */
+export declare function readBundledFile(skill: Skill, relPath: string): string | null;
+/** Diagnostics for the dashboard — expose where the loader looked. */
 export declare function _skillDirsForDiagnostics(workDir?: string): {
     global: string;
     project: string | null;

package/dist/agent/skill-store.js

@@ -1,125 +1,146 @@
 /**
- * Skill store — Phase A (read-only) of the Skills-First redesign.
+ * Skill store — Phase A / A.5 of the Skills-First redesign.
  *
- * Discovers skill .md files from two locations and parses their
- * frontmatter into the Skill type. Phase A surfaces what's already on
- * disk; Phase B adds editing + testing; Phase C wires runtime invocation.
+ * Anthropic-compatible skill loader. Walks two skill directories and
+ * accepts both layouts:
  *
- * Discovery order:
- *   1. ~/.clementine/vault/00-System/skills/<name>.md  (global)
- *   2. <work_dir>/.clementine/skills/<name>.md         (per-project)
+ *   1. **Folder form** (Anthropic spec): <dir>/<skill-name>/SKILL.md
+ *      A capital-S SKILL.md is the entry point. Sibling .md files and
+ *      a scripts/ subdirectory are surfaced as bundled files.
  *
- * Per-project files win on name collision — they override global skills
- * for that project. The dashboard surfaces both pools and tags each
- * skill with its scope so the user can see which one will resolve.
+ *   2. **Flat form** (Clementine legacy): <dir>/<skill-name>.md
+ *      A single .md file with frontmatter + body. Bundled files
+ *      unsupported. Used by the 12 pre-redesign skill files we already
+ *      have on disk.
  *
- * Schema detection: a file is `v1` when its frontmatter declares any of
- * inputs / tools.allow / tools.deny / dataSources / stateKeys / success.
- * Otherwise (only legacy fields like title / triggers / toolsUsed) it's
- * `legacy` and the dashboard shows a migration badge.
+ * Discovery directories (per-project wins on name collision):
+ *   - global:      $CLEMENTINE_HOME/vault/00-System/skills/
+ *   - per-project: <work_dir>/.clementine/skills/
  *
- * Used-by join: Phase A reads the `skills:` array on CronJobDefinition
- * (the existing field) to populate Skill.usedByTriggers. Phase C will
- * extend this to read the new top-level `skill:` field on the trigger.
+ * Phase A is read-only. Phase B adds editing + a "Test this skill"
+ * runner. Phase C wires runtime invocation. Phase E migrates legacy
+ * crons → folder-form skills.
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import matter from 'gray-matter';
-/** Resolve the global skills directory from CLEMENTINE_HOME (or default). */
+// ── Path resolution (lazy — reads CLEMENTINE_HOME on each call) ──────
 function globalSkillsDir() {
     const base = process.env.CLEMENTINE_HOME || path.join(os.homedir(), '.clementine');
     return path.join(base, 'vault', '00-System', 'skills');
 }
-/** Resolve a per-project skills directory. Returns null if work_dir is
- *  empty or doesn't have a .clementine/skills/ child. */
 function projectSkillsDir(workDir) {
     if (!workDir)
         return null;
     const dir = path.join(workDir, '.clementine', 'skills');
     return existsSync(dir) ? dir : null;
 }
-/** Strip backup files (.bak), hidden files, and directories. */
-function isSkillFile(name) {
-    if (name.startsWith('.'))
-        return false;
-    if (!name.endsWith('.md'))
-        return false;
-    if (name.endsWith('.bak'))
-        return false;
-    if (name.endsWith('.bak.md'))
-        return false;
-    return true;
-}
-/** Skill name is the filename without extension. We don't trust the
- *  frontmatter's `name:` field as the canonical identifier because
- *  different files could collide on it; the filename is what the loader
- *  joins on. The frontmatter `name:` is preserved as a display alias. */
-function nameFromFile(file) {
-    return path.basename(file, '.md');
+// ── Anthropic spec validations ────────────────────────────────────────
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const RESERVED_NAMES = new Set(['anthropic', 'claude']);
+const NAME_MAX_LEN = 64;
+const DESCRIPTION_MAX_LEN = 1024;
+const BODY_LINE_LIMIT_WARN = 500;
+/** Run Anthropic-spec validations on a parsed skill. Errors are spec
+ *  violations (skill would be rejected by the Anthropic API); warnings
+ *  are best-practice hints (still loadable). Findings render in the
+ *  dashboard's detail pane. */
+export function validateSkill(skill) {
+    const out = [];
+    const fm = skill.frontmatter;
+    // Name validation (Anthropic spec).
+    if (!fm.name) {
+        out.push({ severity: 'error', field: 'name', message: 'name is required' });
+    }
+    else {
+        if (fm.name.length > NAME_MAX_LEN) {
+            out.push({ severity: 'error', field: 'name', message: `name exceeds ${NAME_MAX_LEN} chars (got ${fm.name.length})` });
+        }
+        if (!NAME_PATTERN.test(fm.name)) {
+            out.push({ severity: 'error', field: 'name', message: 'name must be lowercase letters, numbers, and hyphens only' });
+        }
+        const lower = fm.name.toLowerCase();
+        if (RESERVED_NAMES.has(lower) || lower.includes('anthropic') || lower.includes('claude')) {
+            // Anthropic forbids these words anywhere in the name.
+            out.push({ severity: 'error', field: 'name', message: 'name cannot contain reserved words "anthropic" or "claude"' });
+        }
+    }
+    // Description validation (Anthropic spec).
+    if (!fm.description || !fm.description.trim()) {
+        out.push({ severity: 'warning', field: 'description', message: 'description is required by Anthropic spec — add one so the skill can be discovered' });
+    }
+    else if (fm.description.length > DESCRIPTION_MAX_LEN) {
+        out.push({ severity: 'error', field: 'description', message: `description exceeds ${DESCRIPTION_MAX_LEN} chars (got ${fm.description.length})` });
+    }
+    else if (/<\w+/i.test(fm.description)) {
+        out.push({ severity: 'error', field: 'description', message: 'description cannot contain XML tags' });
+    }
+    // Body length (best-practice hint).
+    const bodyLines = (skill.body.match(/\n/g)?.length ?? 0) + 1;
+    if (bodyLines > BODY_LINE_LIMIT_WARN) {
+        out.push({ severity: 'warning', field: 'body', message: `body is ${bodyLines} lines — Anthropic recommends under ${BODY_LINE_LIMIT_WARN}; split into bundled files (FORMS.md, reference.md, etc.)` });
+    }
+    // Layout hint: flat skills can't bundle scripts or sibling references.
+    if (skill.layout === 'flat' && skill.schemaVersion !== 'legacy') {
+        out.push({ severity: 'warning', field: 'layout', message: 'consider folder form (<skill-name>/SKILL.md) so you can bundle scripts and reference files later' });
+    }
+    return out;
 }
-/** Detect whether a frontmatter object uses the v1 schema or the
- *  pre-redesign legacy shape. Phase A renders this as a badge so users
- *  can see which skills need migration in Phase B. */
-function detectSchemaVersion(fm) {
-    const v1Markers = ['inputs', 'dataSources', 'stateKeys', 'success', 'limits'];
-    if (v1Markers.some((k) => k in fm))
-        return 'v1';
-    const tools = fm.tools;
-    if (tools && (Array.isArray(tools.allow) || Array.isArray(tools.deny)))
-        return 'v1';
-    return 'legacy';
+// ── Frontmatter parsing ───────────────────────────────────────────────
+/** Detect which of the three schema variants this frontmatter is.
+ *
+ * - 'clementine'  if the `clementine:` namespace is present
+ * - 'legacy'      if any of the pre-redesign top-level fields are present
+ *                 (title / triggers / toolsUsed / useCount) AND no clementine
+ * - 'anthropic'   otherwise (just name + description, the canonical case)
+ */
+function detectSchemaVersion(raw) {
+    if (raw.clementine && typeof raw.clementine === 'object' && !Array.isArray(raw.clementine)) {
+        return 'clementine';
+    }
+    const legacyMarkers = ['title', 'triggers', 'toolsUsed', 'useCount', 'source'];
+    if (legacyMarkers.some((k) => k in raw))
+        return 'legacy';
+    return 'anthropic';
 }
-/** Coerce a parsed YAML object into the SkillFrontmatter shape. We
- *  accept both the v1 fields and the legacy fields side-by-side; the
- *  caller's schemaVersion check tells the dashboard which is which. */
-function coerceFrontmatter(raw, fileBasename) {
-    const fm = {
-        // Identifier — ALWAYS the filename (without .md). The frontmatter's
-        // `name:` field is intentionally ignored to avoid two skills colliding
-        // on it. Users wanting a friendly display string can set `title:`
-        // instead, which Phase B's editor surfaces as the heading.
-        name: fileBasename,
-    };
-    if (typeof raw.description === 'string')
-        fm.description = raw.description;
-    // v1 inputs — JSON Schema map keyed by field name.
-    if (raw.inputs && typeof raw.inputs === 'object' && !Array.isArray(raw.inputs)) {
-        fm.inputs = raw.inputs;
+function coerceClementineExtensions(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const r = raw;
+    const out = {};
+    if (r.inputs && typeof r.inputs === 'object' && !Array.isArray(r.inputs)) {
+        out.inputs = r.inputs;
     }
-    // tools.allow / tools.deny
-    if (raw.tools && typeof raw.tools === 'object' && !Array.isArray(raw.tools)) {
-        const t = raw.tools;
+    if (r.tools && typeof r.tools === 'object' && !Array.isArray(r.tools)) {
+        const t = r.tools;
         const policy = {};
         if (Array.isArray(t.allow))
             policy.allow = t.allow.map(String);
         if (Array.isArray(t.deny))
             policy.deny = t.deny.map(String);
         if (policy.allow || policy.deny)
-            fm.tools = policy;
+            out.tools = policy;
     }
-    if (Array.isArray(raw.dataSources)) {
-        fm.dataSources = raw.dataSources
-            .filter((d) => !!d && typeof d === 'object')
-            .map((d) => ({
-            kind: String(d.kind || 'unknown'),
-            purpose: String(d.purpose || ''),
-        }));
+    if (Array.isArray(r.dataSources)) {
+        out.dataSources = r.dataSources
+            .filter((d) => !!d && typeof d === 'object' && !Array.isArray(d))
+            .map((d) => ({ kind: String(d.kind || 'unknown'), purpose: String(d.purpose || '') }));
     }
-    if (Array.isArray(raw.stateKeys))
-        fm.stateKeys = raw.stateKeys.map(String);
-    if (raw.success && typeof raw.success === 'object' && !Array.isArray(raw.success)) {
-        const s = raw.success;
+    if (Array.isArray(r.stateKeys))
+        out.stateKeys = r.stateKeys.map(String);
+    if (r.success && typeof r.success === 'object' && !Array.isArray(r.success)) {
+        const s = r.success;
         const success = {};
         if (s.schema && typeof s.schema === 'object')
             success.schema = s.schema;
         if (typeof s.criterion === 'string')
             success.criterion = s.criterion;
         if (success.schema || success.criterion)
-            fm.success = success;
+            out.success = success;
     }
-    if (raw.limits && typeof raw.limits === 'object' && !Array.isArray(raw.limits)) {
-        const l = raw.limits;
+    if (r.limits && typeof r.limits === 'object' && !Array.isArray(r.limits)) {
+        const l = r.limits;
         const limits = {};
         if (typeof l.maxTurns === 'number')
             limits.maxTurns = l.maxTurns;
@@ -128,19 +149,31 @@ function coerceFrontmatter(raw, fileBasename) {
         if (typeof l.timeoutSeconds === 'number')
             limits.timeoutSeconds = l.timeoutSeconds;
         if (Object.keys(limits).length > 0)
-            fm.limits = limits;
+            out.limits = limits;
     }
-    if (typeof raw.version === 'number')
-        fm.version = raw.version;
-    if (typeof raw.createdAt === 'string')
-        fm.createdAt = raw.createdAt;
-    if (typeof raw.updatedAt === 'string')
-        fm.updatedAt = raw.updatedAt;
-    if (typeof raw.lastUsed === 'string')
-        fm.lastUsed = raw.lastUsed;
-    if (typeof raw.lastTestPass === 'string')
-        fm.lastTestPass = raw.lastTestPass;
-    // Legacy fields (preserved as-is for the migration UI).
+    if (typeof r.version === 'number')
+        out.version = r.version;
+    if (typeof r.createdAt === 'string')
+        out.createdAt = r.createdAt;
+    if (typeof r.updatedAt === 'string')
+        out.updatedAt = r.updatedAt;
+    if (typeof r.lastUsed === 'string')
+        out.lastUsed = r.lastUsed;
+    if (typeof r.lastTestPass === 'string')
+        out.lastTestPass = r.lastTestPass;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Coerce raw YAML object → SkillFrontmatter. Filename always wins for
+ *  identity (frontmatter `name:` is ignored to prevent two skills from
+ *  colliding); we treat the YAML name as a display alias only. */
+function coerceFrontmatter(raw, fileBasename) {
+    const fm = { name: fileBasename };
+    if (typeof raw.description === 'string')
+        fm.description = raw.description;
+    const ext = coerceClementineExtensions(raw.clementine);
+    if (ext)
+        fm.clementine = ext;
+    // Legacy top-level fields preserved for the migration UI.
     if (typeof raw.title === 'string')
         fm.title = raw.title;
     if (Array.isArray(raw.triggers))
@@ -153,58 +186,175 @@ function coerceFrontmatter(raw, fileBasename) {
         fm.useCount = raw.useCount;
     return fm;
 }
-/** Parse a single skill file. Returns a Skill record even when the
- *  frontmatter is malformed — the dashboard renders the parse error
- *  in-pane so the user can fix it without leaving the UI. */
+// ── File / folder helpers ─────────────────────────────────────────────
+function isLoadableSkillFile(name) {
+    if (name.startsWith('.'))
+        return false;
+    if (!name.endsWith('.md'))
+        return false;
+    if (name.endsWith('.bak'))
+        return false;
+    if (name.endsWith('.bak.md'))
+        return false;
+    return true;
+}
+function classifyBundledFile(relPath) {
+    if (relPath.endsWith('.md'))
+        return 'markdown';
+    if (relPath.startsWith('scripts/'))
+        return 'script';
+    if (/\.(py|js|ts|sh|rb)$/.test(relPath))
+        return 'script';
+    return 'other';
+}
+/** Walk a skill folder (recursively shallow — one level into scripts/)
+ *  and return non-SKILL.md files as bundled artifacts. Skips hidden
+ *  files, .bak duplicates, and the SKILL.md itself. */
+function discoverBundledFiles(skillFolder) {
+    const out = [];
+    const walk = (dir, relPrefix) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith('.'))
+                continue;
+            const abs = path.join(dir, entry);
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            const rel = relPrefix ? `${relPrefix}/${entry}` : entry;
+            if (st.isDirectory()) {
+                // Only descend one level — avoids surprise when a skill bundles
+                // node_modules or similar. Convention: scripts/, reference/.
+                if (relPrefix)
+                    continue;
+                walk(abs, rel);
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            // Skip the entry-point file itself + .bak duplicates.
+            if (rel === 'SKILL.md')
+                continue;
+            if (entry.endsWith('.bak') || entry.endsWith('.bak.md'))
+                continue;
+            out.push({
+                relPath: rel,
+                absPath: abs,
+                kind: classifyBundledFile(rel),
+                sizeBytes: st.size,
+            });
+        }
+    };
+    walk(skillFolder, '');
+    // Sort deterministically: top-level files first, then scripts/, then
+    // alphabetical within each group.
+    out.sort((a, b) => {
+        const aTop = !a.relPath.includes('/');
+        const bTop = !b.relPath.includes('/');
+        if (aTop !== bTop)
+            return aTop ? -1 : 1;
+        return a.relPath.localeCompare(b.relPath);
+    });
+    return out;
+}
+function emptySkill(filePath, basename, scope, layout) {
+    return {
+        frontmatter: { name: basename },
+        body: '',
+        filePath,
+        scope,
+        layout,
+        schemaVersion: 'legacy',
+        bundledFiles: [],
+        usedByTriggers: [],
+        validation: [],
+    };
+}
+/** Parse a flat-form skill file (single .md). */
 export function parseSkillFile(filePath, scope) {
-    const basename = nameFromFile(filePath);
+    const basename = path.basename(filePath, '.md');
     let raw;
     try {
         raw = readFileSync(filePath, 'utf-8');
     }
     catch (err) {
-        return {
-            skill: emptySkill(filePath, basename, scope),
-            parseError: 'failed to read: ' + String(err),
-        };
+        return { skill: emptySkill(filePath, basename, scope, 'flat'), parseError: 'failed to read: ' + String(err) };
     }
     let parsed;
     try {
         parsed = matter(raw);
     }
     catch (err) {
-        return {
-            skill: { ...emptySkill(filePath, basename, scope), body: raw },
-            parseError: 'YAML parse error: ' + String(err),
-        };
+        const skill = { ...emptySkill(filePath, basename, scope, 'flat'), body: raw };
+        return { skill, parseError: 'YAML parse error: ' + String(err) };
     }
     const data = parsed.data;
-    const fm = coerceFrontmatter(data, basename);
-    const schemaVersion = detectSchemaVersion(data);
-    return {
-        skill: {
-            frontmatter: fm,
-            body: parsed.content || '',
-            filePath,
-            scope,
-            schemaVersion,
-            usedByTriggers: [],
-        },
+    const skill = {
+        frontmatter: coerceFrontmatter(data, basename),
+        body: parsed.content || '',
+        filePath,
+        scope,
+        layout: 'flat',
+        schemaVersion: detectSchemaVersion(data),
+        bundledFiles: [],
+        usedByTriggers: [],
+        validation: [],
     };
+    skill.validation = validateSkill(skill);
+    return { skill };
 }
-function emptySkill(filePath, basename, scope) {
-    return {
-        frontmatter: { name: basename },
-        body: '',
-        filePath,
+/** Parse a folder-form skill (Anthropic spec: <name>/SKILL.md plus optional
+ *  bundled files). The folder name is the canonical skill identifier. */
+export function parseSkillFolder(folderPath, scope) {
+    const basename = path.basename(folderPath);
+    const entryPoint = path.join(folderPath, 'SKILL.md');
+    if (!existsSync(entryPoint)) {
+        return {
+            skill: emptySkill(entryPoint, basename, scope, 'folder'),
+            parseError: 'no SKILL.md in folder',
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(entryPoint, 'utf-8');
+    }
+    catch (err) {
+        return { skill: emptySkill(entryPoint, basename, scope, 'folder'), parseError: 'failed to read SKILL.md: ' + String(err) };
+    }
+    let parsed;
+    try {
+        parsed = matter(raw);
+    }
+    catch (err) {
+        const skill = { ...emptySkill(entryPoint, basename, scope, 'folder'), body: raw };
+        return { skill, parseError: 'YAML parse error in SKILL.md: ' + String(err) };
+    }
+    const data = parsed.data;
+    const skill = {
+        frontmatter: coerceFrontmatter(data, basename),
+        body: parsed.content || '',
+        filePath: entryPoint,
         scope,
-        schemaVersion: 'legacy',
+        layout: 'folder',
+        schemaVersion: detectSchemaVersion(data),
+        bundledFiles: discoverBundledFiles(folderPath),
         usedByTriggers: [],
+        validation: [],
     };
+    skill.validation = validateSkill(skill);
+    return { skill };
 }
-/** List skills in a directory, returning Skill records (not just paths)
- *  so callers can immediately render them. Tolerates missing dirs and
- *  unreadable files — best-effort. */
+// ── Discovery (top-level API) ────────────────────────────────────────
 function listSkillsInDir(dir, scope) {
     if (!existsSync(dir))
         return [];
@@ -217,24 +367,34 @@ function listSkillsInDir(dir, scope) {
     }
     const out = [];
     for (const entry of entries) {
-        if (!isSkillFile(entry))
+        if (entry.startsWith('.'))
             continue;
         const fullPath = path.join(dir, entry);
+        let st;
         try {
-            const stat = statSync(fullPath);
-            if (!stat.isFile())
-                continue;
+            st = statSync(fullPath);
         }
         catch {
             continue;
         }
-        out.push(parseSkillFile(fullPath, scope).skill);
+        if (st.isDirectory()) {
+            // Folder-form skill. Must contain SKILL.md (case-sensitive,
+            // Anthropic spec). Skip folders that don't (e.g. accidental
+            // dirs like 'auto/' that exist in current vault).
+            if (!existsSync(path.join(fullPath, 'SKILL.md')))
+                continue;
+            out.push(parseSkillFolder(fullPath, scope).skill);
+            continue;
+        }
+        if (st.isFile() && isLoadableSkillFile(entry)) {
+            out.push(parseSkillFile(fullPath, scope).skill);
+        }
     }
     return out;
 }
-/** Top-level discovery API. Returns the merged list of skills across
- *  global + per-project pools, with per-project taking precedence on
- *  name collision. usedByTriggers is populated when jobs are passed in. */
+/** Top-level discovery API. Merges global + per-project pools, with
+ *  per-project taking precedence. Populates usedByTriggers when jobs
+ *  are passed. Returned list is sorted alphabetically by name. */
 export function listSkills(opts = {}) {
     const globalSkills = listSkillsInDir(globalSkillsDir(), 'global');
     const projectSkills = opts.projectWorkDir
@@ -243,14 +403,11 @@ export function listSkills(opts = {}) {
             return pdir ? listSkillsInDir(pdir, 'project') : [];
         })()
         : [];
-    // Build a map keyed by basename so per-project entries override global.
     const merged = new Map();
     for (const s of globalSkills)
         merged.set(s.frontmatter.name, s);
     for (const s of projectSkills)
         merged.set(s.frontmatter.name, s);
-    // Used-by join from cron jobs' skills[] array. Same skill referenced by
-    // multiple jobs accumulates them in order.
     if (opts.jobs && opts.jobs.length > 0) {
         for (const job of opts.jobs) {
             if (!Array.isArray(job.skills))
@@ -262,52 +419,60 @@ export function listSkills(opts = {}) {
             }
         }
     }
-    // Sorted alphabetically — predictable rendering, no need for the
-    // dashboard to re-sort. Per-project always sorts at the same key as
-    // the global version it replaced.
     return [...merged.values()].sort((a, b) => a.frontmatter.name.localeCompare(b.frontmatter.name));
 }
-/** Get a single skill by name, with the same global/project precedence
- *  as listSkills. Returns null if neither pool has the skill. */
+/** Get one skill by name, applying per-project precedence. Returns
+ *  null when neither pool has the skill. */
 export function getSkill(name, opts = {}) {
-    // Per-project first (precedence).
+    // Per-project first (precedence), then global.
+    const tryDir = (dir, scope) => {
+        const folder = path.join(dir, name);
+        if (existsSync(folder) && existsSync(path.join(folder, 'SKILL.md'))) {
+            return parseSkillFolder(folder, scope).skill;
+        }
+        const flat = path.join(dir, name + '.md');
+        if (existsSync(flat)) {
+            return parseSkillFile(flat, scope).skill;
+        }
+        return null;
+    };
+    let skill = null;
     if (opts.projectWorkDir) {
         const pdir = projectSkillsDir(opts.projectWorkDir);
-        if (pdir) {
-            const candidate = path.join(pdir, name + '.md');
-            if (existsSync(candidate)) {
-                const result = parseSkillFile(candidate, 'project');
-                if (opts.jobs)
-                    result.skill.usedByTriggers = jobsUsing(name, opts.jobs);
-                return result.skill;
-            }
-        }
+        if (pdir)
+            skill = tryDir(pdir, 'project');
     }
-    // Global fallback.
-    const candidate = path.join(globalSkillsDir(), name + '.md');
-    if (existsSync(candidate)) {
-        const result = parseSkillFile(candidate, 'global');
-        if (opts.jobs)
-            result.skill.usedByTriggers = jobsUsing(name, opts.jobs);
-        return result.skill;
+    if (!skill)
+        skill = tryDir(globalSkillsDir(), 'global');
+    if (skill && opts.jobs) {
+        for (const j of opts.jobs) {
+            if (Array.isArray(j.skills) && j.skills.includes(name))
+                skill.usedByTriggers.push(j.name);
+        }
     }
-    return null;
+    return skill;
 }
-/** Internal helper for the used-by join. */
-function jobsUsing(skillName, jobs) {
-    const out = [];
-    for (const job of jobs) {
-        if (Array.isArray(job.skills) && job.skills.includes(skillName))
-            out.push(job.name);
+/** Read one bundled file's contents — used by Phase B's preview pane.
+ *  Defends against directory traversal: rejects paths that escape the
+ *  skill folder. */
+export function readBundledFile(skill, relPath) {
+    if (skill.layout !== 'folder')
+        return null;
+    const skillFolder = path.dirname(skill.filePath);
+    const absPath = path.resolve(skillFolder, relPath);
+    if (!absPath.startsWith(skillFolder + path.sep) && absPath !== skillFolder)
+        return null;
+    if (!existsSync(absPath))
+        return null;
+    try {
+        return readFileSync(absPath, 'utf-8');
+    }
+    catch {
+        return null;
     }
-    return out;
 }
-/** Test-only: where the loader looked. Useful in unit tests + the
- *  dashboard's diagnostics surface. */
+/** Diagnostics for the dashboard — expose where the loader looked. */
 export function _skillDirsForDiagnostics(workDir) {
-    return {
-        global: globalSkillsDir(),
-        project: projectSkillsDir(workDir) ?? null,
-    };
+    return { global: globalSkillsDir(), project: projectSkillsDir(workDir) ?? null };
 }
 //# sourceMappingURL=skill-store.js.map

package/dist/cli/dashboard.js

@@ -26872,6 +26872,29 @@ function onSkillsSearch(value) {
   renderSkillsList();
 }
 
+// ── Skill list pane ──────────────────────────────────────────────────
+// Renders the left-rail skill list. Each card shows two compact badges:
+//  - schemaBadge: ANTHROPIC (green) / CLEMENTINE (purple) / LEGACY (yellow)
+//  - layoutBadge: FOLDER (subtle accent) — only shown when folder-form
+// Plus optional PROJECT scope badge. Below: description preview, used-by
+// count, and a small ✗ when validation has any errors.
+function _skillSchemaBadge(version) {
+  if (version === 'anthropic') {
+    return '<span style="font-size:9px;background:var(--green)20;color:var(--green);padding:1px 6px;border-radius:3px;font-weight:600;letter-spacing:0.04em" title="Vanilla Anthropic frontmatter (name + description only)">ANTHROPIC</span>';
+  }
+  if (version === 'clementine') {
+    return '<span style="font-size:9px;background:#8b5cf620;color:#8b5cf6;padding:1px 6px;border-radius:3px;font-weight:600;letter-spacing:0.04em" title="Anthropic-compatible + clementine: extensions">CLEMENTINE</span>';
+  }
+  return '<span style="font-size:9px;background:var(--yellow)20;color:var(--yellow);padding:1px 6px;border-radius:3px;font-weight:600;letter-spacing:0.04em" title="Pre-redesign flat frontmatter — Phase B will help migrate">LEGACY</span>';
+}
+
+function _skillLayoutBadge(layout) {
+  if (layout === 'folder') {
+    return '<span style="font-size:9px;background:var(--accent)15;color:var(--accent);padding:1px 6px;border-radius:3px;font-weight:600;letter-spacing:0.04em" title="Folder form (Anthropic spec): SKILL.md plus optional bundled files">FOLDER</span>';
+  }
+  return '';
+}
+
 function renderSkillsList() {
   var listEl = document.getElementById('skills-list');
   if (!listEl) return;
@@ -26879,7 +26902,7 @@ function renderSkillsList() {
     listEl.innerHTML = '<div style="padding:18px;color:var(--text-muted);font-size:12px;text-align:center;line-height:1.5">'
       + (_skillsState.query
           ? 'No skills match <strong>' + esc(_skillsState.query) + '</strong>.'
-          : 'No skills yet. Phase B will add a <strong>+ New skill</strong> button. For now, drop .md files in <code>~/.clementine/vault/00-System/skills/</code>.')
+          : 'No skills yet. Drop a folder with <code>SKILL.md</code> inside, or a flat <code>.md</code> file, into <code>~/.clementine/vault/00-System/skills/</code>. Phase B will add a <strong>+ New skill</strong> button.')
       + '</div>';
     return;
   }
@@ -26889,21 +26912,21 @@ function renderSkillsList() {
     var fm = s.frontmatter || {};
     var isSelected = s.frontmatter.name === _skillsState.selectedName;
     var bg = isSelected ? 'var(--bg-tertiary)' : 'transparent';
-    // Schema badge: v1 = green, legacy = yellow (needs migration in Phase B).
-    var schemaBadge = s.schemaVersion === 'v1'
-      ? '<span style="font-size:9px;background:var(--green)20;color:var(--green);padding:1px 6px;border-radius:3px;font-weight:600;letter-spacing:0.04em">V1</span>'
-      : '<span style="font-size:9px;background:var(--yellow)20;color:var(--yellow);padding:1px 6px;border-radius:3px;font-weight:600;letter-spacing:0.04em" title="Legacy frontmatter — Phase B will migrate this">LEGACY</span>';
+    var schemaBadge = _skillSchemaBadge(s.schemaVersion);
+    var layoutBadge = _skillLayoutBadge(s.layout);
     var scopeBadge = s.scope === 'project'
       ? '<span style="font-size:9px;background:var(--blue)20;color:var(--blue);padding:1px 6px;border-radius:3px;font-weight:600;letter-spacing:0.04em" title="Loaded from per-project .clementine/skills/">PROJECT</span>'
       : '';
+    var hasErrors = Array.isArray(s.validation) && s.validation.some(function(v) { return v.severity === 'error'; });
+    var errorMark = hasErrors ? '<span style="color:var(--red);font-size:11px;font-weight:600" title="Has validation errors">⚠</span>' : '';
     var usedCount = (s.usedByTriggers || []).length;
     var displayName = fm.title || fm.name;
     var desc = (fm.description || '').slice(0, 100);
     if (fm.description && fm.description.length > 100) desc += '…';
     html += '<div onclick="showSkillDetail(\\x27' + jsStr(fm.name) + '\\x27)" style="padding:12px 14px;border-bottom:1px solid var(--border);cursor:pointer;background:' + bg + ';transition:background 0.1s" onmouseover="this.style.background=\\x27var(--bg-tertiary)\\x27" onmouseout="this.style.background=\\x27' + bg + '\\x27">'
-      + '<div style="display:flex;align-items:center;gap:6px;margin-bottom:4px">'
-      +   schemaBadge + scopeBadge
-      +   '<span style="font-weight:500;font-size:13px;color:var(--text-primary);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1" title="' + esc(displayName) + '">' + esc(displayName) + '</span>'
+      + '<div style="display:flex;align-items:center;gap:4px;margin-bottom:4px;flex-wrap:wrap">'
+      +   schemaBadge + layoutBadge + scopeBadge + errorMark
+      +   '<span style="font-weight:500;font-size:13px;color:var(--text-primary);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1;min-width:0" title="' + esc(displayName) + '">' + esc(displayName) + '</span>'
       + '</div>'
       + (desc ? '<div style="font-size:11px;color:var(--text-muted);line-height:1.4;margin-bottom:4px">' + esc(desc) + '</div>' : '')
       + '<div style="font-size:10px;color:var(--text-muted)">'
@@ -26933,72 +26956,117 @@ async function showSkillDetail(name) {
   }
 }
 
+// ── Skill detail pane ────────────────────────────────────────────────
+// Renders a single skill in the right pane. Sections, in order:
+//   1. Header (name + 3 badges + description + file path)
+//   2. Validation warnings (red errors / yellow warnings) when present
+//   3. Used-by triggers
+//   4. Bundled files (folder-form only) — sibling .md and scripts/
+//   5. Clementine extensions (inputs / tools / dataSources / stateKeys /
+//      success / limits) — only when frontmatter.clementine is present
+//   6. Legacy fields (triggers / toolsUsed / useCount / lastUsed)
+//   7. Procedure body (with line counter "X/500")
+//   8. Schema-specific footer note (legacy → migration hint)
 function renderSkillDetail(s) {
   var fm = s.frontmatter || {};
+  var ext = fm.clementine || {};
   var displayName = fm.title || fm.name;
+  var bodyLines = (s.body || '').split('\\n').length;
   var html = '<div style="padding:24px 28px">';
-  // Header
+
+  // ── 1. Header
   html += '<div style="margin-bottom:18px">';
-  html += '<div style="display:flex;align-items:center;gap:10px;margin-bottom:8px;flex-wrap:wrap">';
+  html += '<div style="display:flex;align-items:center;gap:8px;margin-bottom:8px;flex-wrap:wrap">';
   html += '<h2 style="margin:0;font-size:20px;font-weight:600;color:var(--text-primary)">' + esc(displayName) + '</h2>';
-  html += s.schemaVersion === 'v1'
-    ? '<span style="font-size:10px;background:var(--green)20;color:var(--green);padding:2px 8px;border-radius:4px;font-weight:600;letter-spacing:0.04em">V1 SCHEMA</span>'
-    : '<span style="font-size:10px;background:var(--yellow)20;color:var(--yellow);padding:2px 8px;border-radius:4px;font-weight:600;letter-spacing:0.04em" title="Phase B will migrate this">LEGACY SCHEMA</span>';
+  html += _skillSchemaBadge(s.schemaVersion).replace('font-size:9px', 'font-size:10px').replace('padding:1px 6px', 'padding:2px 8px');
+  if (s.layout === 'folder') {
+    html += '<span style="font-size:10px;background:var(--accent)15;color:var(--accent);padding:2px 8px;border-radius:4px;font-weight:600;letter-spacing:0.04em" title="Folder layout (Anthropic spec)">FOLDER</span>';
+  } else {
+    html += '<span style="font-size:10px;background:var(--bg-tertiary);color:var(--text-muted);padding:2px 8px;border-radius:4px;font-weight:600;letter-spacing:0.04em" title="Single-file Clementine legacy layout">FLAT</span>';
+  }
   if (s.scope === 'project') {
     html += '<span style="font-size:10px;background:var(--blue)20;color:var(--blue);padding:2px 8px;border-radius:4px;font-weight:600">PROJECT-SCOPED</span>';
   }
-  if (typeof fm.version === 'number') {
-    html += '<span style="font-size:10px;color:var(--text-muted)">v' + esc(fm.version) + '</span>';
+  if (typeof ext.version === 'number') {
+    html += '<span style="font-size:10px;color:var(--text-muted);font-weight:500">v' + esc(ext.version) + '</span>';
   }
   html += '</div>';
   if (fm.description) {
     html += '<p style="font-size:13px;color:var(--text-secondary);line-height:1.5;margin:0">' + esc(fm.description) + '</p>';
+  } else {
+    html += '<p style="font-size:12px;color:var(--text-muted);font-style:italic;margin:0">No description. Anthropic spec recommends adding one so the skill can be discovered by Claude.</p>';
   }
-  html += '<div style="margin-top:8px;font-size:11px;color:var(--text-muted)">'
-       + 'File: <code style="font-size:10px">' + esc(s.filePath) + '</code>'
-       + '</div>';
+  html += '<div style="margin-top:10px;font-size:11px;color:var(--text-muted);font-family:\\x27JetBrains Mono\\x27,monospace">' + esc(s.filePath) + '</div>';
   html += '</div>';
 
-  // Used-by triggers
+  // ── 2. Validation warnings (if any)
+  if (Array.isArray(s.validation) && s.validation.length > 0) {
+    var errors = s.validation.filter(function(v) { return v.severity === 'error'; });
+    var warnings = s.validation.filter(function(v) { return v.severity === 'warning'; });
+    if (errors.length > 0) {
+      html += '<div style="margin-bottom:18px;padding:12px 14px;background:rgba(239,68,68,0.08);border:1px solid var(--red);border-radius:6px">';
+      html += '<div style="font-size:11px;color:var(--red);text-transform:uppercase;letter-spacing:0.04em;font-weight:600;margin-bottom:6px">' + errors.length + ' error' + (errors.length === 1 ? '' : 's') + ' — Anthropic spec violation</div>';
+      html += '<ul style="margin:0;padding-left:18px;font-size:12px;line-height:1.5;color:var(--text-secondary)">';
+      for (var ei = 0; ei < errors.length; ei++) {
+        html += '<li><strong style="color:var(--red)">' + esc(errors[ei].field) + ':</strong> ' + esc(errors[ei].message) + '</li>';
+      }
+      html += '</ul></div>';
+    }
+    if (warnings.length > 0) {
+      html += '<div style="margin-bottom:18px;padding:12px 14px;background:rgba(245,158,11,0.08);border:1px solid var(--yellow);border-radius:6px">';
+      html += '<div style="font-size:11px;color:var(--yellow);text-transform:uppercase;letter-spacing:0.04em;font-weight:600;margin-bottom:6px">' + warnings.length + ' suggestion' + (warnings.length === 1 ? '' : 's') + '</div>';
+      html += '<ul style="margin:0;padding-left:18px;font-size:12px;line-height:1.5;color:var(--text-secondary)">';
+      for (var wi = 0; wi < warnings.length; wi++) {
+        html += '<li><strong>' + esc(warnings[wi].field) + ':</strong> ' + esc(warnings[wi].message) + '</li>';
+      }
+      html += '</ul></div>';
+    }
+  }
+
+  // ── 3. Used-by triggers
   if (Array.isArray(s.usedByTriggers) && s.usedByTriggers.length > 0) {
     html += '<div style="margin-bottom:18px;padding:12px 14px;background:var(--bg-tertiary);border-radius:6px">';
     html += '<div style="font-size:11px;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;margin-bottom:6px;font-weight:500">Used by ' + s.usedByTriggers.length + ' trigger' + (s.usedByTriggers.length === 1 ? '' : 's') + '</div>';
     html += '<div style="display:flex;flex-wrap:wrap;gap:6px">';
-    for (var i = 0; i < s.usedByTriggers.length; i++) {
-      html += '<span style="font-size:11px;background:var(--bg-secondary);padding:2px 8px;border-radius:4px;border:1px solid var(--border);color:var(--text-secondary)">' + esc(s.usedByTriggers[i]) + '</span>';
+    for (var ui = 0; ui < s.usedByTriggers.length; ui++) {
+      html += '<span style="font-size:11px;background:var(--bg-secondary);padding:2px 8px;border-radius:4px;border:1px solid var(--border);color:var(--text-secondary)">' + esc(s.usedByTriggers[ui]) + '</span>';
     }
     html += '</div></div>';
   }
 
-  // V1 fields (only render when present)
-  if (fm.inputs && Object.keys(fm.inputs).length > 0) {
-    html += renderSkillSection('Inputs', renderSkillInputs(fm.inputs));
+  // ── 4. Bundled files (folder-form only)
+  if (s.layout === 'folder' && Array.isArray(s.bundledFiles) && s.bundledFiles.length > 0) {
+    html += renderSkillSection('Bundled files (' + s.bundledFiles.length + ')', renderSkillBundledFiles(s.bundledFiles));
+  }
+
+  // ── 5. Clementine extensions
+  if (ext.inputs && Object.keys(ext.inputs).length > 0) {
+    html += renderSkillSection('Inputs', renderSkillInputs(ext.inputs));
   }
-  if (fm.tools && (fm.tools.allow?.length || fm.tools.deny?.length)) {
-    html += renderSkillSection('Tools', renderSkillTools(fm.tools));
+  if (ext.tools && ((ext.tools.allow && ext.tools.allow.length) || (ext.tools.deny && ext.tools.deny.length))) {
+    html += renderSkillSection('Tools', renderSkillTools(ext.tools));
   }
-  if (Array.isArray(fm.dataSources) && fm.dataSources.length > 0) {
-    html += renderSkillSection('Data sources', renderSkillDataSources(fm.dataSources));
+  if (Array.isArray(ext.dataSources) && ext.dataSources.length > 0) {
+    html += renderSkillSection('Data sources', renderSkillDataSources(ext.dataSources));
   }
-  if (Array.isArray(fm.stateKeys) && fm.stateKeys.length > 0) {
-    html += renderSkillSection('State keys', '<div style="display:flex;flex-wrap:wrap;gap:4px">' + fm.stateKeys.map(function(k) { return '<code style="font-size:11px;background:var(--bg-tertiary);padding:2px 6px;border-radius:3px">' + esc(k) + '</code>'; }).join('') + '</div>');
+  if (Array.isArray(ext.stateKeys) && ext.stateKeys.length > 0) {
+    html += renderSkillSection('State keys', '<div style="display:flex;flex-wrap:wrap;gap:4px">' + ext.stateKeys.map(function(k) { return '<code style="font-size:11px;background:var(--bg-tertiary);padding:2px 6px;border-radius:3px">' + esc(k) + '</code>'; }).join('') + '</div>');
   }
-  if (fm.success && (fm.success.criterion || fm.success.schema)) {
+  if (ext.success && (ext.success.criterion || ext.success.schema)) {
     var sc = '';
-    if (fm.success.criterion) sc += '<div style="font-size:12px;line-height:1.5;color:var(--text-secondary);margin-bottom:8px"><em>Criterion:</em> ' + esc(fm.success.criterion) + '</div>';
-    if (fm.success.schema) sc += '<details><summary style="cursor:pointer;font-size:11px;color:var(--text-muted)">Schema</summary><pre style="font-size:11px;background:var(--bg-tertiary);padding:10px;border-radius:6px;margin-top:6px;overflow:auto">' + esc(JSON.stringify(fm.success.schema, null, 2)) + '</pre></details>';
+    if (ext.success.criterion) sc += '<div style="font-size:12px;line-height:1.5;color:var(--text-secondary);margin-bottom:8px"><em>Criterion:</em> ' + esc(ext.success.criterion) + '</div>';
+    if (ext.success.schema) sc += '<details><summary style="cursor:pointer;font-size:11px;color:var(--text-muted)">Schema</summary><pre style="font-size:11px;background:var(--bg-tertiary);padding:10px;border-radius:6px;margin-top:6px;overflow:auto">' + esc(JSON.stringify(ext.success.schema, null, 2)) + '</pre></details>';
     html += renderSkillSection('Success criterion', sc);
   }
-  if (fm.limits) {
-    var l = fm.limits;
-    var bits = [];
-    if (l.maxTurns) bits.push('max ' + l.maxTurns + ' turns');
-    if (l.maxBudgetUsd) bits.push('$' + l.maxBudgetUsd + ' budget');
-    if (l.timeoutSeconds) bits.push(l.timeoutSeconds + 's timeout');
-    if (bits.length) html += renderSkillSection('Limits', '<div style="font-size:12px;color:var(--text-secondary)">' + bits.map(esc).join(' · ') + '</div>');
+  if (ext.limits) {
+    var lbits = [];
+    if (ext.limits.maxTurns) lbits.push('max ' + ext.limits.maxTurns + ' turns');
+    if (ext.limits.maxBudgetUsd) lbits.push('$' + ext.limits.maxBudgetUsd + ' budget');
+    if (ext.limits.timeoutSeconds) lbits.push(ext.limits.timeoutSeconds + 's timeout');
+    if (lbits.length) html += renderSkillSection('Limits', '<div style="font-size:12px;color:var(--text-secondary)">' + lbits.map(esc).join(' · ') + '</div>');
   }
 
-  // Legacy fields (preserved for the migration UI)
+  // ── 6. Legacy fields (preserved for migration UI in Phase B)
   if (Array.isArray(fm.triggers) && fm.triggers.length > 0) {
     html += renderSkillSection('Triggers (legacy NLP phrases)',
       '<div style="display:flex;flex-wrap:wrap;gap:4px">'
@@ -27012,27 +27080,35 @@ function renderSkillDetail(s) {
       + fm.toolsUsed.map(function(t) { return '<code style="font-size:11px;background:var(--bg-tertiary);padding:2px 6px;border-radius:3px">' + esc(t) + '</code>'; }).join('')
       + '</div>');
   }
-  if (fm.useCount || fm.lastUsed) {
-    var bits = [];
-    if (fm.useCount) bits.push('Used ' + fm.useCount + ' times');
-    if (fm.lastUsed) bits.push('Last: ' + new Date(fm.lastUsed).toLocaleString());
-    html += renderSkillSection('Usage', '<div style="font-size:12px;color:var(--text-secondary)">' + bits.map(esc).join(' · ') + '</div>');
+  if (fm.useCount || ext.lastUsed) {
+    var ubits = [];
+    if (fm.useCount) ubits.push('Used ' + fm.useCount + ' times');
+    if (ext.lastUsed) ubits.push('Last: ' + new Date(ext.lastUsed).toLocaleString());
+    html += renderSkillSection('Usage', '<div style="font-size:12px;color:var(--text-secondary)">' + ubits.map(esc).join(' · ') + '</div>');
   }
 
-  // Body — markdown rendered as preformatted text. Phase B will add a
-  // proper markdown renderer; Phase A keeps it simple to ship.
+  // ── 7. Procedure body (with line counter)
   if (s.body && s.body.trim()) {
+    var bodyClass = bodyLines > 500 ? 'color:var(--yellow)' : 'color:var(--text-muted)';
     html += '<div style="margin-top:18px">';
-    html += '<div style="font-size:11px;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;margin-bottom:8px;font-weight:500">Procedure</div>';
+    html += '<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:8px">';
+    html +=   '<div style="font-size:11px;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;font-weight:500">Procedure</div>';
+    html +=   '<div style="font-size:10px;' + bodyClass + ';font-family:\\x27JetBrains Mono\\x27,monospace">' + bodyLines + ' / 500 lines</div>';
+    html += '</div>';
     html += '<pre style="font-size:12px;line-height:1.55;background:var(--bg-tertiary);padding:14px 16px;border-radius:6px;white-space:pre-wrap;word-break:break-word;font-family:inherit;border:1px solid var(--border);max-height:500px;overflow:auto">' + esc(s.body) + '</pre>';
     html += '</div>';
   }
 
+  // ── 8. Schema-specific footer
   if (s.schemaVersion === 'legacy') {
-    html += '<div style="margin-top:24px;padding:12px 14px;background:var(--yellow)15;border:1px solid var(--yellow);border-radius:6px;font-size:12px;color:var(--text-secondary);line-height:1.5">'
+    html += '<div style="margin-top:24px;padding:12px 14px;background:rgba(245,158,11,0.08);border:1px solid var(--yellow);border-radius:6px;font-size:12px;color:var(--text-secondary);line-height:1.5">'
          + '<strong style="color:var(--yellow)">Legacy schema.</strong> '
-         + 'This skill uses the pre-redesign frontmatter shape (title / triggers / toolsUsed / useCount). '
-         + 'Phase B will surface a one-click migration that converts it to v1 (inputs / tools.allow / dataSources / stateKeys / success).'
+         + 'This skill uses the pre-redesign frontmatter shape. Phase B will offer a one-click migration to the Anthropic-compatible format (name + description top-level; cron-tailored fields under <code>clementine:</code>).'
+         + '</div>';
+  } else if (s.schemaVersion === 'anthropic' && s.layout === 'flat') {
+    html += '<div style="margin-top:24px;padding:12px 14px;background:rgba(59,130,246,0.06);border:1px solid var(--blue);border-radius:6px;font-size:12px;color:var(--text-secondary);line-height:1.5">'
+         + '<strong style="color:var(--blue)">Anthropic-compatible.</strong> '
+         + 'This skill matches the official Anthropic spec exactly. Consider promoting it to <strong>folder form</strong> (<code>' + esc(fm.name) + '/SKILL.md</code>) so you can bundle reference files and scripts later.'
          + '</div>';
   }
 
@@ -27040,6 +27116,36 @@ function renderSkillDetail(s) {
   return html;
 }
 
+// PRD § Skills-First Phase A.5 / 1.18.108: bundled file tree.
+// Renders the folder's sibling files + scripts/ contents grouped by kind.
+// Each row: icon (📄 markdown / ⚙ script / · other), relPath, size.
+function renderSkillBundledFiles(files) {
+  var iconFor = function(kind) {
+    if (kind === 'markdown') return '📄';
+    if (kind === 'script') return '⚙';
+    return '·';
+  };
+  var fmt = function(bytes) {
+    if (bytes < 1024) return bytes + ' B';
+    if (bytes < 1024 * 1024) return Math.round(bytes / 1024) + ' KB';
+    return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+  };
+  var html = '<div style="font-family:\\x27JetBrains Mono\\x27,monospace;font-size:11px;background:var(--bg-tertiary);border-radius:6px;padding:10px 14px">';
+  for (var i = 0; i < files.length; i++) {
+    var f = files[i];
+    var indentStyle = f.relPath.indexOf('/') !== -1 ? 'padding-left:20px' : '';
+    html += '<div style="display:flex;justify-content:space-between;align-items:center;padding:3px 0;' + indentStyle + '">'
+      + '<span style="color:var(--text-secondary)">'
+      +   '<span style="display:inline-block;width:18px;color:var(--text-muted)">' + iconFor(f.kind) + '</span>'
+      +   esc(f.relPath)
+      + '</span>'
+      + '<span style="font-size:10px;color:var(--text-muted)">' + esc(fmt(f.sizeBytes)) + '</span>'
+      + '</div>';
+  }
+  html += '</div>';
+  return html;
+}
+
 function renderSkillSection(title, body) {
   return '<div style="margin-bottom:18px">'
     + '<div style="font-size:11px;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.04em;margin-bottom:8px;font-weight:500">' + esc(title) + '</div>'

package/dist/types.d.ts

@@ -309,13 +309,18 @@ export interface AgentHeartbeatState {
      */
     lastTickKind?: 'acted' | 'quiet' | 'silent' | 'override';
 }
-/** Source of a skill file — informational, used by the dashboard. */
+/** Where a skill was loaded from. Per-project skills shadow global. */
 export type SkillScope = 'global' | 'project';
-/** Whether the file's frontmatter matches the v1 spec or is the
- *  pre-redesign shape. Drives the "needs migration" badge in the UI. */
-export type SkillSchemaVersion = 'v1' | 'legacy';
-/** A typed skill input — backed by JSON Schema. The dashboard form
- *  generator can derive UI directly from a JSON Schema; ajv validates. */
+/** Three states the dashboard surfaces as badges:
+ *    'anthropic' — only `name` + `description` (vanilla Anthropic spec)
+ *    'clementine' — has the `clementine:` namespace with extensions
+ *    'legacy'    — pre-redesign flat frontmatter (title/triggers/toolsUsed) */
+export type SkillSchemaVersion = 'anthropic' | 'clementine' | 'legacy';
+/** Whether the on-disk layout is a folder-with-SKILL.md (Anthropic spec)
+ *  or a single .md file (Clementine flat legacy). New skills should be
+ *  created in folder form so they can grow bundled files later. */
+export type SkillLayout = 'folder' | 'flat';
+/** A typed skill input — backed by JSON Schema. Used in `clementine.inputs`. */
 export interface SkillInputSchema {
     type?: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object';
     description?: string;
@@ -330,96 +335,125 @@ export interface SkillInputSchema {
     properties?: Record<string, SkillInputSchema>;
     required?: string[];
 }
-/** Declarative entry describing where a skill reads data from. Surfaced
- *  in the dashboard's per-skill detail pane and in the Tools & MCP "used
- *  by" join. Free-form by design — different skills declare different
- *  data shapes. */
+/** Declarative entry describing where a skill reads data from. */
 export interface SkillDataSource {
-    /** A loose identifier — e.g. 'outlook', 'memory', 'vault', 'cli', 'mcp:ElevenLabs'. */
+    /** Loose identifier — 'outlook', 'memory', 'vault', 'cli', 'mcp:ElevenLabs'. */
     kind: string;
-    /** One-line human description — what the skill reads from this source. */
+    /** One-line human description of what gets read. */
     purpose: string;
 }
-/** Tool allowlist + denylist on a skill. Deny wins on conflict. The
- *  runtime (Phase C) will refuse to invoke a tool that isn't on allow,
- *  even if the trigger tries to override. */
+/** Tool allowlist + denylist. Deny wins on conflict. Phase C runtime
+ *  refuses tools not in `allow`, even when a trigger tries to override. */
 export interface SkillToolPolicy {
     allow?: string[];
     deny?: string[];
 }
-/** Success criterion. Either schema (ajv-validated against the run's
- *  structured_output) or criterion (free-text Haiku evaluator). Both =
- *  both must pass. Mirrors the existing CronJobDefinition shape. */
+/** Success criterion — JSON Schema (ajv-validated) and/or free-text. */
 export interface SkillSuccess {
     schema?: SkillInputSchema;
     criterion?: string;
 }
-/** Per-skill caps. A trigger can tighten these but never loosen. */
+/** Per-skill caps. A trigger can tighten but never loosen. */
 export interface SkillLimits {
     maxTurns?: number;
     maxBudgetUsd?: number;
     timeoutSeconds?: number;
 }
-/** Parsed frontmatter + computed metadata. Phase A surfaces this whole
- *  shape in the Skills page detail pane. */
-export interface SkillFrontmatter {
-    /** Skill identifier — derived from filename if absent in frontmatter. */
-    name: string;
-    /** One-line description (matches today's `description:` field). */
-    description?: string;
+/** Clementine-specific extensions. All optional. Lives under the
+ *  `clementine:` key in the YAML frontmatter so an Anthropic skill that
+ *  doesn't have these stays valid. */
+export interface ClementineSkillExtensions {
     /** Typed parameters the skill accepts at invocation time. */
     inputs?: Record<string, SkillInputSchema>;
     /** Tool allowlist + denylist enforced by the runtime. */
     tools?: SkillToolPolicy;
     /** Where the skill reads data from — purely declarative. */
     dataSources?: SkillDataSource[];
-    /** State.* keys this skill owns (others can't touch them). */
+    /** state.* keys this skill owns. Others can't touch them. */
     stateKeys?: string[];
     /** Success criterion — schema and/or free-text evaluator. */
     success?: SkillSuccess;
     /** Caps the trigger can tighten but never loosen. */
     limits?: SkillLimits;
-    /** Bumped by the user on Publish (Phase B). Phase A surfaces but
-     *  doesn't increment. */
+    /** Skill version — bumped on Publish in Phase B. */
     version?: number;
-    /** Timestamps captured by the legacy + v1 schemas alike. */
+    /** Timestamps Clementine captures. */
     createdAt?: string;
     updatedAt?: string;
     lastUsed?: string;
-    /** Last time the user clicked "Test this skill" in the dashboard
-     *  (Phase B). Phase A reads but doesn't write. */
+    /** Last successful "Test this skill" run (Phase B). */
     lastTestPass?: string;
-    /** Legacy: title (use as fallback for display when description missing). */
+}
+/** Parsed frontmatter. Anthropic-canonical fields are top-level; our
+ *  extensions live under `clementine`. Legacy fields (title/triggers/
+ *  toolsUsed/useCount) are also top-level — they're what the existing
+ *  pre-redesign skills already use and we keep them readable. */
+export interface SkillFrontmatter {
+    /** Skill identifier. Filename is canonical; this field is honored when
+     *  set but not required. Anthropic spec: max 64 chars, lowercase letters
+     *  + numbers + hyphens, no XML, no reserved words ('anthropic'/'claude'). */
+    name: string;
+    /** What the skill does AND when to use it (third person). Anthropic
+     *  spec: non-empty, max 1024 chars, no XML tags. */
+    description?: string;
+    /** Optional namespace for cron-tailored fields. Absent on vanilla
+     *  Anthropic skills; present on Clementine-extended skills. */
+    clementine?: ClementineSkillExtensions;
+    /** Legacy: human-friendly display title. Falls back to `name` when absent. */
     title?: string;
-    /** Legacy: NLP-style trigger phrases. Pre-redesign Clementine matched
-     *  these against incoming chat messages. */
+    /** Legacy: NLP-style trigger phrases for chat-message matching. */
     triggers?: string[];
     /** Legacy: 'manual' / 'auto' / 'imported' — provenance label. */
     source?: string;
-    /** Legacy: tools observed during runs. Informational, not constraint. */
+    /** Legacy: tools observed during runs. Informational, not enforced. */
     toolsUsed?: string[];
-    /** Legacy: incrementing counter of how many runs invoked the skill. */
+    /** Legacy: incrementing counter of runs that invoked the skill. */
     useCount?: number;
 }
+/** A bundled file inside a folder-form skill. `kind` distinguishes
+ *  loadable markdown from executable scripts so the dashboard can
+ *  render them differently. */
+export interface SkillBundledFile {
+    /** Path relative to the skill folder (e.g. 'FORMS.md', 'scripts/extract.py'). */
+    relPath: string;
+    /** Absolute path on disk. */
+    absPath: string;
+    /** Loose categorization for rendering: markdown reference vs script vs other. */
+    kind: 'markdown' | 'script' | 'other';
+    /** File size in bytes — surfaced as "X KB" in the dashboard. */
+    sizeBytes: number;
+}
+/** A validation finding for a skill — surfaced in the dashboard so
+ *  authors can see what to fix. Severity 'error' indicates a spec
+ *  violation (rejected by Anthropic API); 'warning' is a best-practice
+ *  hint (still loadable). */
+export interface SkillValidationWarning {
+    severity: 'error' | 'warning';
+    field: 'name' | 'description' | 'body' | 'frontmatter' | 'layout';
+    message: string;
+}
 /** Resolved skill record — frontmatter + body + computed extras the
- *  dashboard surfaces (file path, scope, schemaVersion, used-by list). */
+ *  dashboard surfaces. */
 export interface Skill {
-    /** Frontmatter, parsed (or synthesized for files without one). */
+    /** Parsed frontmatter (or synthesized when none / unparseable). */
     frontmatter: SkillFrontmatter;
-    /** Markdown body of the skill — the actual procedure. */
+    /** Markdown body of the skill (the actual procedure). */
     body: string;
-    /** Absolute path to the source .md file. */
+    /** Absolute path to the entry-point file. For folder-form skills this
+     *  points at <folder>/SKILL.md. For flat skills it points at <name>.md. */
     filePath: string;
-    /** Whether this skill was loaded from the global pool or a per-project
-     *  override. Per-project wins on name collision. */
+    /** Where this skill was loaded from (global vs per-project). */
     scope: SkillScope;
-    /** Whether the frontmatter matches the v1 spec or is the pre-redesign
-     *  shape. The Skills page renders a "Schema: legacy" badge accordingly. */
+    /** Folder-form (Anthropic-spec) vs flat-file (Clementine legacy). */
+    layout: SkillLayout;
+    /** Anthropic / clementine / legacy — drives the schema badge. */
     schemaVersion: SkillSchemaVersion;
-    /** Used-by join: cron job names that reference this skill. Phase A
-     *  builds this from the legacy `skills:` array on CronJobDefinition;
-     *  Phase C extends it to read the new top-level `skill:` field. */
+    /** Sibling .md files + scripts/ contents (only populated for folder-form). */
+    bundledFiles: SkillBundledFile[];
+    /** Used-by join: cron jobs that reference this skill via skills[]. */
     usedByTriggers: string[];
+    /** Validation findings — populated lazily so listSkills stays cheap. */
+    validation: SkillValidationWarning[];
 }
 export interface CronJobDefinition {
     name: string;

package/package.json

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