@skilly-hand/skilly-hand 0.23.2 → 0.24.0

package/CHANGELOG.md

@@ -16,6 +16,38 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.24.0] - 2026-04-26
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.24.0)
+
+### Added
+- Added install-time creation of the user-owned `.ai/DECISIONS.md` decisions registry, including entry criteria, an entry template, and a required registry changelog section.
+- Added CLI install output that reports the `.ai/DECISIONS.md` decisions registry status during dry runs and applied installs.
+- Added regression coverage for decisions registry planning, creation, existing-registry preservation, uninstall preservation, and invalid `.ai` parent handling.
+
+### Changed
+- Updated `review-rangers` to own decisions registry read/write guidance and bumped the skill metadata version to `1.1.0`.
+
+### Fixed
+- Preserved existing user-owned decisions registry content across reinstalls and uninstalls.
+
+### Removed
+- _None._
+
+## [0.23.3] - 2026-04-20
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.23.3)
+
+### Added
+- Mirrored each skill `manifest.id` into top-level `name` frontmatter across catalog `SKILL.md` files.
+
+### Changed
+- Updated catalog frontmatter rendering to include `name` and require a non-empty `manifest.id` during frontmatter validation.
+
+### Fixed
+- Expanded frontmatter sync tests to catch stale or missing `name` metadata regressions and enforce manifest id requirements.
+
+### Removed
+- _None._
+
 ## [0.23.2] - 2026-04-13
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.23.2)
 

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

@@ -1,4 +1,5 @@
 ---
+name: "accessibility-audit"
 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"

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

@@ -1,4 +1,5 @@
 ---
+name: "agents-root-orchestrator"
 description: "Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly."
 skillMetadata:
   author: "skilly-hand"

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

@@ -1,4 +1,5 @@
 ---
+name: "angular-guidelines"
 description: "Guide Angular code generation and review using latest stable Angular verification and modern framework best practices."
 skillMetadata:
   author: "skilly-hand"

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

@@ -1,4 +1,5 @@
 ---
+name: "figma-mcp-0to1"
 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"

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

@@ -1,4 +1,5 @@
 ---
+name: "frontend-design"
 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"

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

@@ -1,4 +1,5 @@
 ---
+name: "output-optimizer"
 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"

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

@@ -1,4 +1,5 @@
 ---
+name: "project-security"
 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"

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

@@ -1,4 +1,5 @@
 ---
+name: "project-teacher"
 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"

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

@@ -1,4 +1,5 @@
 ---
+name: "react-guidelines"
 description: "Guide React code generation and review using latest stable React verification and modern framework best practices."
 skillMetadata:
   author: "skilly-hand"

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

@@ -1,14 +1,17 @@
 ---
+name: "review-rangers"
 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"
+  last-edit: "2026-04-26"
   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"
+  version: "1.1.0"
+  changelog: "Added DECISIONS.md registry ownership guidance; preserves durable review insights and anti-slop decisions across sessions; affects review-rangers workflow, install scaffolding, and project memory usage"
   auto-invoke: "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value"
   allowed-tools:
     - "Read"
+    - "Edit"
+    - "Write"
     - "Grep"
     - "Glob"
     - "Bash"
@@ -37,14 +40,16 @@ Do not use this skill for:
 ## Core Workflow
 
 1. Identify the target (code, decision, artifact) and its domain.
-2. Determine committee size: 3 members for routine reviews, 5 for high-risk or cross-domain targets.
-3. Spawn N committee members using `assets/committee-member-template.md`. Assign each a distinct evaluation lens. Run them independently — no member sees another's output.
-4. Determine the expert domain for the safety guard.
-5. Spawn 1 safety guard using `assets/safety-guard-template.md`. It evaluates the target from an authoritative expert position.
-6. Run the committee and safety guard in parallel.
-7. Collect all outputs.
-8. Synthesize a structured verdict following the Synthesis Rules.
-9. Emit the final verdict with confidence tier, top findings, and recommended action.
+2. Read `.ai/DECISIONS.md` if it exists. Treat it as project memory for avoiding repeated mistakes and reusing documented decisions.
+3. Determine committee size: 3 members for routine reviews, 5 for high-risk or cross-domain targets.
+4. Spawn N committee members using `assets/committee-member-template.md`. Assign each a distinct evaluation lens. Run them independently — no member sees another's output.
+5. Determine the expert domain for the safety guard.
+6. Spawn 1 safety guard using `assets/safety-guard-template.md`. It evaluates the target from an authoritative expert position.
+7. Run the committee and safety guard in parallel.
+8. Collect all outputs.
+9. Synthesize a structured verdict following the Synthesis Rules.
+10. Emit the final verdict with confidence tier, top findings, and recommended action.
+11. Decide whether any insight qualifies for `.ai/DECISIONS.md`; if yes, update the registry and its changelog in the same edit.
 
 ---
 
