@skilly-hand/skilly-hand 0.1.0

package/catalog/skills/skill-creator/manifest.json

@@ -0,0 +1,36 @@
+{
+  "id": "skill-creator",
+  "title": "Skill Creator",
+  "description": "Create and standardize AI skills with reusable structure, metadata rules, and templates.",
+  "portable": true,
+  "tags": ["core", "workflow", "authoring"],
+  "detectors": ["always"],
+  "detectionTriggers": ["always"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot"],
+  "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"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "assets/SKILL-TEMPLATE.md", "kind": "asset" }
+  ],
+  "dependencies": []
+}

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

@@ -0,0 +1,168 @@
+# Spec-Driven Development Guide
+
+## When to Use
+
+Use this skill when:
+
+- Work spans multiple commits or phases.
+- Requirements are easy to misinterpret without written constraints.
+- You need a repeatable plan that can be reviewed before coding.
+- Several contributors or sessions may touch the same feature.
+
+Do not use this skill for:
+
+- Trivial one-file edits.
+- Emergency fixes where immediate response matters more than process.
+- Tasks with no meaningful verification path.
+
+---
+
+## Core Workflow
+
+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.
+5. Archive to `.sdd/archive/` when complete.
+
+Recommended task size:
+
+- Up to 3 files per task.
+- Around 30 minutes of implementation effort.
+- Clear, concrete verify step.
+
+---
+
+## Spec Structure
+
+A practical spec includes:
+
+- `Why`: problem and urgency.
+- `What`: concrete deliverable.
+- `Constraints`: `MUST`, `MUST NOT`, out-of-scope boundaries.
+- `Current State`: relevant code context.
+- `Tasks`: small implementation units with verify steps.
+- `Validation`: full feature checks after all tasks.
+
+For existing features with behavior changes, use a delta format (`ADDED`, `MODIFIED`, `REMOVED`) instead of rewriting everything.
+
+---
+
+## When to Use Delta vs Full Spec
+
+| Use Full Spec | Use Delta Spec |
+| --- | --- |
+| New feature with no previous spec | Behavior change to an existing feature |
+| Greenfield implementation | Bug fix or requirement adjustment |
+| No requirement baseline exists | Existing requirements already exist |
+
+## Archive Behavior
+
+When archiving a delta spec, apply changes to the base specification:
+
+- `ADDED`: append new requirements.
+- `MODIFIED`: replace the previous requirement text.
+- `REMOVED`: delete the requirement and keep a short reason in commit history.
+
+Then move work from `.sdd/active/<feature-name>/` to `.sdd/archive/<feature-name>/`.
+
+## Task Design Principles
+
+- Keep task scope small: if a task touches more than 3 files or needs more than about 30 minutes, split it.
+- Keep verification fast: each task should be verifiable in 2 minutes or less.
+- Keep completion explicit: each task must have a one-sentence definition of done.
+
+## Decision Tree: When to Break Tasks Smaller
+
+```text
+Does the task touch > 3 files?
+  YES -> split it
+
+Will the task take > 30 minutes?
+  YES -> split it
+
+Can the task be verified in <= 2 minutes?
+  NO -> add a tighter verify step
+
+Can "done" be described in one sentence?
+  NO -> task is too vague; split it
+```
+
+## Common Mistakes to Avoid
+
+### 1) Vague Constraints
+
+```text
+WRONG:
+Must use best practices.
+
+RIGHT:
+MUST use existing auth middleware.
+MUST NOT add new runtime dependencies.
+```
+
+### 2) Oversized Tasks
+
+```text
+WRONG:
+T1: Build the whole authentication feature.
+
+RIGHT:
+T1: Add token verification middleware.
+T2: Add login endpoint behavior.
+T3: Add integration test for login flow.
+```
+
+### 3) Missing Verification
+
+```text
+WRONG:
+Verify: It works.
+
+RIGHT:
+Verify: npm test -- src/auth/login.test.ts
+```
+
+### 4) Mixed Concerns in One Task
+
+```text
+WRONG:
+T1: Create component and migrate all pages to it.
+
+RIGHT:
+T1: Create component.
+T2: Migrate page A.
+T3: Migrate page B.
+```
+
+Use the full preflight and pre-archive checks in [assets/validation-checklist.md](assets/validation-checklist.md).
+
+---
+
+## Modes
+
+Use these mode guides for role-focused execution:
+
+- Planning mode: [agents/plan.md](agents/plan.md)
+- Implementation mode: [agents/apply.md](agents/apply.md)
+- Verification mode: [agents/verify.md](agents/verify.md)
+- Orchestrator mode: [agents/orchestrate.md](agents/orchestrate.md)
+
+---
+
+## Templates
+
+- Feature spec: [assets/spec-template.md](assets/spec-template.md)
+- Delta spec: [assets/delta-spec-template.md](assets/delta-spec-template.md)
+- Design decisions: [assets/design-template.md](assets/design-template.md)
+- Validation checklist: [assets/validation-checklist.md](assets/validation-checklist.md)
+
+---
+
+## Commands
+
+```bash
+mkdir -p .sdd/active/<feature-name>
+cp .skilly-hand/catalog/spec-driven-development/assets/spec-template.md .sdd/active/<feature-name>/spec.md
+cp .skilly-hand/catalog/spec-driven-development/assets/design-template.md .sdd/active/<feature-name>/design.md
+```

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

@@ -0,0 +1,26 @@
+# SDD Mode: Apply
+
+## Purpose
+
+Implement approved spec tasks in small, verifiable increments.
+
+## Inputs
+
+- Spec name/path under `.sdd/active/`.
+- Task range or specific task IDs.
+
+## Procedure
+
+1. Read `spec.md` and `design.md` (if present).
+2. Execute one task at a time.
+3. Keep changes scoped to the assigned task.
+4. Run the task verify step before marking done.
+5. Record progress against task IDs.
+6. Stop and report blockers when constraints conflict.
+
+## Quality Bar
+
+- Behavior matches task intent.
+- Verify steps pass before moving on.
+- No hidden scope creep.
+- Progress summary lists completed tasks and changed files.

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

@@ -0,0 +1,25 @@
+# SDD Mode: Orchestrate
+
+## Purpose
+
+Coordinate planning, implementation, and verification through explicit checkpoints.
+
+## Inputs
+
+- High-level request.
+- Context and constraints.
+
+## Workflow
+
+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.
+5. REPEAT: Continue by phase or task batch.
+6. ARCHIVE: Move completed work from `.sdd/active/` to `.sdd/archive/`.
+
+## Coordination Rules
+
+- Pause at checkpoints before continuing.
+- Keep phase summaries short and decision-oriented.
+- Surface blockers with options, not ambiguity.

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

@@ -0,0 +1,27 @@
+# SDD Mode: Plan
+
+## Purpose
+
+Turn a request into an executable, reviewable spec before implementation starts.
+
+## Inputs
+
+- Goal or problem statement.
+- Known constraints.
+- Current state references (files, systems, behaviors).
+
+## Procedure
+
+1. Clarify scope and success criteria.
+2. Decide full spec vs delta spec.
+3. Fill spec sections: Why, What, Constraints, Current State, Tasks, Validation.
+4. Break tasks into small units with explicit verify commands.
+5. Add `design.md` if architecture decisions or trade-offs are non-obvious.
+6. Return the spec summary for review and approval.
+
+## Quality Bar
+
+- Constraints are enforceable, not vague.
+- Every task has files and a verify step.
+- Out-of-scope items are explicit.
+- Another engineer can execute without guessing intent.

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

@@ -0,0 +1,24 @@
+# SDD Mode: Verify
+
+## Purpose
+
+Validate that implementation matches the approved spec and passes quality checks.
+
+## Inputs
+
+- Spec path.
+- Implementation result from apply mode.
+
+## Procedure
+
+1. Read acceptance intent from `spec.md` and `design.md` (if present).
+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.
+
+## Quality Bar
+
+- End-to-end validation is explicit.
+- Gaps are tied to exact tasks or constraints.
+- Report separates blockers from non-blocking warnings.

package/catalog/skills/spec-driven-development/assets/delta-spec-template.md

@@ -0,0 +1,51 @@
+# [Feature Name] - Delta Spec
+
+Use this template when changing behavior in an existing feature.
+
+## Why
+
+[Why this behavior change is needed now.]
+
+## What
+
+[Concrete behavior change and expected outcome.]
+
+## ADDED Requirements
+
+### Requirement: [Name]
+
+[MUST/SHOULD/MAY statement]
+
+#### Scenario: [Name]
+
+- GIVEN [initial state]
+- WHEN [action]
+- THEN [expected outcome]
+
+## MODIFIED Requirements
+
+### Requirement: [Name]
+
+[New requirement text]
+
+(Previously: [old requirement text])
+
+## REMOVED Requirements
+
+### Requirement: [Name]
+
+(Reason: [why removed])
+
+## Tasks
+
+### T1: [Title]
+
+**What:** [Specific implementation]
+
+**Files:** `path/to/file`, `path/to/test`
+
+**Verify:** [Command or manual check]
+
+## Validation
+
+- [Checks that prove the delta behavior is correct]

package/catalog/skills/spec-driven-development/assets/design-template.md

@@ -0,0 +1,31 @@
+# Design: [Feature Name]
+
+Use with `spec.md` when implementation includes meaningful architectural decisions.
+
+## Context
+
+[Current system state, constraints, and why a decision is needed now.]
+
+## Goals
+
+- [Primary outcome]
+- [Secondary outcome]
+
+## Non-Goals
+
+- [Explicitly excluded area]
+- [Another excluded area]
+
+## Decisions
+
+### Decision: [Name]
+
+[What was chosen and why]
+
+### Alternatives Considered
+
+- [Alternative option and why not chosen]
+
+## Risks / Trade-offs
+
+- **[Risk]:** [Impact + mitigation or acceptance rationale]

package/catalog/skills/spec-driven-development/assets/spec-template.md

@@ -0,0 +1,56 @@
+# [Feature Name]
+
+## Why
+
+[1-2 sentences on the problem and why it matters now.]
+
+## What
+
+[Concrete, testable deliverable.]
+
+## Constraints
+
+### Must
+
+- [Required patterns, architecture, or conventions]
+- [Required dependency or existing system usage]
+
+### Must Not
+
+- [Disallowed approaches]
+- [Disallowed dependencies or behavioral changes]
+
+### Out of Scope
+
+- [Adjacent but excluded features]
+
+## Current State
+
+- [Relevant existing files and behavior]
+- [Known dependencies and integration points]
+
+## Tasks
+
+### T1: [Title]
+
+**What:** [Specific implementation change]
+
+**Files:** `path/to/file`, `path/to/test`
+
+**Verify:** [Command or manual check]
+
+---
+
+### T2: [Title]
+
+**What:** [Specific implementation change]
+
+**Files:** `path/to/file`
+
+**Verify:** [Command or manual check]
+
+## Validation
+
+- [Feature-level automated check]
+- [Feature-level manual scenario]
+- [Additional release-specific verification]

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

@@ -0,0 +1,32 @@
+# Spec Validation Checklist
+
+Use this checklist before implementation and again before archive.
+
+## Spec Quality
+
+- [ ] Title is specific and unambiguous.
+- [ ] `Why` explains urgency and value.
+- [ ] `What` is concrete and testable.
+- [ ] Constraints are enforceable (`Must`, `Must Not`, `Out of Scope`).
+- [ ] `Current State` references real files or systems.
+
+## Task Quality
+
+- [ ] Tasks are small and scoped.
+- [ ] Each task has `What`, `Files`, and `Verify`.
+- [ ] Task verification can be completed quickly.
+- [ ] No task mixes unrelated concerns.
+
+## Implementation Readiness
+
+- [ ] Success criteria are explicit.
+- [ ] No critical ambiguity remains.
+- [ ] Architecture decisions are captured in `design.md` if needed.
+
+## Pre-Archive Verification
+
+- [ ] All planned tasks are complete.
+- [ ] Feature-level validation passes.
+- [ ] Constraints were respected.
+- [ ] No unintended scope creep.
+- [ ] Work is moved from `.sdd/active/` to `.sdd/archive/`.

package/catalog/skills/spec-driven-development/manifest.json

@@ -0,0 +1,41 @@
+{
+  "id": "spec-driven-development",
+  "title": "Spec-Driven Development",
+  "description": "Plan, execute, and verify multi-step work through versioned specs with small, testable tasks.",
+  "portable": true,
+  "tags": ["core", "workflow", "planning"],
+  "detectors": ["always"],
+  "detectionTriggers": ["always"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-03",
+    "license": "Apache-2.0",
+    "version": "1.0.1",
+    "changelog": "Added explicit delta/full guidance, archive rules, task sizing decision tree, and common mistakes section; improves planning clarity and reduces execution ambiguity; affects spec-driven-development SKILL.md usage guidance",
+    "auto-invoke": "Planning or executing feature work, bug fixes, and multi-phase implementation",
+    "allowed-tools": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash",
+      "Task",
+      "SubAgent"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "agents/plan.md", "kind": "instruction" },
+    { "path": "agents/apply.md", "kind": "instruction" },
+    { "path": "agents/verify.md", "kind": "instruction" },
+    { "path": "agents/orchestrate.md", "kind": "instruction" },
+    { "path": "assets/spec-template.md", "kind": "asset" },
+    { "path": "assets/delta-spec-template.md", "kind": "asset" },
+    { "path": "assets/design-template.md", "kind": "asset" },
+    { "path": "assets/validation-checklist.md", "kind": "asset" }
+  ],
+  "dependencies": []
+}

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

