pi-hermes-memory 0.7.9 → 0.7.11

package/src/handlers/skills-command.ts

@@ -24,6 +24,7 @@ export const MEMORY_SKILLS_KEYMAP = {
   moveGlobal: "g",
   moveProject: "p",
   deleteSelected: "d",
+  cycleSort: "s",
   selectAllFiltered: "a",
   clearSelection: "n",
   focusSearch: "/",
@@ -34,6 +35,7 @@ export const MEMORY_SKILLS_KEYMAP = {
 } as const;
 
 export type SkillRowCategory = "G" | "P" | "E";
+export type SkillSortMode = "updated" | "created" | "name";
 
 export interface SkillModalRow {
   skillId: string;
@@ -45,6 +47,8 @@ export interface SkillModalRow {
   description: string;
   path: string;
   displayPath: string;
+  created?: string;
+  updated?: string;
   projectName?: string;
   selected: boolean;
   searchText: string;
@@ -162,6 +166,70 @@ function categoryOrder(category: SkillRowCategory): number {
   }
 }
 
+function recencyValue(row: Pick<SkillModalRow, "updated" | "created">): string {
+  return row.updated || row.created || "";
+}
+
+function sortModeLabel(sortMode: SkillSortMode): string {
+  switch (sortMode) {
+    case "updated":
+      return "Updated";
+    case "created":
+      return "Created";
+    case "name":
+      return "Name";
+  }
+}
+
+function nextSortMode(sortMode: SkillSortMode): SkillSortMode {
+  switch (sortMode) {
+    case "updated":
+      return "created";
+    case "created":
+      return "name";
+    case "name":
+      return "updated";
+  }
+}
+
+function compareSkillRows(a: SkillModalRow, b: SkillModalRow, sortMode: SkillSortMode): number {
+  if (sortMode === "name") {
+    const byName = a.displayName.localeCompare(b.displayName);
+    if (byName !== 0) return byName;
+    return categoryOrder(a.category) - categoryOrder(b.category);
+  }
+
+  const primaryA = sortMode === "updated" ? recencyValue(a) : (a.created || "");
+  const primaryB = sortMode === "updated" ? recencyValue(b) : (b.created || "");
+  if (primaryA || primaryB) {
+    if (!primaryA) return 1;
+    if (!primaryB) return -1;
+    if (primaryA !== primaryB) return primaryB.localeCompare(primaryA);
+  }
+
+  if (sortMode === "updated") {
+    const createdA = a.created || "";
+    const createdB = b.created || "";
+    if (createdA || createdB) {
+      if (!createdA) return 1;
+      if (!createdB) return -1;
+      if (createdA !== createdB) return createdB.localeCompare(createdA);
+    }
+  } else {
+    const updatedA = recencyValue(a);
+    const updatedB = recencyValue(b);
+    if (updatedA || updatedB) {
+      if (!updatedA) return 1;
+      if (!updatedB) return -1;
+      if (updatedA !== updatedB) return updatedB.localeCompare(updatedA);
+    }
+  }
+
+  const byCategory = categoryOrder(a.category) - categoryOrder(b.category);
+  if (byCategory !== 0) return byCategory;
+  return a.displayName.localeCompare(b.displayName);
+}
+
 export function collectLoadedSkillsFromCommands(commands: SkillCommandInfo[]): LoadedSkillRow[] {
   const loaded: LoadedSkillRow[] = [];
 
@@ -214,8 +282,8 @@ export function formatSkillsList(rows: SkillModalRow[], projectName: string | nu
   if (rows.length === 0) {
     lines.push("  (no skills found in this session)");
     lines.push("");
-    lines.push("  Skills are auto-created after complex tasks,");
-    lines.push("  or you can ask the agent to create one.");
+    lines.push("  Ask the agent to save a reusable procedure");
+    lines.push("  with the skill tool when it is worth keeping.");
     return lines.join("\n");
   }
 
@@ -269,6 +337,8 @@ export function buildSkillRows(skills: SkillIndex[], selectedSkillIds = new Set<
       description: skill.description,
       path: skill.path,
       displayPath,
+      created: skill.created,
+      updated: skill.updated,
       projectName: skill.projectName,
       selected: selectedSkillIds.has(skill.skillId),
       searchText: `${displayName} ${skill.name} ${skill.description || ""} ${skill.path} ${displayPath}`.trim(),
@@ -280,6 +350,7 @@ export function buildUnifiedSkillRows(
   managedSkills: SkillIndex[],
   loadedSkills: LoadedSkillRow[],
   selectedSkillIds = new Set<string>(),
+  sortMode: SkillSortMode = "updated",
 ): SkillModalRow[] {
   const managedRows = buildSkillRows(managedSkills, selectedSkillIds);
   const managedPathKeys = new Set(managedRows.map((row) => normalizePathForKey(row.path)));
@@ -308,12 +379,7 @@ export function buildUnifiedSkillRows(
     });
   }
 
-  return [...managedRows, ...externalRows]
-    .sort((a, b) => {
-      const byCategory = categoryOrder(a.category) - categoryOrder(b.category);
-      if (byCategory !== 0) return byCategory;
-      return a.displayName.localeCompare(b.displayName);
-    });
+  return [...managedRows, ...externalRows].sort((a, b) => compareSkillRows(a, b, sortMode));
 }
 
 export function filterSkillRows(rows: SkillModalRow[], query: string): SkillModalRow[] {
@@ -534,8 +600,9 @@ export class SkillsManagerModal implements Focusable {
   private activeFilters: SkillCategoryFilters = { ...DEFAULT_SKILL_FILTERS };
   private pendingFilters: SkillCategoryFilters | null = null;
   private filterCursor = 0;
+  private sortMode: SkillSortMode = "updated";
   private summaryLines: string[] = [
-    "Select skills with space, then move with g/p or delete with d. Press f for filters.",
+    "Select skills with space, then move with g/p or delete with d. Press s to change sort and f for filters.",
   ];
 
   constructor(
@@ -573,9 +640,11 @@ export class SkillsManagerModal implements Focusable {
           name: row.name,
           displayName: row.displayName,
           description: row.description,
+          created: row.created ?? "",
+          updated: row.updated ?? "",
         }));
 
-    this.rows = buildUnifiedSkillRows(this.managedSkills, this.loadedSkills, selectedSkillIds);
+    this.rows = buildUnifiedSkillRows(this.managedSkills, this.loadedSkills, selectedSkillIds, this.sortMode);
     this.syncSearchFocus();
   }
 
@@ -632,7 +701,7 @@ export class SkillsManagerModal implements Focusable {
 
   private setRows(managedSkills: SkillIndex[], retainSelectedSkillIds: string[] = [], focusSkillId?: string): void {
     this.managedSkills = managedSkills;
-    this.rows = buildUnifiedSkillRows(this.managedSkills, this.loadedSkills, new Set(retainSelectedSkillIds));
+    this.rows = buildUnifiedSkillRows(this.managedSkills, this.loadedSkills, new Set(retainSelectedSkillIds), this.sortMode);
     this.syncQueryFromInput();
 
     const rows = this.filteredRows;
@@ -687,6 +756,34 @@ export class SkillsManagerModal implements Focusable {
     this.tui.requestRender();
   }
 
+  private cycleSortMode(): void {
+    this.sortMode = nextSortMode(this.sortMode);
+    const selectedIds = this.getSelectedIds();
+    const currentRow = this.getCurrentRow();
+    this.rows = buildUnifiedSkillRows(
+      this.managedSkills,
+      this.loadedSkills,
+      new Set(selectedIds),
+      this.sortMode,
+    );
+    this.syncQueryFromInput();
+
+    const rows = this.filteredRows;
+    if (rows.length === 0) {
+      this.selectedIndex = 0;
+    } else if (currentRow) {
+      const focusIndex = rows.findIndex((row) => row.skillId === currentRow.skillId);
+      this.selectedIndex = focusIndex >= 0
+        ? focusIndex
+        : Math.min(this.selectedIndex, rows.length - 1);
+    } else {
+      this.selectedIndex = Math.min(this.selectedIndex, rows.length - 1);
+    }
+
+    this.summaryLines = [`Sort mode: ${sortModeLabel(this.sortMode)}.`];
+    this.tui.requestRender();
+  }
+
   private appendExternalReadOnlySummary(
     result: SkillBatchActionResult,
     blockedExternalRows: SkillModalRow[],
@@ -943,6 +1040,10 @@ export class SkillsManagerModal implements Focusable {
       this.openFilterPanel();
       return;
     }
+    if (data === MEMORY_SKILLS_KEYMAP.cycleSort) {
+      this.cycleSortMode();
+      return;
+    }
 
     if (matchesKey(data, Key.tab) || matchesKey(data, Key.slash)) {
       this.focusSearchWithOptionalInput();
@@ -998,7 +1099,7 @@ export class SkillsManagerModal implements Focusable {
       this.promptDelete();
       return;
     }
-    if (this.isPrintableInput(data) && !["g", "p", "d", "a", "n", "f"].includes(data)) {
+    if (this.isPrintableInput(data) && !["g", "p", "d", "a", "n", "f", "s"].includes(data)) {
       this.focusSearchWithOptionalInput(data);
     }
   }
@@ -1076,7 +1177,7 @@ export class SkillsManagerModal implements Focusable {
     lines.push(this.renderFramedLine(
       this.theme.fg(
         "dim",
-        `${filteredRows.length} visible · ${this.rows.length} total · ${selectedCount} selected${this.busy ? " · working…" : ""}`,
+        `${filteredRows.length} visible · ${this.rows.length} total · ${selectedCount} selected · sort: ${sortModeLabel(this.sortMode)}${this.busy ? " · working…" : ""}`,
       ),
       safeWidth,
     ));
@@ -1141,8 +1242,8 @@ export class SkillsManagerModal implements Focusable {
     const help = this.pendingDeleteConfirm
       ? "Confirm delete: y yes · n no · esc cancel"
       : this.callbacks.projectName
-        ? "↑↓ move · space select · / search · f filters · tab switch · g global · p project · d delete · a all · n none · esc close"
-        : "↑↓ move · space select · / search · f filters · tab switch · g global · p project (disabled) · d delete · a all · n none · esc close";
+        ? "↑↓ move · space select · / search · s sort · f filters · tab switch · g global · p project · d delete · a all · n none · esc close"
+        : "↑↓ move · space select · / search · s sort · f filters · tab switch · g global · p project (disabled) · d delete · a all · n none · esc close";
     lines.push(this.renderFramedLine(this.theme.fg("dim", help), safeWidth));
 
     if (this.focusArea === "filters") {

package/src/handlers/sync-markdown-memories.ts

@@ -12,6 +12,7 @@ import {
   syncMemoryEntry,
 } from '../store/sqlite-memory-store.js';
 import { ENTRY_DELIMITER, MEMORY_FILE, USER_FILE } from '../constants.js';
+import { AGENT_ROOT } from '../paths.js';
 
 export interface BackfillCounters {
   filesScanned: number;
@@ -64,10 +65,14 @@ function scanProjectDirs(agentRoot: string, globalDir: string, projectsMemoryDir
     }
   }
 
-  const globalDirName = path.basename(globalDir);
+  const resolvedAgentRoot = path.resolve(agentRoot);
+  const resolvedGlobalDir = path.resolve(globalDir);
+  const globalDirName = path.dirname(resolvedGlobalDir) === resolvedAgentRoot
+    ? path.basename(resolvedGlobalDir)
+    : null;
   if (fs.existsSync(agentRoot)) {
     for (const name of fs.readdirSync(agentRoot)) {
-      if (name === globalDirName || name === projectsMemoryDir || name === 'skills' || name.startsWith('.')) continue;
+      if ((globalDirName && name === globalDirName) || name === projectsMemoryDir || name === 'skills' || name.startsWith('.')) continue;
       if (projects.has(name)) continue;
       const dir = path.join(agentRoot, name);
       const memoryFile = path.join(dir, MEMORY_FILE);
@@ -86,6 +91,7 @@ export function syncMarkdownMemoriesToSqlite(
   dbManager: DatabaseManager,
   globalDir: string,
   projectsMemoryDir?: string,
+  agentRoot = AGENT_ROOT,
 ): BackfillCounters & { projectCount: number } {
   const counters: BackfillCounters = {
     filesScanned: 0,
@@ -114,7 +120,6 @@ export function syncMarkdownMemoriesToSqlite(
   importFile(globalUserFile, 'user');
   importFile(globalFailureFile, 'failure');
 
-  const agentRoot = path.dirname(globalDir);
   const projects = scanProjectDirs(agentRoot, globalDir, projectsMemoryDir);
   for (const project of projects) {
     importFile(project.memoryFile, 'memory', project.name);
@@ -128,6 +133,7 @@ export function registerSyncMarkdownMemoriesCommand(
   dbManager: DatabaseManager,
   globalDir: string,
   projectsMemoryDir?: string,
+  agentRoot = AGENT_ROOT,
 ): void {
   pi.registerCommand('memory-sync-markdown', {
     description: 'Backfill Markdown memories into the SQLite search store',
@@ -135,7 +141,7 @@ export function registerSyncMarkdownMemoriesCommand(
       ctx.ui.notify('🔄 Scanning Markdown memory files for SQLite backfill...', 'info');
 
       try {
-        const counters = syncMarkdownMemoriesToSqlite(dbManager, globalDir, projectsMemoryDir);
+        const counters = syncMarkdownMemoriesToSqlite(dbManager, globalDir, projectsMemoryDir, agentRoot);
 
         let output = `\n✅ Markdown → SQLite sync complete!\n\n`;
         output += `📊 Results:\n`;

package/src/index.ts

@@ -23,7 +23,6 @@
  */
 
 import * as path from "node:path";
-import * as os from "node:os";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { MemoryStore } from "./store/memory-store.js";
 import { SkillStore } from "./store/skill-store.js";
@@ -39,7 +38,6 @@ import { setupSessionFlush } from "./handlers/session-flush.js";
 import { registerInsightsCommand } from "./handlers/insights.js";
 import { triggerConsolidation, registerConsolidateCommand } from "./handlers/auto-consolidate.js";
 import { setupCorrectionDetector } from "./handlers/correction-detector.js";
-import { setupSkillAutoTrigger } from "./handlers/skill-auto-trigger.js";
 import { registerSkillsCommand } from "./handlers/skills-command.js";
 import { registerInterviewCommand } from "./handlers/interview.js";
 import { registerSwitchProjectCommand } from "./handlers/switch-project.js";
@@ -52,6 +50,7 @@ import { detectProject, detectProjectSkills } from "./project.js";
 import { buildPromptContext } from "./prompt-context.js";
 import { migrateLegacyProjectMemoryDirs } from "./project-memory-migration.js";
 import { migrateExtensionRoot } from "./extension-root-migration.js";
+import { AGENT_ROOT } from "./paths.js";
 
 export function resolveProjectSkillDiscovery(
   skillStore: SkillStore,
@@ -80,7 +79,7 @@ export function registerProjectSkillDiscoveryHandler(
 export default function (pi: ExtensionAPI) {
   const config = loadConfig();
 
-  const agentRoot = path.join(os.homedir(), ".pi", "agent");
+  const agentRoot = AGENT_ROOT;
   const legacyGlobalDir = path.join(agentRoot, "memory");
   const defaultGlobalDir = path.join(agentRoot, "pi-hermes-memory");
 
@@ -121,9 +120,9 @@ export default function (pi: ExtensionAPI) {
   // Keep project memory available for users upgrading from the old
   // ~/.pi/agent/<project>/ layout. This is non-destructive: legacy folders
   // remain in place while entries are copied/merged into projects-memory/.
-  migrateLegacyProjectMemoryDirs(globalDir, config.projectsMemoryDir);
+  migrateLegacyProjectMemoryDirs(agentRoot, config.projectsMemoryDir);
   try {
-    syncMarkdownMemoriesToSqlite(dbManager, globalDir, config.projectsMemoryDir);
+    syncMarkdownMemoriesToSqlite(dbManager, globalDir, config.projectsMemoryDir, agentRoot);
   } catch {
     // Best-effort only: failed SQLite backfill should not block extension startup.
   }
@@ -136,7 +135,7 @@ export default function (pi: ExtensionAPI) {
   const projectStore = project.memoryDir ? new MemoryStore(projectConfig) : null;
 
   // ── 1. Load memory from disk on session start ──
-  pi.on("session_start", async (event, _ctx) => {
+  pi.on("session_start", async (_event, ctx) => {
     if (shouldMigrateExtensionRoot && !extensionRootMigrated) {
       try {
         await migrateExtensionRoot(legacyGlobalDir, globalDir);
@@ -146,7 +145,7 @@ export default function (pi: ExtensionAPI) {
       extensionRootMigrated = true;
     }
 
-    refreshSkillProjectContext((event as { cwd?: string }).cwd);
+    refreshSkillProjectContext(ctx.cwd);
     await skillStore.migrateLegacySkills();
     await skillStore.ensureDiscoveredRoots();
     await store.loadFromDisk();
@@ -187,24 +186,21 @@ export default function (pi: ExtensionAPI) {
   // ── 8. Setup correction detection ──
   setupCorrectionDetector(pi, store, projectStore, config, dbManager, projectName);
 
-  // ── 9. Setup skill auto-trigger ──
-  setupSkillAutoTrigger(pi, store, skillStore, config);
-
-  // ── 10. Register commands ──
+  // ── 9. Register commands ──
   registerInsightsCommand(pi, store, projectStore, projectName);
   registerSkillsCommand(pi, skillStore);
   registerInterviewCommand(pi, store);
   registerSwitchProjectCommand(pi, config);
   registerLearnMemoryCommand(pi);
-  registerSyncMarkdownMemoriesCommand(pi, dbManager, globalDir, config.projectsMemoryDir);
+  registerSyncMarkdownMemoriesCommand(pi, dbManager, globalDir, config.projectsMemoryDir, agentRoot);
   registerPreviewContextCommand(pi, store, projectStore, projectName, config);
 
-  // ── 11. SQLite session search + extended memory ──
+  // ── 10. SQLite session search + extended memory ──
   registerSessionSearchTool(pi, dbManager, config.sessionSearch ?? { variant: "legacy" });
   registerMemorySearchTool(pi, dbManager);
   registerIndexSessionsCommand(pi);
 
-  // ── 12. Auto-index session on shutdown ──
+  // ── 11. Auto-index session on shutdown ──
   pi.on("session_shutdown", async (_event, ctx) => {
     try {
       const sessionFile = ctx.sessionManager.getSessionFile();

package/src/paths.ts

@@ -0,0 +1,57 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { DEFAULT_PROJECTS_MEMORY_DIR } from "./constants.js";
+
+export const AGENT_ROOT = path.join(os.homedir(), ".pi", "agent");
+
+export function expandHome(input: string): string {
+  if (input === "~") return os.homedir();
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return path.join(os.homedir(), input.slice(2));
+  }
+  return input;
+}
+
+export function normalizeConfiguredMemoryDir(input: string): string | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) return undefined;
+
+  const expanded = expandHome(trimmed);
+  if (path.isAbsolute(expanded)) return path.normalize(expanded);
+  return path.resolve(AGENT_ROOT, expanded);
+}
+
+function isSafeRelativeDirectory(input: string): boolean {
+  const segments = input.split(/[\\/]+/).filter(Boolean);
+  return segments.length === 1 && segments[0] !== "." && segments[0] !== "..";
+}
+
+export function normalizeProjectsMemoryDir(input: string): string | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) return undefined;
+
+  const expanded = expandHome(trimmed);
+  let relative = expanded;
+
+  if (path.isAbsolute(expanded)) {
+    const resolved = path.resolve(expanded);
+    const relativeToAgentRoot = path.relative(AGENT_ROOT, resolved);
+    if (
+      relativeToAgentRoot === ""
+      || relativeToAgentRoot.startsWith("..")
+      || path.isAbsolute(relativeToAgentRoot)
+    ) {
+      return undefined;
+    }
+    relative = relativeToAgentRoot;
+  }
+
+  const normalized = path.normalize(relative).replace(/^[\\/]+|[\\/]+$/g, "");
+  if (!isSafeRelativeDirectory(normalized)) return undefined;
+  return normalized;
+}
+
+export function resolveProjectsRoot(projectsMemoryDir = DEFAULT_PROJECTS_MEMORY_DIR): string {
+  const normalized = normalizeProjectsMemoryDir(projectsMemoryDir) ?? DEFAULT_PROJECTS_MEMORY_DIR;
+  return path.join(AGENT_ROOT, normalized);
+}

package/src/project-memory-migration.ts

@@ -31,7 +31,7 @@ function isLegacyProjectDir(agentRoot: string, projectsMemoryDir: string, name:
 }
 
 export function migrateLegacyProjectMemoryDirs(
-  globalDir: string,
+  agentRoot: string,
   projectsMemoryDir = "projects-memory",
 ): ProjectMemoryMigrationResult {
   const result: ProjectMemoryMigrationResult = {
@@ -42,7 +42,6 @@ export function migrateLegacyProjectMemoryDirs(
     warnings: [],
   };
 
-  const agentRoot = path.dirname(globalDir);
   if (!fs.existsSync(agentRoot)) return result;
 
   const projectsRoot = path.join(agentRoot, projectsMemoryDir);

package/src/project.ts

@@ -5,6 +5,7 @@
 
 import * as path from "node:path";
 import * as os from "node:os";
+import { resolveProjectsRoot } from "./paths.js";
 
 export interface ProjectInfo {
   /** Project name (directory basename), or null if not in a project. */
@@ -44,7 +45,7 @@ export function detectProject(projectsMemoryDir = "projects-memory", cwd?: strin
 
   return {
     name,
-    memoryDir: path.join(homeDir, ".pi", "agent", projectsMemoryDir, name),
+    memoryDir: path.join(resolveProjectsRoot(projectsMemoryDir), name),
   };
 }
 

package/src/store/skill-store.ts

@@ -253,6 +253,8 @@ export class SkillStore {
     }
 
     return skills.sort((a, b) => {
+      if (a.updated !== b.updated) return b.updated.localeCompare(a.updated);
+      if (a.created !== b.created) return b.created.localeCompare(a.created);
       if (a.scope !== b.scope) return a.scope.localeCompare(b.scope);
       return (a.displayName || a.name).localeCompare(b.displayName || b.name);
     });
@@ -290,7 +292,7 @@ export class SkillStore {
     if (existing) {
       return {
         success: false,
-        error: `Skill '${slug}' already exists (${skillId}). Use 'patch' or 'edit' to update it.`,
+        error: `Skill '${slug}' already exists (${skillId}). Use 'patch' or 'update' to update it.`,
         conflictType: "duplicate",
         similarSkillIds: [skillId],
         suggestedAction: "patch",
@@ -303,7 +305,7 @@ export class SkillStore {
         const targetId = similarSkillIds[0];
         return {
           success: false,
-          error: `A similar global skill already exists (${targetId}). Enhance the existing skill with new learnings/failures using 'patch' or 'edit' instead of creating a duplicate.`,
+          error: `A similar global skill already exists (${targetId}). Enhance the existing skill with new learnings/failures using 'patch' or 'update' instead of creating a duplicate.`,
           conflictType: "similar",
           similarSkillIds,
           suggestedAction: "patch",
@@ -315,7 +317,7 @@ export class SkillStore {
         const targetId = collidingNameSkillIds[0];
         return {
           success: false,
-          error: `A near-name global skill already exists (${targetId}) but with different intent. Use a clearer differentiated name for the new skill, or patch/edit the existing skill if the intent is actually the same.`,
+          error: `A near-name global skill already exists (${targetId}) but with different intent. Use a clearer differentiated name for the new skill, or patch/update the existing skill if the intent is actually the same.`,
           conflictType: "name-collision",
           similarSkillIds: collidingNameSkillIds,
           suggestedAction: "rename",
@@ -790,6 +792,8 @@ export class SkillStore {
       name: doc.name,
       displayName: doc.displayName,
       description: doc.description,
+      created: doc.created,
+      updated: doc.updated,
     };
   }
 

package/src/store/skill-utils.ts

@@ -6,6 +6,19 @@ export interface ParsedSkillFile {
   body: string;
 }
 
+function parseScalar(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (typeof parsed === "string") return parsed;
+    } catch {
+      // fall through to raw trimmed
+    }
+  }
+  return trimmed;
+}
+
 export function parseFrontmatter(raw: string): ParsedSkillFile {
   const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!match) return { meta: {}, body: raw.trim() };
@@ -15,7 +28,7 @@ export function parseFrontmatter(raw: string): ParsedSkillFile {
     const idx = line.indexOf(":");
     if (idx > 0) {
       const key = line.slice(0, idx).trim();
-      const value = line.slice(idx + 1).trim();
+      const value = parseScalar(line.slice(idx + 1));
       meta[key] = value;
     }
   }
@@ -23,18 +36,22 @@ export function parseFrontmatter(raw: string): ParsedSkillFile {
   return { meta, body: match[2].trim() };
 }
 
+function yamlDoubleQuoted(value: string): string {
+  return JSON.stringify(value);
+}
+
 export function formatFrontmatter(doc: Pick<SkillDocument, "name" | "displayName" | "description" | "version" | "created" | "updated" | "body">): string {
   const lines = [
     "---",
-    `name: ${doc.name}`,
-    `description: ${doc.description}`,
+    `name: ${yamlDoubleQuoted(doc.name)}`,
+    `description: ${yamlDoubleQuoted(doc.description)}`,
     `version: ${doc.version}`,
-    `created: ${doc.created}`,
-    `updated: ${doc.updated}`,
+    `created: ${yamlDoubleQuoted(doc.created)}`,
+    `updated: ${yamlDoubleQuoted(doc.updated)}`,
   ];
 
   if (doc.displayName && doc.displayName.trim() && doc.displayName.trim() !== doc.name) {
-    lines.push(`display_name: ${doc.displayName.trim()}`);
+    lines.push(`display_name: ${yamlDoubleQuoted(doc.displayName.trim())}`);
   }
 
   lines.push("---", doc.body);