@@ -141,6 +146,56 @@ RECOMMENDED ACTION:
 
 ---
 
+## Decisions Registry Protocol
+
+`review-rangers` owns `.ai/DECISIONS.md` maintenance when the registry exists. Use it as both:
+
+- A documentary source before solving or reviewing relevant problems.
+- A durable memory target after review when a finding has future value.
+
+### Read Rules
+
+- Read `.ai/DECISIONS.md` near the start of relevant review or problem-solving work.
+- Apply documented decisions and "avoid repeating" notes as project constraints.
+- If the file does not exist, continue the review without creating it unless the current task is installation or explicit registry setup.
+
+### Write Criteria
+
+Write to `.ai/DECISIONS.md` only for:
+
+- Breaking changes.
+- Mid-interest or high-interest solutions.
+- Architectural decisions.
+- Repeated issue patterns.
+- Project-specific conventions likely to matter in future sessions.
+
+Do not write entries for minimal cleanup, obvious one-off bugs, insignificant changes, local-only implementation details, or full review transcripts.
+
+### Write Format
+
+Insert new entries above the final `## Changelog` section so the changelog remains the last section.
+
+```md
+## YYYY-MM-DD - Short Decision Title
+
+- Interest level: Mid | High | Breaking
+- Context:
+- Decision / Insight:
+- Rationale:
+- Avoid repeating:
+- Source:
+```
+
+Every change to `.ai/DECISIONS.md` must update `## Changelog` in the same edit.
+
+```md
+- YYYY-MM-DD: Created/updated entry "<title>" because <why>.
+```
+
+If the changelog section is missing, add it as the final section before making any other registry change.
+
+---
+
 ## Decision Tree
 
 ```text

package/catalog/skills/review-rangers/manifest.json

@@ -10,13 +10,15 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-04",
+    "last-edit": "2026-04-26",
     "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",
+    "version": "1.1.0",
+    "changelog": "Added DECISIONS.md registry ownership guidance; preserves durable review insights and anti-slop decisions across sessions; affects review-rangers workflow, install scaffolding, and project memory usage",
     "auto-invoke": "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value",
     "allowed-tools": [
       "Read",
+      "Edit",
+      "Write",
       "Grep",
       "Glob",
       "Bash",

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

@@ -1,4 +1,5 @@
 ---
+name: "skill-creator"
 description: "Create and standardize AI skills with reusable structure, metadata rules, and templates."
 skillMetadata:
   author: "skilly-hand"
@@ -115,7 +116,7 @@ Top-level `SKILL.md` files now include managed YAML frontmatter mirrored from `m
 Rules:
 
 - `manifest.json` is the single source of truth.
