clementine-agent 1.18.105 → 1.18.107

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

@@ -0,0 +1,60 @@
+/**
+ * Skill store — Phase A (read-only) 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.
+ *
+ * Discovery order:
+ *   1. ~/.clementine/vault/00-System/skills/<name>.md  (global)
+ *   2. <work_dir>/.clementine/skills/<name>.md         (per-project)
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import type { Skill, SkillScope, CronJobDefinition } from '../types.js';
+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. */
+    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. */
+export declare function parseSkillFile(filePath: 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. */
+    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). */
+    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. */
+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. */
+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. */
+export declare function _skillDirsForDiagnostics(workDir?: string): {
+    global: string;
+    project: string | null;
+};
+export {};
+//# sourceMappingURL=skill-store.d.ts.map

package/dist/agent/skill-store.js

@@ -0,0 +1,313 @@
+/**
+ * Skill store — Phase A (read-only) 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.
+ *
+ * Discovery order:
+ *   1. ~/.clementine/vault/00-System/skills/<name>.md  (global)
+ *   2. <work_dir>/.clementine/skills/<name>.md         (per-project)
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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). */
+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');
+}
+/** 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';
+}
+/** 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;
+    }
+    // tools.allow / tools.deny
+    if (raw.tools && typeof raw.tools === 'object' && !Array.isArray(raw.tools)) {
+        const t = raw.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;
+    }
+    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(raw.stateKeys))
+        fm.stateKeys = raw.stateKeys.map(String);
+    if (raw.success && typeof raw.success === 'object' && !Array.isArray(raw.success)) {
+        const s = raw.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;
+    }
+    if (raw.limits && typeof raw.limits === 'object' && !Array.isArray(raw.limits)) {
+        const l = raw.limits;
+        const limits = {};
+        if (typeof l.maxTurns === 'number')
+            limits.maxTurns = l.maxTurns;
+        if (typeof l.maxBudgetUsd === 'number')
+            limits.maxBudgetUsd = l.maxBudgetUsd;
+        if (typeof l.timeoutSeconds === 'number')
+            limits.timeoutSeconds = l.timeoutSeconds;
+        if (Object.keys(limits).length > 0)
+            fm.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 raw.title === 'string')
+        fm.title = raw.title;
+    if (Array.isArray(raw.triggers))
+        fm.triggers = raw.triggers.map(String);
+    if (typeof raw.source === 'string')
+        fm.source = raw.source;
+    if (Array.isArray(raw.toolsUsed))
+        fm.toolsUsed = raw.toolsUsed.map(String);
+    if (typeof raw.useCount === 'number')
+        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. */
+export function parseSkillFile(filePath, scope) {
+    const basename = nameFromFile(filePath);
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        return {
+            skill: emptySkill(filePath, basename, scope),
+            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 data = parsed.data;
+    const fm = coerceFrontmatter(data, basename);
+    const schemaVersion = detectSchemaVersion(data);
+    return {
+        skill: {
+            frontmatter: fm,
+            body: parsed.content || '',
+            filePath,
+            scope,
+            schemaVersion,
+            usedByTriggers: [],
+        },
+    };
+}
+function emptySkill(filePath, basename, scope) {
+    return {
+        frontmatter: { name: basename },
+        body: '',
+        filePath,
+        scope,
+        schemaVersion: 'legacy',
+        usedByTriggers: [],
+    };
+}
+/** 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. */
+function listSkillsInDir(dir, scope) {
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!isSkillFile(entry))
+            continue;
+        const fullPath = path.join(dir, entry);
+        try {
+            const stat = statSync(fullPath);
+            if (!stat.isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        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. */
+export function listSkills(opts = {}) {
+    const globalSkills = listSkillsInDir(globalSkillsDir(), 'global');
+    const projectSkills = opts.projectWorkDir
+        ? (() => {
+            const pdir = projectSkillsDir(opts.projectWorkDir);
+            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))
+                continue;
+            for (const skillName of job.skills) {
+                const s = merged.get(skillName);
+                if (s)
+                    s.usedByTriggers.push(job.name);
+            }
+        }
+    }
+    // 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. */
+export function getSkill(name, opts = {}) {
+    // Per-project first (precedence).
+    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;
+            }
+        }
+    }
+    // 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;
+    }
+    return null;
+}
+/** 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);
+    }
+    return out;
+}
+/** Test-only: where the loader looked. Useful in unit tests + the
+ *  dashboard's diagnostics surface. */
+export function _skillDirsForDiagnostics(workDir) {
+    return {
+        global: globalSkillsDir(),
+        project: projectSkillsDir(workDir) ?? null,
+    };
+}
+//# sourceMappingURL=skill-store.js.map

