@skilly-hand/skilly-hand 0.16.1 → 0.18.0

package/CHANGELOG.md

@@ -16,6 +16,44 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.18.0] - 2026-04-08
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.18.0)
+
+### Added
+- Added `sync-catalog` orchestration script to compute catalog README + skill frontmatter updates up front and apply writes atomically with rollback on failure.
+- Added `sync-skill-frontmatter` CLI script with `--check`, `--json`, and `--skill` filtering support.
+- Added regression coverage for catalog sync rollback/idempotency and frontmatter normalization edge cases (`tests/sync-catalog.test.js`, `tests/skill-frontmatter.test.js`).
+
+### Changed
+- Updated root `catalog:sync` script to run `scripts/sync-catalog.mjs` for unified catalog synchronization.
+- Expanded script JSON contract coverage for `sync-catalog` and `sync-skill-frontmatter` in `tests/scripts-output.test.js`.
+- Updated catalog validation flow to verify catalog README drift through dry-run sync checks.
+
+### Fixed
+- Hardened skill frontmatter parsing and verification to avoid false frontmatter detection and preserve markdown content for malformed leading YAML-like blocks.
+- Improved catalog README sync behavior to treat CRLF/LF-equivalent content as in sync.
+
+### Removed
+- _None._
+
+## [0.17.0] - 2026-04-08
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.17.0)
+
+### Added
+- Added sandbox harness and matrix integration tests (`scripts/test-in-sandbox.mjs`, `tests/sandbox-harness.test.js`, `tests/sandbox-matrix.test.js`) and wired them into the root test pipeline.
+- Added required `review-rangers` final-gate guidance to the spec-driven-development verify flow and validation checklist.
+
+### Changed
+- Updated installer reconciliation logic to remove stale managed targets when agent selection narrows, while preserving/restoring backups for retained targets.
+- Updated backup behavior to skip backup creation for files already marked as managed content.
+- Updated root `npm test` to run sandbox integration verification after the node test suite.
+
+### Fixed
+- Fixed uninstall and re-install behavior for narrowed agent selections by restoring original files and cleaning obsolete managed artifacts.
+
+### Removed
+- _None._
+
 ## [0.16.1] - 2026-04-08
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.16.1)
 

package/catalog/skills/accessibility-audit/SKILL.md

@@ -1,3 +1,24 @@
+---
+description: "Audit web accessibility against W3C WCAG 2.2 Level AA using framework-agnostic checks, remediation patterns, and portable command-line scanning."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-04"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added portable WCAG 2.2 Level AA accessibility auditing skill with W3C-only references and scanner script; enables consistent web accessibility review across frameworks; affects catalog skill coverage and install plans for stacks recommending accessibility-audit"
+  auto-invoke: "Auditing, reviewing, or implementing web accessibility against WCAG 2.2 Level AA"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "WebFetch"
+    - "WebSearch"
+    - "Task"
+    - "SubAgent"
+---
 # Accessibility Audit Guide
 
 ## When to Use

package/catalog/skills/agents-root-orchestrator/SKILL.md

@@ -1,3 +1,22 @@
+---
+description: "Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-03"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added root AGENTS orchestration guidance around Where/What/When structure; improves AI task routing clarity and trigger recognition; affects root AGENTS authoring workflow"
+  auto-invoke: "Creating or updating root AGENTS.md orchestration guidance"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "Task"
+    - "SubAgent"
+---
 # AGENTS Root Orchestrator Guide
 
 ## When to Use

package/catalog/skills/angular-guidelines/SKILL.md

@@ -1,3 +1,24 @@
+---
+description: "Guide Angular code generation and review using latest stable Angular verification and modern framework best practices."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-03"
+  license: "Apache-2.0"
+  version: "1.1.1"
+  changelog: "Added allowed-modes metadata to declare angular-guidelines sub-agent routing targets; improves discoverability of component-creator and angular-tester delegation modes; affects angular-guidelines manifest metadata"
+  auto-invoke: "Generating, reviewing, or refactoring Angular code artifacts in Angular projects"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "WebFetch"
+    - "WebSearch"
+    - "Task"
+    - "SubAgent"
+---
 # Angular Guidelines
 
 ## When to Use

package/catalog/skills/figma-mcp-0to1/SKILL.md

@@ -1,3 +1,24 @@
+---
+description: "Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-03"
+  license: "Apache-2.0"
+  version: "1.0.1"
+  changelog: "Added allowed-modes metadata to declare figma-mcp-0to1 sub-agent routing targets; improves discoverability of install-auth, tool-function-catalog, canvas-creation-playbook, and troubleshooting-ops delegation modes; affects figma-mcp-0to1 manifest metadata"
+  auto-invoke: "Installing, configuring, or using Figma MCP from setup through first canvas creation"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "WebFetch"
+    - "WebSearch"
+    - "Task"
+    - "SubAgent"
+---
 # Figma MCP 0-to-1 Guide
 
 ## When to Use