-- Mirror only `description` and `skillMetadata.{author,last-edit,license,version,changelog,auto-invoke,allowed-tools}`.
+- Mirror only `name` (from `manifest.id`), `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.
 

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

@@ -1,7 +1,7 @@
 # {Name of the Skill} Guide
 
 <!--
-Managed frontmatter is mirrored from manifest.json by automation.
+Managed frontmatter is mirrored from manifest.json by automation (`name` is derived from `manifest.id`).
 Do not hand-author frontmatter in this template.
 -->
 

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

@@ -1,4 +1,5 @@
 ---
+name: "spec-driven-development"
 description: "Plan, execute, and verify multi-step work through versioned specs with small, testable tasks."
 skillMetadata:
   author: "skilly-hand"

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

@@ -1,4 +1,5 @@
 ---
+name: "test-driven-development"
 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"

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

@@ -1,4 +1,5 @@
 ---
+name: "token-optimizer"
 description: "Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens."
 skillMetadata:
   author: "skilly-hand"

package/catalog/skills/user-story-crafting/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: "user-story-crafting"
 description: "Create and refine user stories with structured quality gates, splitting heuristics, and lightweight story mapping for release slicing. Trigger: writing, restructuring, splitting, or sequencing user stories for delivery-ready backlog work."
 skillMetadata:
   author: "skilly-hand"

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Davecelot/skilly-hand.git"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -18,7 +22,8 @@
     "SECURITY.md"
   ],
   "workspaces": [
-    "packages/*"
+    "packages/*",
+    "site"
   ],
   "engines": {
     "node": ">=22.0.0"
@@ -47,7 +52,10 @@
     "cli": "node ./packages/cli/src/bin.js",
     "detect": "node ./packages/cli/src/bin.js detect",
     "list": "node ./packages/cli/src/bin.js list",
-    "doctor": "node ./packages/cli/src/bin.js doctor"
+    "doctor": "node ./packages/cli/src/bin.js doctor",
+    "site:dev": "npm run dev -w @skilly-hand/site",
+    "site:build": "npm run build -w @skilly-hand/site",
+    "site:preview": "npm run preview -w @skilly-hand/site"
   },
   "dependencies": {
     "inquirer": "13.4.1"

package/packages/catalog/package.json

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

package/packages/catalog/src/index.js

@@ -128,6 +128,10 @@ function assertFrontmatterFields(manifest) {
     throw new Error("Invalid manifest while building SKILL.md frontmatter");
   }
 
+  if (typeof manifest.id !== "string" || manifest.id.trim().length === 0) {
+    throw new Error(`Skill "${manifest.id}" is missing required manifest.id for frontmatter mirroring`);
+  }
+
   if (typeof manifest.description !== "string" || manifest.description.length === 0) {
     throw new Error(`Skill "${manifest.id}" is missing required manifest.description for frontmatter mirroring`);
   }
@@ -163,6 +167,7 @@ function assertFrontmatterFields(manifest) {
 export function buildSkillFrontmatterPayload(manifest) {
   assertFrontmatterFields(manifest);
   return {
+    name: manifest.id,
     description: manifest.description,
     skillMetadata: {
       author: manifest.skillMetadata.author,
@@ -178,6 +183,7 @@ export function buildSkillFrontmatterPayload(manifest) {
 
 function renderSkillFrontmatterInner(payload) {
   const lines = [
+    `name: ${yamlQuote(payload.name)}`,
     `description: ${yamlQuote(payload.description)}`,
     "skillMetadata:",
     `  author: ${yamlQuote(payload.skillMetadata.author)}`,
@@ -206,6 +212,7 @@ export function splitSkillMarkdown(content) {
   const source = normalized.startsWith("\uFEFF") ? normalized.slice(1) : normalized;
   const lines = splitLinesWithOffsets(source);
   const mirroredKeys = new Set([
+    "name",
     "description",
     "skillMetadata",
     "author",

package/packages/cli/package.json

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

package/packages/cli/src/bin.js

@@ -131,11 +131,24 @@ function buildHelpText(renderer, appVersion) {
 
 function buildInstallResultDoc(result, flags, detectionGridText = "") {
   const mode = flags.dryRun ? "dry-run" : "apply";
+  const decisionsRegistry = result.plan.decisionsRegistry || {
+    relativePath: ".ai/DECISIONS.md",
+    exists: false,
+    willCreate: false
+  };
+  const decisionsRegistryStatus = decisionsRegistry.created
+    ? "created"
+    : decisionsRegistry.exists
+      ? "existing"
+      : decisionsRegistry.willCreate
+        ? "will create"
+        : "not reported";
   return createResultDoc("Install", [
     section("Install Preflight", [
       kvBlock([
         ["Project", result.plan.cwd],
         ["Install root", result.plan.installRoot],
+        ["Decisions registry", `${decisionsRegistry.relativePath} (${decisionsRegistryStatus})`],
         ["Agents", result.plan.agents.join(", ") || "none"],
         ["Include tags", flags.include.join(", ") || "none"],
         ["Exclude tags", flags.exclude.join(", ") || "none"],

package/packages/core/package.json

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

package/packages/core/src/index.js

@@ -6,6 +6,35 @@ import { detectProject, inspectProjectFiles } from "../../detectors/src/index.js
 export const DEFAULT_AGENTS = ["standard", "codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"];
 const MANAGED_MARKER = "<!-- Managed by skilly-hand.";
 const NATIVE_SETUP_MARKER = "<!-- Managed by skilly-hand native setup.";
+const DECISIONS_REGISTRY_RELATIVE_PATH = ".ai/DECISIONS.md";
+const DECISIONS_REGISTRY_TEMPLATE = `# AI Decisions
+
+Durable project memory for \`review-rangers\`. Use this file to record breaking changes, mid/high-interest solutions, and important review insights that future agents should reuse.
+
+## Entry Criteria
+
+- Add entries only for breaking changes, mid/high-interest solutions, architectural decisions, repeated issue patterns, or project-specific conventions with future value.
+- Do not add minimal, obvious, one-off, or insignificant changes.
+- Do not paste full review transcripts.
+- Every change to this file must update the changelog at the end.
+
+## Entry Template
+
+\`\`\`md
+## YYYY-MM-DD - Short Decision Title
+
+- Interest level: Mid | High | Breaking
+- Context:
+- Decision / Insight:
+- Rationale:
+- Avoid repeating:
+- Source:
+\`\`\`
+
+## Changelog
+
+- YYYY-MM-DD: Created/updated entry "<title>" because <why>.
+`;
 const AGENT_INSTALL_PROFILES = {
   standard: {
     instructionFiles: [["AGENTS.md"]],
@@ -263,10 +292,60 @@ export function buildInstallPlan({ cwd, detections, skills, agents }) {
       tags: skill.tags
     })),
     installRoot: path.join(cwd, ".skilly-hand"),
