skill-expert-skills

Skill Expert v4.0 — Universal Edition

Transform "create/optimize a Skill" requests into triggerable, reusable, maintainable, verifiable Skill packages with quality gates.

Principles: Expertise First | User Confirmation First | Conciseness | Universality

---

Pre-Flight Check

---

Fast Track Decision

After identifying task type, classify complexity to choose the execution path:

Task Classification
    |
    +-- Simple Skill (minimal template, < 100 lines, well-known domain)
    |   -> FAST TRACK: Phase 0 -> Phase 3 -> Phase 4
    |
    +-- Standard Skill (with references, 100-500 lines)
    |   -> STANDARD: Phase 0 -> Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5
    |
    +-- Complex Skill (knowledge-intensive, domain expertise needed)
    |   -> FULL: All phases with deep research
    |
    +-- Validate/Package Only
        -> Jump to Phase 4 / Command Reference

---

Phase 0: Discovery + Hypothesis

Goal: Understand the real need, check for existing skills.

0.1 Task Classification

0.2 Skill Discovery (Reuse First)

-> references/skill-discovery-protocol.md

Search local skills first, then trusted external sources.

0.3 Hypothesis Generation + 5 Whys

-> references/hypothesis-ladder-for-skills.md

Generate 3-5 hypotheses about what the user really wants:

Validate with user. Use 5 Whys to uncover the deep need behind the surface request.

GATE: Hypothesis Validation

---

Phase 1: Requirement Mining

Goal: Get to the REAL problem, validate it, confirm with user.

1.1 Three-Stage Elicitation

-> references/requirement-elicitation-protocol.md

Stage 1: Explicit (5W1H)  ->  Stage 2: Implicit (4 methods)  ->  Stage 3: Validation

1.2 Skill Type Classification

-> references/skill-type-taxonomy.md

Quick question to determine type (~80% accuracy):

1) Comprehensive "summary"    2) Key-only "insight/diagnosis"
3) Produce "new content"      4) Reach a "conclusion"

1.3 Non-Technical Methodology (if applicable)

-> references/non-technical-methodology-research.md

For judgment-heavy domains: find experts, golden examples, anti-patterns.

1.4 User Confirmation

-> references/user-confirmation-protocol.md

Present requirements summary → get explicit user confirmation.

GATE: Requirement Gate

---

Phase 2: Knowledge Acquisition

Goal: Become an expert BEFORE writing.

2.1 Research Workflow

-> references/knowledge-acquisition-guide.md

LLM baseline -> Extract domains -> Research with tools -> Cross-validate -> Gate -> Self-check

Use whatever tools are available in your environment:

• Documentation lookup tools (official docs first)
• Web search tools (for latest practices, at least 3 sources)
• Code search tools (for real-world examples)
• URL fetch tools (for specific references)

If no external tools available, rely on own knowledge but mark it as "unverified".

2.2 Source Credibility Tiers

2.3 Deep Research (Complex skills only)

-> references/deep-research-methodology.md

Five-layer knowledge pyramid: Basics -> Principles -> Practice -> Expert -> Frontier.

GATE: Knowledge Gate (Composite)

All 4 sub-checks must pass as a single gate:

-> references/knowledge-validation-checklist.md for details

---

Phase 3: Skill Writing

Goal: Write the skill following enterprise patterns.

3.1 SKILL.md Positioning (NON-NEGOTIABLE)

SKILL.md SHOULD be:
  ✅ Scannable in 30 seconds (table of contents)
  ✅ Decision tree: "what situation → which action/file"
  ✅ Command reference: one-line key commands
  ✅ Minimal necessary constraints/contracts

SKILL.md should NOT be:
  ❌ Detailed knowledge base or tutorials
  ❌ Complete protocol explanations
  ❌ Long examples or code blocks
  ❌ Background knowledge

→ All detailed content MUST go to references/

3.2 Conciseness Checklist

• New content > 20 lines? → Move to references/
• Does AI need this every invocation? → If not, move to references/
• Can it be a one-line pointer? → Use → references/xxx.md
• Body < 500 lines? → Hard limit 800 lines
• Contains tech-stack specific content? → Abstract or move to references/

3.3 Template Selection

-> references/skill-templates.md

3.4 Frontmatter Specification

---
name: my-skill              # Required. hyphen-case, ≤64 chars, matches directory name
description: |               # Required. ≤1024 chars, third person, no < >
  What this skill does.
  Use when:
  - scenario 1
  - scenario 2
  Not for: X, Y.
