@skilly-hand/skilly-hand 0.10.4 → 0.11.0

package/CHANGELOG.md

@@ -16,6 +16,22 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.10.5] - 2026-04-04
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.10.5)
+
+### Added
+- _None._
+
+### Changed
+- Renamed portable skill `life-guard` to `review-rangers` across manifests, tests, docs, and AGENTS routing output.
+- Standardized skill instruction structure so metadata is defined in `manifest.json` (removed YAML front matter from `SKILL.md` files and updated skill-creator guidance/templates).
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.10.4] - 2026-04-04
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.10.4)
 
@@ -132,7 +148,7 @@ All notable changes to this project are documented in this file.
 
 ### Added
 - Added portable skill `frontend-design` for project-aware UI component design that enforces stack detection before any design work.
-- Added portable skill `life-guard` for multi-perspective code and decision review using a committee + domain expert safety guard pattern.
+- Added portable skill `review-rangers` for multi-perspective code and decision review using a committee + domain expert safety guard pattern.
 - Added portable skill `test-driven-development` for guiding the RED → GREEN → REFACTOR TDD cycle.
 
 ### Changed

package/README.md

@@ -73,7 +73,7 @@ The catalog currently includes:
 - `angular-guidelines`
 - `figma-mcp-0to1`
 - `frontend-design`
-- `life-guard`
+- `review-rangers`
 - `react-guidelines`
 - `skill-creator`
 - `spec-driven-development`

package/catalog/README.md

@@ -9,8 +9,9 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `angular-guidelines` | Guide Angular code generation and review using latest stable Angular verification and modern framework best practices. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
 | `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. | frontend, design, workflow, ui | all |
-| `life-guard` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, workflow, review, quality | all |
+| `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. | core, workflow, education | all |
 | `react-guidelines` | Guide React code generation and review using latest stable React verification and modern framework best practices. | react, frontend, workflow, best-practices | all |
+| `review-rangers` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, workflow, review, quality | all |
 | `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |
 | `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | core, workflow, planning | all |
 | `test-driven-development` | 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. | testing, workflow, quality, core | all |

package/catalog/catalog-index.json

@@ -4,8 +4,9 @@
   "angular-guidelines",
   "figma-mcp-0to1",
   "frontend-design",
-  "life-guard",
+  "project-teacher",
   "react-guidelines",
+  "review-rangers",
   "skill-creator",
   "spec-driven-development",
   "test-driven-development",

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

@@ -1,23 +1,3 @@
----
-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. Never invents design
-  decisions — reads the project first, confirms with the user, then designs.
-  Trigger: user asks to build, design, style, or update any UI component, page, or visual element in a frontend project.
-metadata:
-  author: skilly-hand
-  last-edit: 2026-04-04
-  license: Apache-2.0
-  version: "1.0.0"
-  changelog: "initial release; prevents AI slop design by enforcing project-aware stack detection before any design work; affects all frontend design and styling tasks"
-  auto-invoke: "design a component, create a UI, style this page, build a frontend, update the layout"
-allowed-tools: Read, Grep, Glob, Bash, Edit, Write
-allowed-modes:
-  - stack-detector      # Scan the project for tech stack, UI libs, CSS vars, and design tokens
-  - component-designer  # Design and implement components following the confirmed project stack
----
-
 # Frontend Design Guide
 
 ## When to Use

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

