skill-creator

name: skill-creator description: "Use when creating, refactoring, or validating OpenCode skills. Provides S.T.A.R. workflow, Bottom-Up Reconstruction, and Quality Gates. Semantic cohesion: Contextual granularity with dynamic context pruning." license: MIT compatibility: opencode

Quick Decision Matrix

<decision_matrix> <question>What do you need to accomplish?</question>

Setup

# Verify Python 3.8+ is installed
python --version

# Install dependencies
pip install pyyaml rich

# Create a new skill
python .claude/skills/skill-creator/scripts/init_skill.py my-skill

# Validate skill quality
python .claude/skills/skill-creator/scripts/validate_skill.py .claude/skills/my-skill

# Calculate SkillScore (Tier 1: Fast static analysis)
python .claude/skills/skill-creator/scripts/skillscore_evaluator.py .claude/skills/my-skill/SKILL.md

Quantitative Impact

Key Drivers:

• Semantic cohesion (+0.12 SkillScore): Contextual granularity vs fragments
• Progressive disclosure (+8-15%): Tiered architecture with JIT loading
• Quality gates (+15-25): Boolean gates + SkillScore validation
• Portability (+10-15): Generic placeholders vs hardcoded paths

About SkillScore

SkillScore uses a two-tiered quality assessment system:

• Tier 1 (Fast): Static analysis of document structure (current implementation)

  • Validates syntax, structure, and keyword density
  • Speed: ~10ms per file
  • Use: Development iteration and CI/CD

• Tier 2 (Deep): AdvancedIF-style rubric verification (planned)

  • Validates actual agent behavior using LLM-as-a-Judge
  • Speed: ~2-5s per file
  • Use: Production validation and scientific rigor

Important: Tier 1 is a development tool, not a scientific metric. For production validation, use Tier 2 (see docs/skillscore-tier2-specification.md).

See also: docs/skillscore-red-team-analysis.md for critical evaluation.

Core Principles

S.T.A.R.: Structure → Target → Author → Review

Bottom-Up: Audit → Rebuild → Validate

🚨 MANDATORY PROTOCOL (NON-NEGOTIABLE)

1. STOP. Do not create skills without a S.T.A.R. plan.
2. MUST use the Decision Matrix for navigation.
3. CRITICAL: All files MUST have semantic cohesion.
4. NEVER use excessive atomization (>15 files).

Applying Prompt Engineering Best Practices

When creating skills, apply C.L.E.A.R. principles from the prompt-engineering skill:

See Also: prompt-engineering skill for complete framework details (Diátaxis, COSTAR, C.L.E.A.R., Chain-of-Thought, Decision Matrices, Few-Shot).

Document Structure

Tier 1: YAML Frontmatter (< 100 tokens)

---
name: skill-name
description: "Concise description with keywords"
license: MIT
compatibility: opencode
---

Tier 2: SKILL.md (100-800 lines)

Purpose: Decision matrix + setup commands

Structure:

• Quick Decision Matrix (XML format)
• Setup commands (bash)
• Key workflows and common patterns
• Reference links

Tier 3: Comprehensive References (800-1500 lines)

Purpose: Deep dives with full semantic context

Size Guidelines:

When to Split:

• Exceeds 2000 lines AND natural section boundaries exist
• Covers multiple unrelated domains (e.g., testing + deployment)
• Creates navigation difficulties despite tags

When to Consolidate:

• Too many tiny files (> 15 files, avg < 150 lines)
• Arbitrary splits mid-concept
• Related content scattered across 5+ files

Navigation Tags (for JIT Section Loading)

XML format for <nav> tags in reference files:

<nav>
  <tag name="section-name" section="Section Title" />
</nav>

YAML format for skill metadata:

# Example in YAML frontmatter
tags:
  - authentication
  - error-handling
  - testing

Key Workflows

S.T.A.R. Workflow (Creation)

Setup → Task → Analysis → Result

1. Setup: Structure the skill directory and SKILL.md skeleton
2. Task: Define user intents and semantic domains
3. Analysis: Design comprehensive guides (800-1500 lines) with navigation
4. Result: Validate with boolean gates and SkillScore > 90

See: Workflow: Skill Creation Comprehensive Guide

Bottom-Up Reconstruction (Refactoring)

For degraded skills needing rebuild:

1. Audit: Detect problems (excessive atomization, content drift)
2. Extract: Preserve valuable content and identify patterns
3. Rebuild: Consolidate into comprehensive guides
4. Validate: Quality gates (boolean gates + SkillScore)

See: Workflow: Bottom-Up Reconstruction Comprehensive Guide

Common Patterns

Decision Matrix Structure

<decision_matrix>
<question>What task do you need?</question>
<options>

<option condition="Specific user intent">
  <action><navigate_to>references/comprehensive-guide.md</navigate_to></action>
</option>
</options>
</decision_matrix>

Atom Metadata

<atom>
  <type>pattern|workflow|reference</type>
  <diataxis_quadrant>how-to|tutorial|explanation|reference</diataxis_quadrant>
  <intent>specific_user_intent</intent>
</atom>

Quality Targets

Production Ready:
  SkillScore (Tier 1): > 90/100
  Boolean Gates: 10/10 PASS
  Reasoning Success: 100%

Good Quality:
  SkillScore (Tier 1): 80-90/100
  Boolean Gates: 9/10 PASS
  Reasoning Success: > 95%

Two-Tiered Validation Architecture

We use a two-tiered approach to balance speed and scientific rigor:

Note: High Tier 1 scores are necessary but not sufficient for Tier 2 success.

Anti-Patterns

❌ Excessive atomization: > 15 files, avg < 150 lines ❌ Arbitrary splits: Breaking mid-concept to hit line targets ❌ Missing decision matrix: Users can't navigate ❌ No setup section: Users don't know how to use the skill

✅ Semantic cohesion: 800-1500 line comprehensive guides ✅ Navigation tags: Enable JIT section loading ✅ Decision matrix: Clear navigation paths ✅ Setup section: Prerequisites and commands

References

• Creation: S.T.A.R. Method - Complete workflow for creating production-ready skills from scratch
• Refactoring: Bottom-Up Reconstruction - End-to-end workflow for refactoring degraded skills
• Progressive Disclosure: Comprehensive Guide - 3-tier architecture with JIT loading examples
• Validation: Quality Gates - Boolean gates, SkillScore metrics, and TDD workflow
• Navigation: Tags Specification - JIT loading XML format specification