package/catalog/skills/frontend-design/SKILL.md

@@ -1,3 +1,20 @@
+---
+description: "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-05"
+  license: "Apache-2.0"
+  version: "1.1.0"
+  changelog: "v1.1.0: Added design-context-setter agent for greenfield/DESIGN.md workflow; added visual-refiner agent for post-generation quality evaluation; added motion-designer agent for stack-aware micro-interactions; added aesthetic-archetypes reference asset; expanded SKILL.md routing map with optional motion and refinement phases; upgraded component-designer with interaction states checklist and aesthetic principles"
+  auto-invoke: "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; adding motion or micro-interactions to existing UI; refining or polishing generated UI output"
+  allowed-tools:
+    - "Read"
+    - "Grep"
+    - "Glob"
+    - "Bash"
+    - "Edit"
+    - "Write"
+---
 # Frontend Design Guide
 
 ## When to Use

package/catalog/skills/output-optimizer/SKILL.md

@@ -1,3 +1,21 @@
+---
+description: "Optimize output token consumption through compact interpreter modes with controlled expansion when complexity, ambiguity, or risk requires more detail. Trigger: minimizing response verbosity while preserving clarity and correctness."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-07"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added a new portable output compression skill with deterministic interpreter modes and guarded detail expansion; reduces response token costs while preserving safety and clarity; affects response shaping workflows and catalog routing"
+  auto-invoke: "When minimizing output verbosity or selecting compact communication modes"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "Task"
+---
 # Output Optimizer Guide
 
 ## When to Use

package/catalog/skills/project-security/SKILL.md

@@ -1,3 +1,22 @@
+---
+description: "Scan project configuration and release surfaces for leak and security risks, and enforce security gates on commit, push, and publish workflows across GitHub, GitLab, npm, pnpm, yarn, and generic CI. Trigger: validating repository security posture, preventing secret leaks, or hardening delivery pipelines."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-07"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added portable project-security skill with commit/push/publish gating assets and CI templates; reduces secret leak and misconfiguration risk before delivery; affects catalog security workflow coverage and auto-invoke routing"
+  auto-invoke: "Scanning project configuration and delivery workflows for leaks or security issues before commit, push, or publish"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "Task"
+    - "SubAgent"
+---
 # Project Security Guide
 
 ## When to Use

package/catalog/skills/project-teacher/SKILL.md

@@ -1,3 +1,20 @@
+---
+description: "Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. Trigger: user asks to explain, understand, clarify, or learn about anything in the project or codebase."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-04"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Initial release of project-teacher skill; provides interactive, project-grounded teaching for any concept or code path; affects education and clarification workflows across all projects"
+  auto-invoke: "User needs to understand, explain, or learn about any aspect of the project or codebase"
+  allowed-tools:
+    - "Read"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "WebFetch"
+    - "WebSearch"
+---
 # Project Teacher Guide
 
 ## When to Use

package/catalog/skills/react-guidelines/SKILL.md

@@ -1,3 +1,24 @@
+---
+description: "Guide React code generation and review using latest stable React verification and modern framework best practices."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-04"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added new react-guidelines skill with component and testing sub-agent routing; improves React-specific generation and review consistency with latest-stable preflight checks; affects portable catalog skill discovery and React workflow guidance"
+  auto-invoke: "Generating, reviewing, or refactoring React code artifacts in React projects"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "WebFetch"
+    - "WebSearch"
+    - "Task"
+    - "SubAgent"
+---
 # React Guidelines
 
 ## When to Use

package/catalog/skills/review-rangers/SKILL.md

@@ -1,3 +1,20 @@
+---
+description: "Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-04"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added multi-perspective review skill with committee + safety guard synthesis; enables adversarial evaluation without permanent agent files; affects catalog skill coverage for review and quality workflows"
+  auto-invoke: "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value"
+  allowed-tools:
+    - "Read"
+    - "Grep"
+    - "Glob"
+    - "Bash"
+    - "Task"
+    - "SubAgent"
+---
 # Review Rangers Guide
 
 ## When to Use

package/catalog/skills/skill-creator/SKILL.md

@@ -1,3 +1,24 @@
+---
+description: "Create and standardize AI skills with reusable structure, metadata rules, and templates."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-03-27"
+  license: "Apache-2.0"
+  version: "1.2.3"
+  changelog: "Metadata updated to ensure compliance with current standards; maintains skill integrity and version tracking; affects metadata section"
+  auto-invoke: "Creating a new skill"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "WebFetch"
+    - "WebSearch"
+    - "Task"
+    - "SubAgent"
+---
 # Skill Creator Guide
 
 ## When to Create a Skill