@@ -0,0 +1,143 @@
+# Project Teacher Guide
+
+## When to Use
+
+Use this skill when:
+
+- The user asks to explain, understand, or clarify anything — code, architecture, decisions, or concepts.
+- The user asks "what is", "why does", "how does", "what happens when", or similar questions.
+- Clarification is needed during an SDD planning session before writing a spec.
+- A concept needs to be broken down into simpler terms before implementation begins.
+- The user wants to understand the reasoning or history behind a decision in the codebase.
+
+Do not use this skill for:
+
+- Writing, generating, or modifying code.
+- Creating specs, plans, or implementation tasks.
+- Running tests or build commands.
+
+---
+
+## Core Teaching Loop
+
+Every explanation follows this 4-step loop:
+
+1. **Scan** — Read the relevant parts of the project before answering.
+2. **Clarify** — Ask 1–2 targeted questions to understand what the user already knows and what depth they need.
+3. **Explain** — Deliver the explanation using verified facts, citing file paths where relevant.
+4. **Check Understanding** — Ask if the explanation landed or if any part needs to go deeper.
+
+Never skip the Scan step. Never state something as fact without verifying it in the code first.
+
+---
+
+## Scan Protocol
+
+Before answering any question, scan the project:
+
+```text
+1. Identify the entry points (e.g., index.ts, main.ts, App.tsx, package.json).
+2. Find the files most relevant to the question (use Glob + Grep).
+3. Read the relevant sections — functions, imports, config, comments.
+4. Note the actual behavior, not assumed behavior.
+5. Only then compose the explanation.
+```
+
+Scan rules:
+
+- Never explain from memory alone; always verify against the current code.
+- If the answer requires understanding a dependency, read it or look it up.
+- If the codebase contradicts a general best practice, explain what the code actually does.
+
+---
+
+## Interaction Patterns
+
+Before explaining, ask 1–2 focused questions to calibrate:
+
+| Situation | Question to Ask |
+| --- | --- |
+| Unclear what level of detail is needed | "Would you like a quick overview or a deeper walkthrough?" |
+| Unclear what the user already knows | "Are you familiar with [concept X], or should I start from scratch?" |
+| Multiple possible angles | "Are you more interested in how it works internally or why it was designed this way?" |
+| SDD context | "Is this to clarify requirements before writing a spec, or to understand existing behavior?" |
+
+Rules:
+
+- Ask at most 2 questions before explaining — do not interrogate.
+- If the question is already crystal clear, skip directly to explanation.
+- After explaining, always close with: "Does this make sense, or would you like me to go deeper on any part?"
+
+---
+
+## Explanation Modes
+
+Choose the mode that fits the question and the user's answer to your calibration questions:
+
+| Mode | When to Use | Format |
+| --- | --- | --- |
+| **Quick Overview** | User wants orientation, not depth | 3–5 bullet points + 1 example |
+| **Deep Dive** | User wants to fully understand | Step-by-step prose + code references + file:line citations |
+| **Analogy** | Abstract or unfamiliar concept | Real-world comparison + 1 short code example |
+| **Trace-Through** | User wants to follow execution | Numbered steps tracing the code path from trigger to outcome |
+
+Mix modes when helpful — for example, start with an Analogy then transition to a Trace-Through for complex topics.
+
+---
+
+## Decision Tree
+
+```text
+What kind of question is this?
+
+  "What is X?" or "What does X do?"
+    -> Quick Overview or Deep Dive based on user preference
+
+  "Why does X work this way?" or "Why was X chosen?"
+    -> Deep Dive + cite relevant code comments, config, or git context if available
+
+  "How does X flow / execute / work internally?"
+    -> Trace-Through mode
+
+  "I don't understand X at all"
+    -> Analogy first, then offer a follow-up Trace-Through
+
+  Clarifying requirements before writing a spec?
+    -> Deep Dive focused on constraints and behavior; hand off to spec-driven-development when done
+```
+
+---
+
+## SDD Companion Rules
+
+When `project-teacher` is invoked during a `spec-driven-development` session:
+
+1. Pause the SDD workflow to answer the clarifying question.
+2. Use Deep Dive or Trace-Through — shallow answers during planning create bad specs.
+3. After explaining, summarize what was clarified in one sentence the user can paste directly into the spec's `Why` or `Constraints` section.
+4. Return control to the SDD workflow explicitly: "Ready to continue with the spec?"
+
+---
+
+## Quality Rules
+
+- **Only state verified facts.** If you haven't read the file, don't claim to know what it does.
+- **Cite sources.** Reference `file.ts:42` or `config/settings.json` when making specific claims.
+- **Separate fact from inference.** If you're reasoning about intent rather than reading it directly, say so: "Based on the code, it looks like..." vs. "The code does...".
+- **No hallucinated APIs.** If an external API or library behavior is in question, use WebFetch or WebSearch to verify before explaining.
+- **Keep it simple by default.** Use plain language first. Introduce jargon only when it adds precision, and always define it when you do.
+
+---
+
+## Commands
+
+```bash
+# Find entry points to scan
+ls package.json tsconfig.json src/index.* src/main.* src/App.*
+
+# Search for a concept across the project
+grep -r "conceptName" src/ --include="*.ts" -l
+
+# Read a specific file section
+cat -n src/path/to/file.ts | head -60
+```

package/catalog/skills/project-teacher/manifest.json

@@ -0,0 +1,24 @@
+{
+  "id": "project-teacher",
+  "title": "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.",
+  "portable": true,
+  "tags": ["core", "workflow", "education"],
+  "detectors": ["always"],
+  "detectionTriggers": ["always"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
+  "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"]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" }
+  ],
+  "dependencies": []
+}

package/catalog/skills/{life-guard → review-rangers}/SKILL.md

@@ -1,19 +1,4 @@
----
-name: life-guard
-description: >
-  Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict.
-  Trigger: Reviewing code, decisions, pull requests, APIs, architecture, or any artifact that benefits from adversarial multi-perspective evaluation.
-metadata:
-  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
----
-
-# Life-Guard Guide
+# Review Rangers Guide
 
 ## When to Use
 
@@ -166,10 +151,10 @@ Does committee majority agree the target is sound?
 
 ```bash
 # Reference committee member template when constructing agent prompts
-cat .skilly-hand/catalog/life-guard/assets/committee-member-template.md
+cat .skilly-hand/catalog/review-rangers/assets/committee-member-template.md
 
 # Reference safety guard template when constructing agent prompts
-cat .skilly-hand/catalog/life-guard/assets/safety-guard-template.md
+cat .skilly-hand/catalog/review-rangers/assets/safety-guard-template.md
 ```
 
 ---