license: MIT                 # Optional
compatibility: Python 3.8+   # Optional. ≤500 chars
allowed-tools: Read Write    # Optional. space-delimited tool names
metadata:                    # Optional. extension fields
  version: 1.0.0
---

3.5 Directory Structure

my-skill/
├── SKILL.md              # Required: instructions + metadata
├── scripts/              # Optional: executable code
│   ├── main.py
│   └── requirements.txt
├── references/           # Optional: detailed docs (loaded into context)
│   ├── patterns.md
│   └── checklist.md
└── assets/               # Optional: templates, images (NOT loaded into context)
    └── template.md

3.6 Writing Standards

-> references/writing-style-guide.md -> references/universality-guide.md

GATE: Writing Gate

---

Phase 4: Quality Validation + User Confirmation

Goal: Ensure output meets quality standards and user needs.

4.1 Structural Validation Checklist

4.2 Portability Checklist

4.3 User Final Confirmation

-> references/user-confirmation-protocol.md

Present: validation results + deliverables + features summary. Get explicit confirmation.

GATE: Delivery Gate

---

Phase 5: Self-Reflection + Knowledge Precipitation

Goal: Learn from the experience.

5.1 Self-Reflection Report

## Self-Reflection

| Dimension | Score (1-5) | Evidence |
|-----------|-------------|----------|
| Requirement Understanding | [1-5] | [notes] |
| Knowledge Completeness | [1-5] | [notes] |
| Output Quality | [1-5] | [notes] |
| User Satisfaction | [1-5] | [notes] |
| **Total** | **[/20]** | |

| Problem | Cause | Prevention |
|---------|-------|------------|
| [issue] | [why] | [measure] |

5.2 Knowledge Precipitation

• Document lessons learned
• Update references if new patterns discovered
• Note what worked well for future skills

GATE: Reflection Complete

---

Decision Tree

【Create New Skill】
  Phase 0: Classify task → Generate hypotheses → [Fast Track?] → User confirms
  Phase 1: 5 Whys → Skill Type → Validate requirements → User confirms
  Phase 2: Research domain → 4-Layer knowledge gate
  Phase 3: Select template → Write SKILL.md → Conciseness check
  Phase 4: Structural validation → Portability check → User confirms
  Phase 5: Self-reflect → Precipitate knowledge

【Optimize Existing Skill】
  Phase 0: Classify → Hypothesize what to improve → [Fast Track?] → User confirms
  Phase 1: 5 Whys on current pain points → User confirms
  Phase 2: Research latest patterns → 4-Layer gate
  Phase 3: Modify SKILL.md → Conciseness check
  Phase 4: Validate → User confirms
  Phase 5: Self-reflect → Document changes

【Validate / Package Only】
  -> Phase 4: Run validation scripts → Report results

---

Command Reference

Run from project root:

# Search installed skills (reuse-first)
python scripts/search_skills.py "<keyword>" --root <skills-directory>

# Initialize new skill
python scripts/init_skill.py <skill-name> --path <skills-directory>

# Validate (required before delivery)
python scripts/quick_validate.py <skill-directory>
python scripts/universal_validate.py <skill-directory>

# Package for distribution (optional)
python scripts/package_skill.py <skill-directory> ./dist

# Maintenance
python scripts/upgrade_skill.py <skill-directory>
python scripts/diff_with_official.py <skill-directory>
python scripts/analyze_trigger.py <skill-directory>

---

Key Constraints

---

Output Contract

Required: Updated SKILL.md + change summary (triggers, domains, validation results)

On-demand: references/ | scripts/ | assets/

---

Gate System Summary

---

Definition of Done

Complete ALL before declaring done:

Phase 0-1: Understanding

• Task type identified
• 3-5 hypotheses generated, ≥1 confirmed
• 5 Whys completed
• User explicitly confirmed requirements

Phase 2: Knowledge

• Domain researched (used available tools or marked as unverified)
• Freshness, accuracy, completeness gates passed
• Own knowledge vs findings compared

Phase 3: Writing

• SKILL.md body < 500 lines
• Frontmatter valid (name, description)
• Detailed content in references/ (not body)
• Has decision tree or workflow
• Has output contract

Phase 4: Validation

• Structural checks passed
• Portability checks passed (no hardcoded paths/tools/projects)
• User explicitly confirmed output

Phase 5: Reflection

• Quality score calculated
• Improvement areas documented
• Lessons captured

Self-check: Did I follow Phase 0 → 1 → 2 → 3 → 4 → 5 in order? If phases were skipped → go back and complete them.

---

References Navigation

Core Phase References

Supporting References

Official Resources