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> What do you need to accomplish?

creation-star-method.md Complete S.T.A.R. workflow (Setup → Task → Analysis → Result) for creating production-ready skills with SkillScore > 90 refactoring-bottom-up-reconstruction.md End-to-end workflow: Audit → Extract → Rebuild → Validate. Consolidate fragmented content into comprehensive guides (800-1500 lines) progressive-disclosure-comprehensive-guide.md Progressive disclosure architecture: 3-tier system (metadata → instructions → references) with JIT loading for 70%+ token savings validation-quality-gates.md Quality gates: Layer 1 (Boolean checks), Layer 1.5 (C.L.E.A.R. principles), Layer 2 (SkillScore metrics) navigation-tags-specification.md Specification for XML navigation tags, JIT loading patterns, and validation rules references/portable-vs-project-specific-decision-framework.md Comprehensive framework with three-factor test, binary checklist, and 7 canonical examples to distinguish generic guidance from monorepo-specific content

---

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

Metric	Anti-Pattern	Best Practice	Improvement
SkillScore	55-70	88-95	+20-35
Cohesion	0.45-0.60	0.80-0.93	+40-105%
Nav Time	3-5 min	30-60 sec	75-83% faster
File Hops	15+	3-5	70% reduction

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:

Principle	Application to Skills	Impact
Concise	Maximize signal-to-noise. Remove filler phrases ("please", "thank you").	70% token reduction
Logical	Follow COSTAR structure: Context → Task → Constraints → Format	+55% clarity
Explicit	Use objective metrics instead of vague terms ("brief" → "3 sentences, 50 words max")	91% hallucination reduction
Adaptive	Handle edge cases with IF/THEN logic. Provide tier-based guidelines.	+51% edge case handling
Reflective	Include validation checklists and self-audit before completion.	67% error reduction

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:

Tier	Size Guidelines	Purpose
Tier 3	800-1500 lines (when semantically cohesive)	Comprehensive deep dives

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:

Tier	Type	Method	Cost	Use Case
Tier 1	Static Analysis	skillscore_evaluator.py checks structure/keywords	Free	Dev loop (current)
Tier 2	Deep Verify	LLM-as-a-Judge checks semantic adherence	$$$	Release gating (planned)

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