+    decisionsRegistry: {
+      path: path.join(cwd, ".ai", "DECISIONS.md"),
+      relativePath: DECISIONS_REGISTRY_RELATIVE_PATH,
+      exists: false,
+      willCreate: true
+    },
     generatedAt: nowIso()
   };
 }
 
+async function planDecisionsRegistry(cwd) {
+  const aiDir = path.join(cwd, ".ai");
+  const registryPath = path.join(cwd, ".ai", "DECISIONS.md");
+
+  if (await exists(aiDir)) {
+    const info = await lstat(aiDir);
+    if (!info.isDirectory()) {
+      throw new Error("Cannot create decisions registry because .ai exists and is not a directory.");
+    }
+  }
+
+  let registryExists = false;
+  if (await exists(registryPath)) {
+    const info = await lstat(registryPath);
+    if (!info.isFile()) {
+      throw new Error("Cannot use decisions registry because .ai/DECISIONS.md exists and is not a file.");
+    }
+    registryExists = true;
+  }
+
+  return {
+    path: registryPath,
+    relativePath: DECISIONS_REGISTRY_RELATIVE_PATH,
+    exists: registryExists,
+    willCreate: !registryExists
+  };
+}
+
+async function ensureDecisionsRegistry(cwd) {
+  const registry = await planDecisionsRegistry(cwd);
+  if (registry.exists) {
+    return registry;
+  }
+
+  await mkdir(path.dirname(registry.path), { recursive: true });
+  await writeFile(registry.path, DECISIONS_REGISTRY_TEMPLATE, "utf8");
+  return {
+    ...registry,
+    exists: true,
+    willCreate: false,
+    created: true
+  };
+}
+
 async function backupPathIfNeeded(targetPath, backupsDir, lockData) {
   if (!(await exists(targetPath))) {
     return null;
@@ -600,6 +679,7 @@ export async function installProject({
         excludeTags: parseTags(excludeTags)
       });
   const plan = buildInstallPlan({ cwd, detections, skills, agents: selectedAgents });
+  plan.decisionsRegistry = await planDecisionsRegistry(cwd);
 
   if (dryRun) {
     return { plan, applied: false };
@@ -621,6 +701,8 @@ export async function installProject({
   await mkdir(installRoot, { recursive: true });
   await mkdir(targetCatalogDir, { recursive: true });
   await mkdir(backupsDir, { recursive: true });
+  const decisionsRegistry = await ensureDecisionsRegistry(cwd);
+  plan.decisionsRegistry = decisionsRegistry;
 
   for (const skill of skills) {
     await copySkillTo(targetCatalogDir, skill.id);

package/packages/detectors/package.json

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