gh-lyndonkl-claude/skills/skill-creator/resources/skill-construction.md

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:

# [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

## 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

---
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

{
  "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:

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:

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.