@skilly-hand/skilly-hand 0.10.5 → 0.11.0

package/catalog/README.md

@@ -9,6 +9,7 @@ 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 |
+| `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 |

package/catalog/catalog-index.json

@@ -4,6 +4,7 @@
   "angular-guidelines",
   "figma-mcp-0to1",
   "frontend-design",
+  "project-teacher",
   "react-guidelines",
   "review-rangers",
   "skill-creator",

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/package.json

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