@@ -87,6 +108,17 @@ Generic skill needs {product-name} info?   -> Add references/ pointing to {produ
 | `skillMetadata.allowed-tools` | Yes | String list | All tools this skill can invoke (e.g., `Read`, `Edit`, `Write`, `SubAgent`) |
 | `skillMetadata.allowed-modes` | Optional | String list | Use only when skill has an `agents/` folder |
 
+### SKILL.md Frontmatter Mirroring
+
+Top-level `SKILL.md` files now include managed YAML frontmatter mirrored from `manifest.json`.
+
+Rules:
+
+- `manifest.json` is the single source of truth.
+- Mirror only `description` and `skillMetadata.{author,last-edit,license,version,changelog,auto-invoke,allowed-tools}`.
+- Do not manually edit mirrored frontmatter in `SKILL.md`; run sync automation instead.
+- Keep instruction body content in `SKILL.md` focused on workflow guidance.
+
 ---
 
 ## Metadata Standards
@@ -153,6 +185,7 @@ Do not:
 - Use web URLs in references.
 - Leave `changelog` empty or informal.
 - Use non-ISO date formats.
+- Manually drift `SKILL.md` frontmatter away from `manifest.json`.
 
 ---
 
@@ -167,6 +200,7 @@ Do not:
 - [ ] `changelog` uses structured format: `what; why; where`.
 - [ ] `allowed-modes` is present only when `agents/` exists.
 - [ ] `allowed-tools` matches actual tool usage.
+- [ ] `SKILL.md` frontmatter is synced from `manifest.json`.
 - [ ] Critical patterns are clear and concise.
 - [ ] Code examples are minimal and focused.
 - [ ] Commands section exists with copy-paste commands.

package/catalog/skills/skill-creator/assets/SKILL-TEMPLATE.md

@@ -1,5 +1,10 @@
 # {Name of the Skill} Guide
 
+<!--
+Managed frontmatter is mirrored from manifest.json by automation.
+Do not hand-author frontmatter in this template.
+-->
+
 ## When to Use
 
 Use this skill when:
@@ -74,3 +79,4 @@ Otherwise     -> {Default action}
 
 - Template assets: Place reusable templates, schemas, and examples in `assets/`.
 - Define metadata in `manifest.json` (`id`, `description`, `skillMetadata`, `allowed-tools`, optional `allowed-modes`).
+- Run skill frontmatter sync so top-level `SKILL.md` mirrors manifest metadata.

package/catalog/skills/spec-driven-development/SKILL.md

@@ -1,3 +1,22 @@
+---
+description: "Plan, execute, and verify multi-step work through versioned specs with small, testable tasks."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-03"
+  license: "Apache-2.0"
+  version: "1.0.3"
+  changelog: "Added OpenSpec complementary support routing guidance to spec-driven-development instructions; improves planning continuity and review clarity when local SDD needs reinforcement; affects spec-driven-development SKILL guidance and manifest metadata"
+  auto-invoke: "Planning or executing feature work, bug fixes, and multi-phase implementation"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "Task"
+    - "SubAgent"
+---
 # Spec-Driven Development Guide
 
 ## When to Use
@@ -22,7 +41,7 @@ Do not use this skill for:
 1. Define the spec in `.sdd/active/<feature-name>/spec.md`.
 2. Review and refine scope, constraints, and tasks.
 3. Execute one small task at a time.
-4. Verify each task and the end-to-end outcome.
+4. Verify each task and the end-to-end outcome, ending with a required `review-rangers` final gate.
 5. Archive to `.sdd/archive/` when complete.
 
 Recommended task size:

package/catalog/skills/spec-driven-development/agents/orchestrate.md

@@ -14,7 +14,7 @@ Coordinate planning, implementation, and verification through explicit checkpoin
 1. PLAN: Produce or update the spec.
 2. REVIEW CHECKPOINT: Confirm the plan is approved.
 3. APPLY: Execute agreed task batch.
-4. VERIFY CHECKPOINT: Validate outputs against the spec.
+4. VERIFY CHECKPOINT: Validate outputs against the spec and run the required final `review-rangers` gate.
 5. REPEAT: Continue by phase or task batch.
 6. ARCHIVE: Move completed work from `.sdd/active/` to `.sdd/archive/`.
 

package/catalog/skills/spec-driven-development/agents/verify.md

@@ -15,7 +15,15 @@ Validate that implementation matches the approved spec and passes quality checks
 2. Run task-level verification evidence checks.
 3. Run feature-level validation commands.
 4. Confirm constraints (`MUST`, `MUST NOT`) were respected.
-5. Report pass/fail per area with concrete evidence.
+5. Run a final structured `review-rangers` pass over the full change set.
+6. Report pass/fail per area with concrete evidence.
+
+### Required Final Gate (`review-rangers`)
+
+- Validate selected agent targets vs actual instruction files/symlinks written.
+- Validate stale managed target cleanup after re-install/reselection.
+- Validate backup and restore safety (including uninstall restore behavior).
+- Any unresolved `review-rangers` blocker keeps verification in failed state.
 
 ## Quality Bar
 

package/catalog/skills/spec-driven-development/assets/validation-checklist.md

@@ -28,5 +28,6 @@ Use this checklist before implementation and again before archive.
 - [ ] All planned tasks are complete.
 - [ ] Feature-level validation passes.
 - [ ] Constraints were respected.
+- [ ] Final `review-rangers` gate completed with no unresolved blockers.
 - [ ] No unintended scope creep.
 - [ ] Work is moved from `.sdd/active/` to `.sdd/archive/`.

package/catalog/skills/test-driven-development/SKILL.md

@@ -1,3 +1,20 @@
+---
+description: "Guide implementation using the RED → GREEN → REFACTOR TDD cycle: write a failing test first, write the minimum code to pass, then refactor while tests stay green."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-04"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Initial TDD skill ported from legacy scannlab-sdd tdd-templates; enables RED→GREEN→REFACTOR workflow across any stack; affects catalog skill coverage for test-first development"
+  auto-invoke: "Implementing features, services, or components using test-driven development (TDD) or RED→GREEN→REFACTOR cycles"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+---
 # Test-Driven Development Guide
 
 ## When to Use

package/catalog/skills/token-optimizer/SKILL.md

@@ -1,3 +1,21 @@
+---
+description: "Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-03"
+  license: "Apache-2.0"
+  version: "1.0.3"
+  changelog: "Migrated token-optimizer into portable catalog format with curated model-agnostic guidance; improves default reasoning and token-efficiency behavior across installs; affects skill discovery, auto-invoke routing, and install baseline"
+  auto-invoke: "Classifying task complexity and choosing reasoning depth/token budget"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "Task"
+---
 # Token Optimizer Guide
 
 ## When to Use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {
@@ -26,9 +26,9 @@
   "scripts": {
     "build": "node ./scripts/build-catalog-index.mjs",
     "catalog:check": "node ./scripts/check-catalog.mjs",
-    "catalog:sync": "node ./scripts/sync-catalog-readme.mjs",
+    "catalog:sync": "node ./scripts/sync-catalog.mjs",
     "agentic:self:sync": "node ./scripts/sync-self-agentic.mjs",
-    "test": "node --test tests/*.test.js",
+    "test": "node --test tests/*.test.js && node ./scripts/test-in-sandbox.mjs",
     "security:check": "node ./scripts/security-check.mjs",
     "verify:packlist": "node ./scripts/verify-packlist.mjs",
     "verify:versions": "node ./scripts/verify-versions.mjs",

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "private": true,
   "type": "module"
 }

package/packages/catalog/src/index.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -21,6 +21,16 @@ const REQUIRED_FIELDS = [
   "dependencies"
 ];
 
+const MIRRORED_SKILL_METADATA_KEYS = [
+  "author",
+  "last-edit",
+  "license",
+  "version",
+  "changelog",
+  "auto-invoke",
+  "allowed-tools"
+];
+
 export function getCatalogRoot() {
   return catalogDir;
 }
@@ -70,9 +80,372 @@ export function validateSkillManifest(manifest) {
     throw new Error(`Skill "${manifest.id}" must declare files`);
   }
 
+  const hasSkillInstruction = manifest.files.some((file) => file.path === "SKILL.md" && file.kind === "instruction");
+  if (!hasSkillInstruction) {
+    throw new Error(`Skill "${manifest.id}" must include files entry for SKILL.md as instruction`);
+  }
+
+  assertFrontmatterFields(manifest);
+
   return true;
 }
 