package/catalog/skills/{life-guard → review-rangers}/manifest.json

@@ -1,6 +1,6 @@
 {
-  "id": "life-guard",
-  "title": "Life-Guard",
+  "id": "review-rangers",
+  "title": "Review Rangers",
   "description": "Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict.",
   "portable": true,
   "tags": ["core", "workflow", "review", "quality"],

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

@@ -72,20 +72,20 @@ Generic skill needs {product-name} info?   -> Add references/ pointing to {produ
 
 ---
 
-## Frontmatter Fields
+## Manifest Metadata Fields
 
 | Field | Required | Format | Description |
 |-------|----------|--------|-------------|
-| `name` | Yes | `lowercase-hyphens` | Skill identifier |
-| `description` | Yes | Block with trigger | What skill does plus explicit `Trigger: ...` clause for AI recognition |
-| `metadata.author` | Yes | String | Always `skilly-hand` |
-| `metadata.last-edit` | Yes | ISO 8601 date | Format: `YYYY-MM-DD` (e.g., `2026-03-21`) |
-| `metadata.license` | Yes | String | Always `Apache-2.0` for `skilly-hand` |
-| `metadata.version` | Yes | Semantic version | Format: `"X.Y.Z"` as string |
-| `metadata.changelog` | Yes | Structured text | Format: `"<what changed>; <why it matters>; <where it affects>"` |
-| `metadata.auto-invoke` | Yes | String | Explicit trigger condition (e.g., `"When auditing, reviewing, or validating an existing skill"`) |
-| `allowed-tools` | Yes | Comma-separated | All tools this skill can invoke (e.g., `Read, Edit, Write, SubAgent`) |
-| `allowed-modes` | Optional | YAML list | Use only when skill has an `agents/` folder |
+| `id` | Yes | `lowercase-hyphens` | Skill identifier |
+| `description` | Yes | String | What skill does plus explicit `Trigger: ...` clause for AI recognition |
+| `skillMetadata.author` | Yes | String | Always `skilly-hand` |
+| `skillMetadata.last-edit` | Yes | ISO 8601 date | Format: `YYYY-MM-DD` (e.g., `2026-03-21`) |
+| `skillMetadata.license` | Yes | String | Always `Apache-2.0` for `skilly-hand` |
+| `skillMetadata.version` | Yes | Semantic version | Format: `"X.Y.Z"` as string |
+| `skillMetadata.changelog` | Yes | Structured text | Format: `"<what changed>; <why it matters>; <where it affects>"` |
+| `skillMetadata.auto-invoke` | Yes | String | Explicit trigger condition (e.g., `"When auditing, reviewing, or validating an existing skill"`) |
+| `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 |
 
 ---
 
@@ -146,7 +146,7 @@ Do:
 
 Do not:
 
-- Add a Keywords section (agent searches frontmatter, not body).
+- Add a Keywords section (agent searches manifest metadata, not body).
 - Duplicate content from existing docs (reference instead).
 - Include lengthy explanations when a concise rule is enough.
 - Add troubleshooting sections when they are not essential.
@@ -161,7 +161,7 @@ Do not:
 - [ ] Skill does not already exist.
 - [ ] Pattern is reusable (not one-off).
 - [ ] Name follows conventions.
-- [ ] Frontmatter includes all required fields.
+- [ ] `manifest.json` includes all required metadata fields.
 - [ ] `description` includes explicit `Trigger: ...` clause.
 - [ ] `last-edit` uses ISO format (`YYYY-MM-DD`).
 - [ ] `changelog` uses structured format: `what; why; where`.

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

@@ -1,22 +1,3 @@
----
-name: {skill-name}
-description: >
-  {Brief description of what this skill enables}.
-  Trigger: {When the AI should load this skill - explicit trigger condition}.
-metadata:
-  author: skilly-hand
-  last-edit: {YYYY-MM-DD}
-  license: Apache-2.0
-  version: "1.0.0"
-  changelog: "{<what changed>; <why it matters>; <where it affects>}"
-  auto-invoke: "{Complete with a brief and specific phrase if the skill needs auto-invoke}"
-allowed-tools: {tool1, tool2, tool3}  # Examples: Read, Edit, Write, Bash, Grep, SubAgent, Task, WebFetch
-# IMPORTANT: Only include 'allowed-modes' if your skill has an agents/ folder with sub-agents.
-# If you don't have agents/, delete the lines below.
-allowed-modes:
-  - {mode-name}     # {Description of when this mode is used}
----
-
 # {Name of the Skill} Guide
 
 ## When to Use
@@ -92,3 +73,4 @@ Otherwise     -> {Default action}
 ## Resources
 
 - Template assets: Place reusable templates, schemas, and examples in `assets/`.
+- Define metadata in `manifest.json` (`id`, `description`, `skillMetadata`, `allowed-tools`, optional `allowed-modes`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {