Initial commit

2025-11-30 08:38:26 +08:00
commit 41d9f6b189
304 changed files with 98322 additions and 0 deletions
--- a/skills/skill-creator/resources/skill-construction.md
+++ b/skills/skill-creator/resources/skill-construction.md
@@ -0,0 +1,419 @@
+# Skill Construction
+
+This resource supports **Step 5** of the Skill Creator workflow.
+
+**Input files:** `$SESSION_DIR/global-context.md`, `$SESSION_DIR/step-4-output.md`
+**Output files:** `$SESSION_DIR/step-5-output.md`, actual skill files created in target directory, updates `global-context.md`
+
+**Stage goal:** Build the actual skill files following standard structure.
+
+---
+
+## Why Complexity Level
+
+### WHY Complexity Assessment Matters
+
+Complexity determines skill structure:
+- **Simple skills:** SKILL.md only (no resources needed)
+- **Moderate skills:** SKILL.md + 1-3 focused resource files
+- **Complex skills:** SKILL.md + 4-8 resource files
+
+**Mental model:** Don't build a mansion when a cottage will do. Match structure to content needs.
+
+Over-engineering (too many files for simple content): maintenance burden, navigation difficulty
+Under-engineering (too little structure for complex content): bloated files, poor organization
+
+### WHAT Complexity Levels Exist
+
+**Levels:**
+
+**Level 1 - Simple:** 3-5 steps, < 300 lines total → SKILL.md + rubric only
+
+**Level 2 - Moderate:** 5-8 steps, 300-800 lines → SKILL.md + 1-3 resource files + rubric
+
+**Level 3 - Complex:** 8+ steps, 800+ lines → SKILL.md + 4-8 resource files + rubric
+
+---
+
+### WHAT to Decide
+
+**Assess your extracted content:**
+
+**Count:**
+- Total workflow steps: [X]
+- Major decision points: [X]
+- Key concepts to explain: [X]
+- Examples needed: [X]
+- Total estimated lines: [X]
+
+**Complexity level:** [1 / 2 / 3]
+
+**Rationale:** [Why this level fits]
+
+**Proposed structure:** [List of files]
+
+**Present to user:** "Based on content volume, I recommend [LEVEL] complexity. Structure: [FILES]. Does this make sense?"
+
+---
+
+## Why Plan Resources
+
+### WHY Resource Planning Matters
+
+Resource files should be:
+- **Focused:** Each file covers one cohesive topic
+- **Referenced:** Linked from SKILL.md workflow steps
+- **Sized appropriately:** Under 500 lines each
+- **WHY/WHAT structured:** Follows standard format
+
+**Mental model:** Resource files are like appendices - referenced when needed, not read linearly.
+
+Poor planning: overlapping content, unclear purpose, navigation difficulty, files too large or too granular.
+
+### WHAT to Plan
+
+#### Grouping Principles
+
+**Group related content into resource files based on:**
+
+**By workflow step** (for complex skills):
+- One resource per major step
+- Contains WHY/WHAT for all sub-steps
+- Example: `inspectional-reading.md` for Step 1
+
+**By topic** (for moderate skills):
+- Group related concepts
+- Example: `key-concepts.md`, `decision-framework.md`, `examples.md`
+
+**By type** (alternative):
+- All principles in one file
+- All examples in another
+- All templates in another
+
+---
+
+#### Resource File Template
+
+**Each resource file should include:**
+
+```markdown
+# [Resource Name]
+
+This resource supports **Step X** of the [Skill Name] workflow.
+
+---
+
+## Why [First Topic]
+
+### WHY This Matters
+
+[Brief explanation activating context, not over-explaining]
+
+### WHAT to Do
+
+[Specific instructions, options with tradeoffs, user choice points]
+
+---
+
+## Why [Second Topic]
+
+### WHY This Matters
+
+...
+
+### WHAT to Do
+
+...
+```
+
+---
+
+#### File Naming
+
+**Use descriptive, kebab-case names:**
+- ✅ `inspectional-reading.md`
+- ✅ `component-extraction.md`
+- ✅ `evaluation-rubric.json`
+- ❌ `resource1.md`
+- ❌ `temp_file.md`
+
+---
+
+### WHAT to Document
+
+```markdown
+## Resource Plan
+
+**Complexity level:** [Level 1/2/3]
+
+**Resource files:**
+
+1. **[filename.md]**
+   - Purpose: [What this covers]
+   - Linked from: [Which SKILL.md steps]
+   - Estimated lines: [X]
+
+2. **[filename.md]**
+   - Purpose: [What this covers]
+   - Linked from: [Which SKILL.md steps]
+   - Estimated lines: [X]
+
+3. **evaluation-rubric.json**
+   - Purpose: Quality scoring
+   - Linked from: Final validation step
+
+**Total files:** [X]
+```
+
+**Present to user:** "Here's the resource structure plan. Any changes needed?"
+
+---
+
+## Why SKILL.md Structure
+
+### WHY Standard Structure Matters
+
+SKILL.md must follow conventions:
+- **YAML frontmatter:** For skill system identification and invocation
+- **Table of Contents:** For navigation
+- **Read This First:** For context and overview
+- **Workflow with checklist:** For execution
+- **Step details:** With resource links where needed
+
+**Mental model:** SKILL.md is the "main" file - everything starts here.
+
+Without standard structure: skill won't be invoked correctly, users confused about how to start, poor usability.
+
+### WHAT to Include
+
+#### 1. YAML Frontmatter
+
+```yaml
+---
+name: skill-name
+description: Use when [TRIGGER CONDITIONS - focus on WHEN not WHAT]. Invoke when [USER MENTIONS]. Also applies when [SCENARIOS].
+---
+```
+
+**Critical:** Description focuses on WHEN to use (triggers), not WHAT it does.
+
+**Bad:** `description: Extracts skills from documents`
+**Good:** `description: Use when user has a document containing theory or methodology and wants to convert it into a reusable skill`
+
+---
+
+#### 2. Title and Table of Contents
+
+Standard TOC linking to Read This First, Workflow, and each step.
+
+#### 3. Read This First
+
+Includes: What skill does (1-2 sentences), Process overview, Why it works, Collaborative nature.
+
+#### 4. Workflow Section
+
+Must have: **"COPY THIS CHECKLIST"** instruction, followed by checklist with steps and sub-tasks.
+
+#### 5. Step Details
+
+Format: Step heading, Goal statement, Sub-tasks with resource links or inline instructions.
+
+---
+
+### WHAT to Validate
+
+**Check:**
+- ✅ YAML frontmatter present and description focuses on WHEN
+- ✅ Table of contents complete
+- ✅ Read This First section provides context
+- ✅ Workflow has explicit copy instruction
+- ✅ All steps have goals and sub-tasks
+- ✅ Resource links are correct and use anchors
+- ✅ File is under 500 lines
+
+---
+
+## Why Resource Structure
+
+### WHY WHY/WHAT Format Matters
+
+Resource files follow standard format:
+- **WHY sections:** Activate relevant context, explain importance
+- **WHAT sections:** Provide specific instructions, present options
+
+**Mental model:** WHY primes the LLM's activation space; WHAT provides execution guidance.
+
+Without WHY: LLM may not activate relevant knowledge, shallow understanding
+Without WHAT: Clear intent but unclear execution, user stuck on "now what?"
+
+### WHAT to Include in Resources
+
+#### WHY Section Format
+
+Explains what this accomplishes, why it's important, how it fits in the process. Optional mental model. Keep focused - don't over-explain.
+
+#### WHAT Section Format
+
+Specific instructions in clear steps. If options exist, present each with: when to use, pros, cons, how. Mark user choice points.
+
+---
+
+### WHAT to Validate
+
+**For each resource file, check:**
+- ✅ Each major section has WHY and WHAT subsections
+- ✅ WHY explains importance without over-explaining
+- ✅ WHAT provides concrete, actionable guidance
+- ✅ Options presented with trade-offs when applicable
+- ✅ User choice points clearly marked
+- ✅ File is under 500 lines
+
+---
+
+## Why Evaluation Rubric
+
+### WHY Rubric Matters
+
+The rubric enables:
+- **Self-assessment:** LLM can objectively score its work
+- **Quality standards:** Clear criteria for success
+- **Improvement identification:** Know what needs fixing
+- **User transparency:** User sees quality assessment
+
+**Mental model:** Rubric is like a grading rubric for an assignment - objective criteria for evaluation.
+
+Without rubric: no quality control, subjective assessment, missed improvements.
+
+### WHAT to Include
+
+#### JSON Structure
+
+```json
+{
+  "criteria": [
+    {
+      "name": "[Criterion Name]",
+      "description": "[What this measures]",
+      "scores": {
+        "1": "[Description of score 1 performance]",
+        "2": "[Description of score 2 performance]",
+        "3": "[Description of score 3 performance]",
+        "4": "[Description of score 4 performance]",
+        "5": "[Description of score 5 performance]"
+      }
+    }
+  ],
+  "threshold": 3.5,
+  "passing_note": "Average score must be ≥ 3.5 for skill to be considered complete. Scores below 3 in any category require revision."
+}
+```
+
+---
+
+#### Standard Criteria
+
+**Recommended criteria for skills:**
+
+1. **Completeness:** Are all required components present?
+2. **Clarity:** Are instructions clear and unambiguous?
+3. **Actionability:** Can this be followed step-by-step?
+4. **Structure:** Is organization logical and navigable?
+5. **Examples:** Are sufficient examples provided?
+6. **Triggers:** Is "when to use" clearly defined?
+
+**Customize based on skill type** - add domain-specific criteria as needed.
+
+---
+
+#### Scoring Guidelines
+
+**Score scale:**
+- **5:** Excellent - exceeds expectations
+- **4:** Good - meets all requirements well
+- **3:** Adequate - meets minimum requirements
+- **2:** Needs improvement - significant gaps
+- **1:** Poor - major issues
+
+**Threshold:** Average ≥ 3.5 recommended
+
+---
+
+### WHAT to Validate
+
+**Check rubric:**
+- ✅ 4-7 criteria (not too few or too many)
+- ✅ Each criterion has clear descriptions for scores 1-5
+- ✅ Criteria are measurable (not subjective)
+- ✅ Threshold is specified
+- ✅ JSON is valid
+
+---
+
+## Write Step 5 Output
+
+After completing skill construction and verifying files, write to output file:
+
+```bash
+cat > "$SESSION_DIR/step-5-output.md" << 'EOF'
+# Step 5: Skill Construction Output
+
+## Complexity Level
+
+**Level:** [1/2/3] - [Simple/Moderate/Complex]
+**Rationale:** [Why this level]
+
+## Resource Plan
+
+**Files created:**
+1. SKILL.md ([X] lines) - Main skill file
+2. resources/[filename1].md ([X] lines) - [Purpose]
+3. resources/[filename2].md ([X] lines) - [Purpose]
+...
+N. resources/evaluation-rubric.json - Quality scoring
+
+**Total files:** [X]
+
+## Skill Location
+
+**Path:** [Full path to created skill directory]
+
+## File Verification
+
+**Line counts:**
+- ✅ SKILL.md: [X]/500 lines
+- ✅ [file1].md: [X]/500 lines
+- ✅ [file2].md: [X]/500 lines
+...
+
+**Structure checks:**
+- ✅ YAML frontmatter present and WHEN-focused
+- ✅ Table of contents complete
+- ✅ Workflow has copy instruction
+- ✅ All resource links valid
+- ✅ WHY/WHAT structure followed
+- ✅ Rubric JSON valid
+
+## User Validation
+
+**Status:** [Approved / Needs revision]
+**User notes:** [Feedback]
+
+EOF
+```
+
+**Update global context:**
+
+```bash
+cat >> "$SESSION_DIR/global-context.md" << 'EOF'
+
+## Step 5 Complete
+
+**Skill created at:** [path]
+**Files:** [count]
+**All files under 500 lines:** Yes
+**Ready for validation:** Yes
+
+EOF
+```
+
+**Next step:** Step 6 (Validation) will read `global-context.md` + `step-5-output.md` + actual skill files.