package/dist/cli/dashboard.js

@@ -4609,6 +4609,44 @@ export async function cmdDashboard(opts) {
     //   POST /api/cron/:job/publish    — promote draft to CRON.md
     //   DELETE /api/cron/:job/draft    — discard the draft
     //   GET /api/cron/drafts           — list all drafted task names
+    // ── Skills-First redesign Phase A / 1.18.106: skill catalog (read-only) ─
+    // Two endpoints feed the new Skills page:
+    //   GET /api/skills              — full list with usedByTriggers join
+    //   GET /api/skills/:name        — single skill detail (frontmatter + body)
+    // Phase A is read-only; Phase B adds POST/PUT for editing.
+    app.get('/api/skills', async (_req, res) => {
+        try {
+            const { listSkills } = await import('../agent/skill-store.js');
+            const { parseCronJobs } = await import('../gateway/cron-scheduler.js');
+            const jobs = parseCronJobs();
+            const skills = listSkills({ jobs });
+            res.json({ ok: true, count: skills.length, skills });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.get('/api/skills/:name', async (req, res) => {
+        try {
+            const name = req.params.name;
+            if (!name) {
+                res.status(400).json({ ok: false, error: 'name required' });
+                return;
+            }
+            const { getSkill } = await import('../agent/skill-store.js');
+            const { parseCronJobs } = await import('../gateway/cron-scheduler.js');
+            const jobs = parseCronJobs();
+            const skill = getSkill(name, { jobs });
+            if (!skill) {
+                res.status(404).json({ ok: false, error: `skill "${name}" not found` });
+                return;
+            }
+            res.json({ ok: true, skill });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
     app.get('/api/cron/drafts', async (_req, res) => {
         try {
             const { listDraftNames } = await import('../agent/draft-store.js');
@@ -17116,6 +17154,13 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
         <span class="nav-icon"></span> Tasks
         <span class="nav-badge" id="nav-cron-count" style="display:none">0</span>
       </div>
+      <!-- Skills-First redesign Phase A / 1.18.106: read-only catalog
+           of skill files (procedures + tools + data + state). Phase B
+           adds editing + testing; Phase C wires runtime invocation. -->
+      <div class="nav-item" data-page="skills" data-icon="brain" title="Reusable skill files — procedures + tool allowlists + data sources">
+        <span class="nav-icon"></span> Skills
+        <span class="nav-badge" id="nav-skills-count" style="display:none">0</span>
+      </div>
       <div class="nav-item" data-page="heartbeat" data-icon="bell" title="Heartbeat controls and queued work">
         <span class="nav-icon"></span> Heartbeat
       </div>
@@ -20427,6 +20472,34 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
 
     <!-- page-goals merged into Team → Goals tab. -->
 
+    <!-- ═══ Skills Page — Phase A read-only catalog ═══
+         Skills-First redesign Phase A / 1.18.106: a list of every skill
+         file with detail pane. Editing + testing land in Phase B; runtime
+         invocation lands in Phase C. The page is intentionally minimal —
+         we want users to see what's there, not be overwhelmed by 7 tiles. -->
+    <div class="page" id="page-skills">
+      <div class="page-head">
+        <div class="icon icon-slot" data-icon="brain"></div>
+        <div class="title-block">
+          <h1>Skills</h1>
+          <p class="desc">Reusable procedures Clementine can run. Each skill declares its tools, data sources, and state.</p>
+        </div>
+      </div>
+      <div style="display:grid;grid-template-columns:380px 1fr;gap:18px;height:calc(100vh - 180px);min-height:500px">
+        <div id="skills-list-pane" style="overflow-y:auto;border:1px solid var(--border);border-radius:8px;background:var(--bg-secondary)">
+          <div style="padding:14px 16px;border-bottom:1px solid var(--border);display:flex;align-items:center;gap:8px">
+            <input type="search" id="skills-search" placeholder="Search skills…" oninput="onSkillsSearch(this.value)" style="flex:1;padding:6px 10px;font-size:12px;border:1px solid var(--border);border-radius:6px;background:var(--bg-primary);color:var(--text-primary)">
+          </div>
+          <div id="skills-list" style="padding:6px"></div>
+        </div>
+        <div id="skills-detail-pane" style="overflow-y:auto;border:1px solid var(--border);border-radius:8px;background:var(--bg-secondary);padding:0">
+          <div id="skills-detail" style="padding:24px;color:var(--text-muted);text-align:center;font-size:13px">
+            Select a skill on the left to see its procedure, tools, and data sources.
+          </div>
+        </div>
+      </div>
+    </div>
+
     <!-- ═══ Team Page — The Office ═══ -->
     <div class="page" id="page-team">
       <div class="page-head">
@@ -22106,7 +22179,7 @@ function lucide(name, cls) {
   return '<svg class="icn ' + (cls || '') + '" viewBox="0 0 24 24" aria-hidden="true">' + path + '</svg>';
 }
 
-var DESTINATIONS = ['home', 'build', 'heartbeat', 'team', 'brain', 'settings'];
+var DESTINATIONS = ['home', 'build', 'skills', 'heartbeat', 'team', 'brain', 'settings'];
 
 var ROUTE_REDIRECTS = {
   // old hash → new {page, tab}
@@ -22183,6 +22256,12 @@ function navigateTo(page, opts) {
       var bp = currentAgentSlug || '';
       refreshBuilderAgents(bp);
       break;
+    case 'skills':
+      // Skills-First redesign Phase A / 1.18.106: load the catalog when
+      // the user navigates to the Skills page. Read-only; no mutation
+      // surfaces here yet.
+      if (typeof refreshSkillsPage === 'function') refreshSkillsPage();
+      break;
     case 'heartbeat':
       refreshHeartbeatControl();
       break;
@@ -26730,6 +26809,294 @@ async function deleteDelegation(id) {
 
 // ── Heartbeat Queue ──────────────────────
 
+// ── Skills-First redesign Phase A / 1.18.106 ──────────────────────────
+// Read-only Skills page: list + detail. Phase B adds editor + Test
+// runner; Phase C wires runtime invocation; Phase D collapses Tasks
+// page complexity once Triggers can point at skills directly.
+//
+// State kept module-local so other surfaces (e.g. the Tools & MCP
+// catalog's future "used by" join) can read it without re-fetching.
+var _skillsState = {
+  data: [],          // raw skills array from /api/skills
+  filtered: [],      // text-filter result
+  selectedName: '',  // currently shown in detail pane
+  query: '',         // search input value
+};
+
+async function refreshSkillsPage() {
+  var listEl = document.getElementById('skills-list');
+  var detailEl = document.getElementById('skills-detail');
+  if (!listEl) return;
+  listEl.innerHTML = '<div style="padding:18px;color:var(--text-muted);font-size:12px">Loading skills…</div>';
+  try {
+    var r = await apiFetch('/api/skills');
+    var d = await r.json();
+    if (!r.ok || d.ok === false) {
+      listEl.innerHTML = '<div style="padding:18px;color:var(--red);font-size:12px">Failed to load: ' + esc(d.error || 'unknown') + '</div>';
+      return;
+    }
+    _skillsState.data = d.skills || [];
+    _skillsState.filtered = applySkillsFilter(_skillsState.data, _skillsState.query);
+    renderSkillsList();
+    var badge = document.getElementById('nav-skills-count');
+    if (badge) {
+      badge.textContent = String(_skillsState.data.length);
+      badge.style.display = _skillsState.data.length > 0 ? '' : 'none';
+    }
+    // If a skill was previously selected, reload its detail. Otherwise
+    // auto-select the first to give the user something to look at.
+    if (_skillsState.selectedName) {
+      var still = _skillsState.data.find(function(s) { return s.frontmatter.name === _skillsState.selectedName; });
+      if (still) showSkillDetail(_skillsState.selectedName);
+    } else if (_skillsState.filtered.length > 0) {
+      showSkillDetail(_skillsState.filtered[0].frontmatter.name);
+    }
+  } catch (e) {
+    listEl.innerHTML = '<div style="padding:18px;color:var(--red);font-size:12px">Error: ' + esc(String(e)) + '</div>';
+  }
+}
+
+function applySkillsFilter(skills, query) {
+  var q = (query || '').trim().toLowerCase();
+  if (!q) return skills.slice();
+  return skills.filter(function(s) {
+    var fm = s.frontmatter || {};
+    var hay = [fm.name, fm.title, fm.description, (fm.toolsUsed || []).join(' ')].filter(Boolean).join(' ').toLowerCase();
+    return hay.indexOf(q) !== -1;
+  });
+}
+
+function onSkillsSearch(value) {
+  _skillsState.query = value;
+  _skillsState.filtered = applySkillsFilter(_skillsState.data, value);
+  renderSkillsList();
+}
+
+function renderSkillsList() {
+  var listEl = document.getElementById('skills-list');
+  if (!listEl) return;
+  if (_skillsState.filtered.length === 0) {
+    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>.')
+      + '</div>';
+    return;
+  }
+  var html = '';
+  for (var i = 0; i < _skillsState.filtered.length; i++) {
+    var s = _skillsState.filtered[i];
+    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 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 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>'
+      + (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)">'
+      +   (usedCount > 0 ? 'Used by ' + usedCount + ' trigger' + (usedCount === 1 ? '' : 's') : '<span style="color:var(--text-muted);opacity:0.6">Unused</span>')
+      + '</div>'
+      + '</div>';
+  }
+  listEl.innerHTML = html;
+}
+
+async function showSkillDetail(name) {
+  _skillsState.selectedName = name;
+  renderSkillsList();  // re-render to update the highlight
+  var detailEl = document.getElementById('skills-detail');
+  if (!detailEl) return;
+  detailEl.innerHTML = '<div style="padding:24px;color:var(--text-muted);font-size:12px">Loading…</div>';
+  try {
+    var r = await apiFetch('/api/skills/' + encodeURIComponent(name));
+    var d = await r.json();
+    if (!r.ok || d.ok === false) {
+      detailEl.innerHTML = '<div style="padding:24px;color:var(--red);font-size:12px">Failed: ' + esc(d.error || 'unknown') + '</div>';
+      return;
+    }
+    detailEl.innerHTML = renderSkillDetail(d.skill);
+  } catch (e) {
+    detailEl.innerHTML = '<div style="padding:24px;color:var(--red);font-size:12px">Error: ' + esc(String(e)) + '</div>';
+  }
+}
+
+function renderSkillDetail(s) {
+  var fm = s.frontmatter || {};
+  var displayName = fm.title || fm.name;
+  var html = '<div style="padding:24px 28px">';
+  // Header
+  html += '<div style="margin-bottom:18px">';
+  html += '<div style="display:flex;align-items:center;gap:10px;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>';
+  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>';
+  }
+  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>';
+  }
+  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>';
+
+  // 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>';
+    }
+    html += '</div></div>';
+  }
+
+  // V1 fields (only render when present)
+  if (fm.inputs && Object.keys(fm.inputs).length > 0) {
+    html += renderSkillSection('Inputs', renderSkillInputs(fm.inputs));
+  }
+  if (fm.tools && (fm.tools.allow?.length || fm.tools.deny?.length)) {
+    html += renderSkillSection('Tools', renderSkillTools(fm.tools));
+  }
+  if (Array.isArray(fm.dataSources) && fm.dataSources.length > 0) {
+    html += renderSkillSection('Data sources', renderSkillDataSources(fm.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 (fm.success && (fm.success.criterion || fm.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>';
+    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>');
+  }
+
+  // Legacy fields (preserved for the migration UI)
+  if (Array.isArray(fm.triggers) && fm.triggers.length > 0) {
+    html += renderSkillSection('Triggers (legacy NLP phrases)',
+      '<div style="display:flex;flex-wrap:wrap;gap:4px">'
+      + fm.triggers.slice(0, 30).map(function(t) { return '<span style="font-size:11px;background:var(--bg-tertiary);padding:2px 6px;border-radius:3px;color:var(--text-secondary)">' + esc(t) + '</span>'; }).join('')
+      + (fm.triggers.length > 30 ? '<span style="font-size:11px;color:var(--text-muted)">+' + (fm.triggers.length - 30) + ' more</span>' : '')
+      + '</div>');
+  }
+  if (Array.isArray(fm.toolsUsed) && fm.toolsUsed.length > 0) {
+    html += renderSkillSection('Tools used (legacy informational)',
+      '<div style="display:flex;flex-wrap:wrap;gap:4px">'
+      + 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>');
+  }
+
+  // Body — markdown rendered as preformatted text. Phase B will add a
+  // proper markdown renderer; Phase A keeps it simple to ship.
+  if (s.body && s.body.trim()) {
+    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 += '<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>';
+  }
+
+  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">'
+         + '<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).'
+         + '</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>'
+    + body
+    + '</div>';
+}
+
+function renderSkillInputs(inputs) {
+  var html = '<table style="width:100%;font-size:12px;border-collapse:collapse">';
+  html += '<thead><tr style="border-bottom:1px solid var(--border);text-align:left">'
+    + '<th style="padding:6px 8px;font-weight:500;color:var(--text-muted);font-size:10px;text-transform:uppercase">Field</th>'
+    + '<th style="padding:6px 8px;font-weight:500;color:var(--text-muted);font-size:10px;text-transform:uppercase">Type</th>'
+    + '<th style="padding:6px 8px;font-weight:500;color:var(--text-muted);font-size:10px;text-transform:uppercase">Default</th>'
+    + '</tr></thead><tbody>';
+  Object.keys(inputs).forEach(function(key) {
+    var spec = inputs[key] || {};
+    html += '<tr style="border-bottom:1px solid var(--border-light)">';
+    html += '<td style="padding:6px 8px"><code style="font-size:11px">' + esc(key) + '</code></td>';
+    html += '<td style="padding:6px 8px;color:var(--text-secondary)">' + esc(spec.type || 'any') + '</td>';
+    html += '<td style="padding:6px 8px;color:var(--text-muted);font-size:11px">' + (spec.default !== undefined ? '<code>' + esc(JSON.stringify(spec.default)) + '</code>' : '—') + '</td>';
+    html += '</tr>';
+    if (spec.description) {
+      html += '<tr><td colspan="3" style="padding:0 8px 6px 16px;font-size:11px;color:var(--text-muted);font-style:italic">' + esc(spec.description) + '</td></tr>';
+    }
+  });
+  html += '</tbody></table>';
+  return html;
+}
+
+function renderSkillTools(tools) {
+  var html = '';
+  if (Array.isArray(tools.allow) && tools.allow.length > 0) {
+    html += '<div style="margin-bottom:6px;font-size:11px;color:var(--text-muted)">Allow:</div>';
+    html += '<div style="display:flex;flex-wrap:wrap;gap:4px;margin-bottom:8px">'
+      + tools.allow.map(function(t) { return '<code style="font-size:11px;background:var(--green)15;color:var(--green);padding:2px 6px;border-radius:3px">' + esc(t) + '</code>'; }).join('')
+      + '</div>';
+  }
+  if (Array.isArray(tools.deny) && tools.deny.length > 0) {
+    html += '<div style="margin-bottom:6px;font-size:11px;color:var(--text-muted)">Deny:</div>';
+    html += '<div style="display:flex;flex-wrap:wrap;gap:4px">'
+      + tools.deny.map(function(t) { return '<code style="font-size:11px;background:var(--red)15;color:var(--red);padding:2px 6px;border-radius:3px">' + esc(t) + '</code>'; }).join('')
+      + '</div>';
+  }
+  return html;
+}
+
+function renderSkillDataSources(sources) {
+  return '<ul style="list-style:none;padding:0;margin:0;font-size:12px">'
+    + sources.map(function(d) {
+        return '<li style="padding:4px 0;border-bottom:1px solid var(--border-light)">'
+          + '<code style="font-size:11px;background:var(--bg-tertiary);padding:1px 6px;border-radius:3px;margin-right:8px">' + esc(d.kind) + '</code>'
+          + '<span style="color:var(--text-secondary)">' + esc(d.purpose) + '</span>'
+          + '</li>';
+      }).join('')
+    + '</ul>';
+}
+
 async function refreshHeartbeatControl() {
   var container = document.getElementById('heartbeat-control-content');
   if (!container) return;

package/dist/types.d.ts

@@ -309,6 +309,118 @@ export interface AgentHeartbeatState {
      */
     lastTickKind?: 'acted' | 'quiet' | 'silent' | 'override';
 }
+/** Source of a skill file — informational, used by the dashboard. */
+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. */
+export interface SkillInputSchema {
+    type?: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object';
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    items?: 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. */
+export interface SkillDataSource {
+    /** A loose identifier — e.g. 'outlook', 'memory', 'vault', 'cli', 'mcp:ElevenLabs'. */
+    kind: string;
+    /** One-line human description — what the skill reads from this source. */
+    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. */
+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. */
+export interface SkillSuccess {
+    schema?: SkillInputSchema;
+    criterion?: string;
+}
+/** Per-skill caps. A trigger can tighten these 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;
+    /** 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). */
+    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. */
+    version?: number;
+    /** Timestamps captured by the legacy + v1 schemas alike. */
+    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. */
+    lastTestPass?: string;
+    /** Legacy: title (use as fallback for display when description missing). */
+    title?: string;
+    /** Legacy: NLP-style trigger phrases. Pre-redesign Clementine matched
+     *  these against incoming chat messages. */
+    triggers?: string[];
+    /** Legacy: 'manual' / 'auto' / 'imported' — provenance label. */
+    source?: string;
+    /** Legacy: tools observed during runs. Informational, not constraint. */
+    toolsUsed?: string[];
+    /** Legacy: incrementing counter of how many runs invoked the skill. */
+    useCount?: number;
+}
+/** Resolved skill record — frontmatter + body + computed extras the
+ *  dashboard surfaces (file path, scope, schemaVersion, used-by list). */
+export interface Skill {
+    /** Frontmatter, parsed (or synthesized for files without one). */
+    frontmatter: SkillFrontmatter;
+    /** Markdown body of the skill — the actual procedure. */
+    body: string;
+    /** Absolute path to the source .md file. */
+    filePath: string;
+    /** Whether this skill was loaded from the global pool or a per-project
+     *  override. Per-project wins on name collision. */
+    scope: SkillScope;
+    /** Whether the frontmatter matches the v1 spec or is the pre-redesign
+     *  shape. The Skills page renders a "Schema: legacy" badge accordingly. */
+    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. */
+    usedByTriggers: string[];
+}
 export interface CronJobDefinition {
     name: string;
     schedule: string;

package/package.json

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