+function toLf(text) {
+  return text.replaceAll("\r\n", "\n");
+}
+
+function splitLinesWithOffsets(text) {
+  const lines = [];
+  let start = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") {
+      lines.push({
+        text: text.slice(start, index),
+        start,
+        end: index + 1
+      });
+      start = index + 1;
+    }
+  }
+  if (start < text.length) {
+    lines.push({
+      text: text.slice(start),
+      start,
+      end: text.length
+    });
+  } else if (text.length === 0) {
+    lines.push({ text: "", start: 0, end: 0 });
+  }
+  return lines;
+}
+
+function yamlQuote(value) {
+  return JSON.stringify(String(value));
+}
+
+function assertFrontmatterFields(manifest) {
+  if (!manifest || typeof manifest !== "object") {
+    throw new Error("Invalid manifest while building SKILL.md frontmatter");
+  }
+
+  if (typeof manifest.description !== "string" || manifest.description.length === 0) {
+    throw new Error(`Skill "${manifest.id}" is missing required manifest.description for frontmatter mirroring`);
+  }
+
+  if (!manifest.skillMetadata || typeof manifest.skillMetadata !== "object") {
+    throw new Error(`Skill "${manifest.id}" is missing required manifest.skillMetadata for frontmatter mirroring`);
+  }
+
+  for (const key of MIRRORED_SKILL_METADATA_KEYS) {
+    if (!(key in manifest.skillMetadata)) {
+      throw new Error(`Skill "${manifest.id}" is missing required skillMetadata.${key} for frontmatter mirroring`);
+    }
+  }
+
+  const scalarKeys = ["author", "last-edit", "license", "version", "changelog", "auto-invoke"];
+  for (const key of scalarKeys) {
+    if (typeof manifest.skillMetadata[key] !== "string" || manifest.skillMetadata[key].trim().length === 0) {
+      throw new Error(`Skill "${manifest.id}" has invalid skillMetadata.${key}; expected a non-empty string`);
+    }
+  }
+
+  if (!Array.isArray(manifest.skillMetadata["allowed-tools"])) {
+    throw new Error(`Skill "${manifest.id}" must declare skillMetadata.allowed-tools as an array`);
+  }
+
+  for (const tool of manifest.skillMetadata["allowed-tools"]) {
+    if (typeof tool !== "string" || tool.trim().length === 0) {
+      throw new Error(`Skill "${manifest.id}" has invalid skillMetadata.allowed-tools; expected non-empty strings`);
+    }
+  }
+}
+
+export function buildSkillFrontmatterPayload(manifest) {
+  assertFrontmatterFields(manifest);
+  return {
+    description: manifest.description,
+    skillMetadata: {
+      author: manifest.skillMetadata.author,
+      "last-edit": manifest.skillMetadata["last-edit"],
+      license: manifest.skillMetadata.license,
+      version: manifest.skillMetadata.version,
+      changelog: manifest.skillMetadata.changelog,
+      "auto-invoke": manifest.skillMetadata["auto-invoke"],
+      "allowed-tools": [...manifest.skillMetadata["allowed-tools"]]
+    }
+  };
+}
+
+function renderSkillFrontmatterInner(payload) {
+  const lines = [
+    `description: ${yamlQuote(payload.description)}`,
+    "skillMetadata:",
+    `  author: ${yamlQuote(payload.skillMetadata.author)}`,
+    `  last-edit: ${yamlQuote(payload.skillMetadata["last-edit"])}`,
+    `  license: ${yamlQuote(payload.skillMetadata.license)}`,
+    `  version: ${yamlQuote(payload.skillMetadata.version)}`,
+    `  changelog: ${yamlQuote(payload.skillMetadata.changelog)}`,
+    `  auto-invoke: ${yamlQuote(payload.skillMetadata["auto-invoke"])}`,
+    "  allowed-tools:"
+  ];
+
+  for (const tool of payload.skillMetadata["allowed-tools"]) {
+    lines.push(`    - ${yamlQuote(tool)}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function renderSkillFrontmatter(manifest) {
+  const payload = buildSkillFrontmatterPayload(manifest);
+  return `---\n${renderSkillFrontmatterInner(payload)}\n---\n`;
+}
+
+export function splitSkillMarkdown(content) {
+  const normalized = toLf(content);
+  const source = normalized.startsWith("\uFEFF") ? normalized.slice(1) : normalized;
+  const lines = splitLinesWithOffsets(source);
+  const mirroredKeys = new Set([
+    "description",
+    "skillMetadata",
+    "author",
+    "last-edit",
+    "license",
+    "version",
+    "changelog",
+    "auto-invoke",
+    "allowed-tools"
+  ]);
+  const isYamlLike = (line) => (
+    line.trim().length === 0 ||
+    /^\s*[A-Za-z0-9_-]+:(?:\s.*)?$/.test(line) ||
+    /^\s*-\s+.*$/.test(line)
+  );
+
+  let firstNonBlankIndex = 0;
+  while (firstNonBlankIndex < lines.length && lines[firstNonBlankIndex].text.trim().length === 0) {
+    firstNonBlankIndex += 1;
+  }
+
+  if (firstNonBlankIndex >= lines.length || lines[firstNonBlankIndex].text !== "---") {
+    return {
+      hasFrontmatter: false,
+      malformedFrontmatter: false,
+      frontmatter: null,
+      body: source
+    };
+  }
+
+  const openLine = lines[firstNonBlankIndex];
+  let sawKeyValue = false;
+  let sawMirroredKey = false;
+  const detectedKeys = new Set();
+
+  for (let index = firstNonBlankIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index].text;
+    const nextLine = index + 1 < lines.length ? lines[index + 1].text : null;
+
+    if (
+      sawMirroredKey &&
+      line.trim().length === 0 &&
+      nextLine &&
+      /^(?:[-*+]\s+|\d+\.\s+|#{1,6}\s+|>\s+|```)/.test(nextLine)
+    ) {
+      return {
+        hasFrontmatter: true,
+        malformedFrontmatter: true,
+        frontmatter: null,
+        body: source.slice(lines[index + 1].start)
+      };
+    }
+
+    if (line === "---") {
+      if (!sawKeyValue || !sawMirroredKey) {
+        return {
+          hasFrontmatter: false,
+          malformedFrontmatter: false,
+          frontmatter: null,
+          body: source
+        };
+      }
+      const end = lines[index].end;
+      const frontmatter = source.slice(openLine.start, end);
+      return {
+        hasFrontmatter: true,
+        malformedFrontmatter: false,
+        frontmatter: frontmatter.endsWith("\n") ? frontmatter : `${frontmatter}\n`,
+        body: source.slice(end),
+        detectedKeys: Array.from(detectedKeys)
+      };
+    }
+
+    if (/^\s*[A-Za-z0-9_-]+:(?:\s.*)?$/.test(line)) {
+      sawKeyValue = true;
+      const key = line.split(":", 1)[0].trim();
+      detectedKeys.add(key);
+      if (mirroredKeys.has(key)) {
+        sawMirroredKey = true;
+      }
+    }
+
+    if (!isYamlLike(line)) {
+      if (!sawKeyValue || !sawMirroredKey) {
+        return {
+          hasFrontmatter: false,
+          malformedFrontmatter: false,
+          frontmatter: null,
+          body: source
+        };
+      }
+      return {
+        hasFrontmatter: true,
+        malformedFrontmatter: true,
+        frontmatter: null,
+        body: source.slice(lines[index].start),
+        detectedKeys: Array.from(detectedKeys)
+      };
+    }
+  }
+
+  if (!sawKeyValue) {
+    return {
+      hasFrontmatter: false,
+      malformedFrontmatter: false,
+      frontmatter: null,
+      body: source
+    };
+  }
+
+  if (!sawMirroredKey) {
+    return {
+      hasFrontmatter: false,
+      malformedFrontmatter: false,
+      frontmatter: null,
+      body: source
+    };
+  }
+
+  return {
+    hasFrontmatter: true,
+    malformedFrontmatter: true,
+    frontmatter: null,
+    body: "",
+    detectedKeys: Array.from(detectedKeys)
+  };
+}
+
+export function applyManifestFrontmatterToSkill(content, manifest) {
+  const expectedFrontmatter = renderSkillFrontmatter(manifest);
+  const parts = splitSkillMarkdown(content);
+  return `${expectedFrontmatter}${parts.body}`;
+}
+
+export function verifySkillFrontmatterContent(content, manifest) {
+  const expectedFrontmatter = renderSkillFrontmatter(manifest);
+  const parts = splitSkillMarkdown(content);
+  if (!parts.hasFrontmatter) {
+    return { ok: false, reason: "missing" };
+  }
+  if (parts.malformedFrontmatter || !parts.frontmatter) {
+    return { ok: false, reason: "malformed" };
+  }
+  if (parts.frontmatter !== expectedFrontmatter) {
+    return { ok: false, reason: "mismatch" };
+  }
+  const residual = splitSkillMarkdown(parts.body);
+  if (residual.hasFrontmatter && !residual.malformedFrontmatter && residual.frontmatter === expectedFrontmatter) {
+    return { ok: false, reason: "residual-frontmatter" };
+  }
+  return { ok: true, reason: null };
+}
+
+export async function syncSkillFrontmatter({ skillId, dryRun = false } = {}) {
+  const plan = await planSkillFrontmatterSync({ skillId });
+  if (!dryRun) {
+    await applyTextUpdatesAtomically(plan.updates);
+  }
+  return {
+    skillCount: plan.skillCount,
+    updatedSkillIds: plan.updatedSkillIds
+  };
+}
+
+export async function planSkillFrontmatterSync({ skillId } = {}) {
+  const allIds = await listSkillIds();
+  if (skillId && !allIds.includes(skillId)) {
+    throw new Error(`Unknown skill id: ${skillId}`);
+  }
+
+  const ids = skillId ? [skillId] : allIds;
+  const updatedSkillIds = [];
+  const updates = [];
+
+  for (const id of ids) {
+    const manifest = await loadSkillManifest(id);
+    const skillPath = path.join(skillsDir, id, "SKILL.md");
+    const current = await readFile(skillPath, "utf8");
+    const next = applyManifestFrontmatterToSkill(current, manifest);
+    if (next !== toLf(current)) {
+      updatedSkillIds.push(id);
+      updates.push({
+        skillId: id,
+        path: skillPath,
+        content: next
+      });
+    }
+  }
+
+  return {
+    skillCount: ids.length,
+    updatedSkillIds,
+    updates
+  };
+}
+
+export async function applyTextUpdatesAtomically(updates) {
+  const deduped = [];
+  const seenPaths = new Set();
+  for (let index = updates.length - 1; index >= 0; index -= 1) {
+    const update = updates[index];
+    if (!seenPaths.has(update.path)) {
+      seenPaths.add(update.path);
+      deduped.push(update);
+    }
+  }
+  deduped.reverse();
+
+  const originals = new Map();
+  for (const update of deduped) {
+    try {
+      originals.set(update.path, await readFile(update.path, "utf8"));
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        originals.set(update.path, null);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  const writtenPaths = [];
+  try {
+    for (const update of deduped) {
+      await writeFile(update.path, update.content, "utf8");
+      writtenPaths.push(update.path);
+    }
+  } catch (error) {
+    for (const targetPath of writtenPaths.reverse()) {
+      const original = originals.get(targetPath);
+      if (original === null) {
+        await rm(targetPath, { force: true });
+      } else {
+        await writeFile(targetPath, original, "utf8");
+      }
+    }
+    throw error;
+  }
+}
+
 export async function copySkillTo(targetCatalogDir, skillId) {
   const source = path.join(skillsDir, skillId);
   const destination = path.join(targetCatalogDir, skillId);
@@ -88,6 +461,7 @@ export async function readTemplate(templateName) {
 }
 
 export function renderAgentsMarkdown({ skills, detections, generatedAt, projectName }) {
+  const escapeTableCell = (value) => String(value).replaceAll("|", "\\|").replaceAll("\n", "<br>");
   const sortedSkills = [...skills].sort((a, b) => a.id.localeCompare(b.id));
   const sortedDetections = [...detections].sort((a, b) => a.technology.localeCompare(b.technology));
   const autoInvokeSkills = sortedSkills.filter((skill) => skill.skillMetadata?.["auto-invoke"]);
@@ -114,7 +488,7 @@ export function renderAgentsMarkdown({ skills, detections, generatedAt, projectN
   ];
 
   for (const skill of sortedSkills) {
-    lines.push(`| \`${skill.id}\` | ${skill.description} | ${skill.tags.join(", ")} |`);
+    lines.push(`| \`${skill.id}\` | ${escapeTableCell(skill.description)} | ${escapeTableCell(skill.tags.join(", "))} |`);
   }
 
   lines.push(
@@ -126,7 +500,7 @@ export function renderAgentsMarkdown({ skills, detections, generatedAt, projectN
     "1. Always run `token-optimizer` first to classify complexity and set the minimum viable reasoning depth.",
     "2. Always run `output-optimizer` immediately after `token-optimizer` for response-shape control.",
     "3. `output-optimizer` mode policy:",
-    "   - Default: select a random canonical mode for each new interaction.",
+    "   - Default: use `step-brief` when there is no explicit mode or strong phrasing signal.",
     "   - Override: if user explicitly requests a mode (for example `mode: step-brief`), that explicit mode wins.",
     "   - Persistence: keep the explicitly requested mode active until the user asks for a different mode.",
     "",
@@ -154,7 +528,7 @@ export function renderAgentsMarkdown({ skills, detections, generatedAt, projectN
   } else {
     lines.push("| Action | Skill |", "| ------ | ----- |");
     for (const skill of autoInvokeSkills) {
-      lines.push(`| ${skill.skillMetadata["auto-invoke"]} | \`${skill.id}\` |`);
+      lines.push(`| ${escapeTableCell(skill.skillMetadata["auto-invoke"])} | \`${skill.id}\` |`);
     }
   }
 
@@ -230,6 +604,28 @@ export async function verifyCatalogFiles() {
         issues.push(`Missing file for ${skillId}: ${file.path}`);
       }
     }
+
+    const skillDocPath = path.join(skillPath, "SKILL.md");
+    let skillDocContent;
+    try {
+      skillDocContent = await readFile(skillDocPath, "utf8");
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        // Missing file is already surfaced above via manifest file verification.
+        continue;
+      }
+      issues.push(`Cannot read ${skillId}/SKILL.md: ${error.message}`);
+      continue;
+    }
+
+    try {
+      const status = verifySkillFrontmatterContent(skillDocContent, manifest);
+      if (!status.ok) {
+        issues.push(`Frontmatter ${status.reason} for ${skillId}: SKILL.md`);
+      }
+    } catch (error) {
+      issues.push(`Frontmatter validation failed for ${skillId}: ${error.message}`);
+    }
   }
 
   return issues;

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "private": true,
   "type": "module",
   "bin": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "private": true,
   "type": "module"
 }

package/packages/core/src/index.js

@@ -175,7 +175,11 @@ async function ensureManagedTextFile(targetPath, content, backupsDir, lockData)
       return;
     }
 
-    await backupPathIfNeeded(targetPath, backupsDir, lockData);
+    // Do not back up previously managed content; backups are for restoring
+    // user-authored files replaced by managed files.
+    if (!current.includes(MANAGED_MARKER)) {
+      await backupPathIfNeeded(targetPath, backupsDir, lockData);
+    }
   }
 
   await mkdir(path.dirname(targetPath), { recursive: true });
@@ -230,6 +234,69 @@ function buildInstallTargets(selectedAgents) {
   };
 }
 
+async function reconcileManagedTargets({
+  previousLock,
+  selectedInstructionTargets,
+  selectedSkillTargets,
+  lockData
+}) {
+  if (!previousLock) {
+    return;
+  }
+
+  const selectedInstructions = new Set(selectedInstructionTargets);
+  const selectedSkills = new Set(selectedSkillTargets);
+  const selectedTargets = new Set([...selectedInstructions, ...selectedSkills]);
+  const previousBackups = previousLock.backups || {};
+
+  for (const [targetPath, backupPath] of Object.entries(previousBackups)) {
+    if (!selectedTargets.has(targetPath)) {
+      continue;
+    }
+    if (await exists(backupPath)) {
+      lockData.backups[targetPath] = backupPath;
+    }
+  }
+
+  for (const symlinkPath of previousLock.managedSymlinks || []) {
+    if (selectedSkills.has(symlinkPath)) {
+      continue;
+    }
+
+    if (await exists(symlinkPath)) {
+      await rm(symlinkPath, { recursive: true, force: true });
+    }
+
+    const backupPath = previousBackups[symlinkPath];
+    if (backupPath && await exists(backupPath)) {
+      await mkdir(path.dirname(symlinkPath), { recursive: true });
+      await cp(backupPath, symlinkPath, { recursive: true, force: true });
+    }
+  }
+
+  for (const filePath of previousLock.managedFiles || []) {
+    if (selectedInstructions.has(filePath)) {
+      continue;
+    }
+
+    const backupPath = previousBackups[filePath];
+    if (backupPath && await exists(backupPath)) {
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await cp(backupPath, filePath, { recursive: true, force: true });
+      continue;
+    }
+
+    if (!(await exists(filePath))) {
+      continue;
+    }
+
+    const content = await readFile(filePath, "utf8");
+    if (content.includes(MANAGED_MARKER)) {
+      await rm(filePath, { force: true });
+    }
+  }
+}
+
 export async function installProject({
   cwd,
   agents,
@@ -259,6 +326,7 @@ export async function installProject({
   const targetCatalogDir = path.join(installRoot, "catalog");
   const backupsDir = path.join(installRoot, "backups");
   const lockPath = path.join(installRoot, "manifest.lock.json");
+  const previousLock = await exists(lockPath) ? await readJson(lockPath) : null;
   const lockData = {
     version: 1,
     generatedAt: plan.generatedAt,
@@ -289,15 +357,24 @@ export async function installProject({
   await writeFile(path.join(installRoot, "AGENTS.md"), agentsMarkdown, "utf8");
 
   const { instructionTargets, skillTargets } = buildInstallTargets(selectedAgents);
+  const absoluteInstructionTargets = instructionTargets.map((pathParts) => path.join(cwd, ...pathParts));
+  const absoluteSkillTargets = skillTargets.map((pathParts) => path.join(cwd, ...pathParts));
+
+  await reconcileManagedTargets({
+    previousLock,
+    selectedInstructionTargets: absoluteInstructionTargets,
+    selectedSkillTargets: absoluteSkillTargets,
+    lockData
+  });
 
-  for (const pathParts of instructionTargets) {
-    await ensureManagedTextFile(path.join(cwd, ...pathParts), agentsMarkdown, backupsDir, lockData);
+  for (const targetPath of absoluteInstructionTargets) {
+    await ensureManagedTextFile(targetPath, agentsMarkdown, backupsDir, lockData);
   }
 
   const skillsSourcePath = path.join(installRoot, "catalog");
 
-  for (const pathParts of skillTargets) {
-    await ensureSymlink(path.join(cwd, ...pathParts), skillsSourcePath, backupsDir, lockData);
+  for (const targetPath of absoluteSkillTargets) {
+    await ensureSymlink(targetPath, skillsSourcePath, backupsDir, lockData);
   }
 
   await writeJson(lockPath, lockData);

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "private": true,
   "type": "module"
 }