@@ -0,0 +1,141 @@
+# Token Optimizer Guide
+
+## When to Use
+
+Use this skill when:
+
+- Starting a task and deciding the right reasoning depth.
+- Balancing response quality against speed and token budget.
+- Choosing how much context gathering is actually needed.
+- Reassessing scope when a task becomes more complex than expected.
+
+Do not use this skill for:
+
+- Cases where the user explicitly requests a fixed reasoning level.
+- Mid-task rewrites that would reset already-correct progress.
+- Emergency actions where immediate execution is the only priority.
+
+---
+
+## Critical Patterns
+
+### Pattern 1: Classify Complexity First
+
+Pick a complexity tier before doing substantial work:
+
+| Tier | Typical Shape |
+| --- | --- |
+| Trivial | Single lookup, deterministic answer, no ambiguity |
+| Simple | 2-3 clear steps, minimal context, low risk |
+| Moderate | Multiple files or decisions, some trade-offs |
+| Complex | Broad impact, cross-cutting behavior, non-trivial edge cases |
+| Expert | Security/performance critical, architecture-level consequences |
+
+### Pattern 2: Match Effort to Complexity
+
+Use the lightest viable approach, then escalate only if needed:
+
+| Tier | Reasoning Style | Context Gathering | Response Depth |
+| --- | --- | --- | --- |
+| Trivial | None or minimal | Direct targeted read/search | 1-2 sentences |
+| Simple | Light | 1-2 focused operations | Brief factual answer |
+| Moderate | Selective | 3-5 targeted operations | Concise rationale |
+| Complex | Regular | Systematic exploration | Detailed explanation |
+| Expert | Deep | Broad investigation + explicit trade-offs | Thorough analysis |
+
+### Pattern 3: Progressive Escalation
+
+Escalate one tier when you discover:
+
+1. Hidden dependencies or wider blast radius.
+2. Conflicting constraints or unclear acceptance criteria.
+3. Additional non-functional requirements (security, performance, compatibility).
+
+Do not jump to the highest-effort tier by default.
+
+### Pattern 4: Token-Saving Defaults
+
+Always prefer:
+
+- Batched independent reads/searches.
+- Targeted pattern matching (`rg`) before broad scans.
+- Reuse of already-collected context over repeated calls.
+- Brief outputs unless rationale materially improves decisions.
+
+Avoid:
+
+- Reading full files when a narrow section is enough.
+- Re-running identical commands without new signal.
+- Long-form explanations for straightforward checks.
+
+---
+
+## Decision Tree
+
+```text
+Single lookup with known target?                  -> Trivial
+Needs 2-3 clear actions and limited context?      -> Simple
+Touches multiple files or design choices?         -> Moderate
+Needs architectural/refactor trade-offs?          -> Complex
+Impacts security/performance/core reliability?    -> Expert
+```
+
+Upgrade one tier if:
+
+- User asks to optimize, harden, or redesign.
+- Public API or user-facing behavior changes.
+- Scope expands beyond expected files/components.
+
+Downgrade one tier if:
+
+- User provides exact file paths and acceptance criteria.
+- Existing patterns make implementation mostly mechanical.
+
+---
+
+## Examples
+
+### Example 1: Trivial
+
+```text
+Request: "What version is in package.json?"
+Approach: single file read, no extra reasoning, direct answer.
+```
+
+### Example 2: Simple
+
+```text
+Request: "Check whether alert component has tests."
+Approach: targeted file search, return yes/no + location.
+```
+
+### Example 3: Moderate
+
+```text
+Request: "Add disabled state to button component."
+Approach: inspect component + styles + tests, apply existing patterns, summarize key decisions.
+```
+
+### Example 4: Complex
+
+```text
+Request: "Refactor validation flow to support async checks."
+Approach: analyze architecture and compatibility constraints, propose phased changes, verify behavior end-to-end.
+```
+
+---
+
+## Commands
+
+```bash
+rg --files
+rg -n "<pattern>" <path>
+rg -n "TODO|FIXME" src
+```
+
+---
+
+## Resources
+
+- Complexity heuristics: [references/complexity-indicators.md](references/complexity-indicators.md)
+- Related planning workflow: [../spec-driven-development/SKILL.md](../spec-driven-development/SKILL.md)

package/catalog/skills/token-optimizer/manifest.json

@@ -0,0 +1,33 @@
+{
+  "id": "token-optimizer",
+  "title": "Token Optimizer",
+  "description": "Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens.",
+  "portable": true,
+  "tags": ["core", "workflow", "efficiency"],
+  "detectors": ["always"],
+  "detectionTriggers": ["always"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot"],
+  "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"
+    ]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "references/complexity-indicators.md", "kind": "reference" }
+  ],
+  "dependencies": []
+}