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

| # | Checkpoint | Status |

|---|------------|--------|

| 1 | Read this SKILL.md? | [ ] |

| 2 | Identified task type? (Create / Optimize / Validate / Package) | [ ] |

| 3 | Ready to classify complexity? (Simple / Standard / Complex) | [ ] |

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

| Type | Action |

|------|--------|

| Create New | Continue to 0.2 |

| Optimize Existing | Continue to 0.2 |

| Validate Only | Skip to Command Reference |

| Package Only | Skip to Command Reference |

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:

| Hypothesis Type | Example Question |

|-----------------|-----------------|

| Scope | Full solution or single function? |

| Audience | Novice or expert user? |

| Trigger | What scenarios activate this skill? |

| Output | Code, document, decision, or report? |

| Depth | Quick utility or comprehensive workflow? |

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

GATE: Hypothesis Validation

| Condition | On Failure |

|-----------|------------|

| At least 1 hypothesis confirmed by user | Continue questioning |

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

| Condition | On Failure |

|-----------|------------|

| User explicitly confirms requirements | Redo mining |

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

| Tier | Source Type | Trust Level |

|------|-----------|-------------|

| S | Official docs, official blog | Highest — use directly |

| A | Official GitHub, official examples | High — use directly |

| B | Known tech blogs, high-vote StackOverflow | Medium — cross-validate |

| C | Personal blogs, forums | Low — must multi-source verify |

| D | Unknown source, AI-generated | Lowest — must verify against official |

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:

| Sub-Check | Pass Condition |

|-----------|----------------|

| Freshness | Source date < 1 year, grade A/B |

| Accuracy | Official source + 2 independent confirmations |

| Completeness | Core features 100%, scenarios 80%+ |

| Fusion | LLM vs fresh knowledge compared, conflicts resolved |

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

| Template | When | Complexity | Files |

|----------|------|-----------|-------|

| Minimal | Quick utility, personal preference | Low | 1 |

| Read-only | Analysis, audit, review (no file changes) | Low | 1-2 |

| Script-driven | Automation, repeatable tasks | Medium | 3+ |

| Knowledge-intensive | Expert domain, multi-phase workflow | High | 5+ |

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

| Condition | On Failure |

|-----------|------------|

| Pre-invocation check passed | Fix parameters, retry |

| Post-invocation check passed | Log warning, retry |

Phase 4: Quality Validation + User Confirmation

Goal: Ensure output meets quality standards and user needs.

4.1 Structural Validation Checklist

| Check | Criteria |

|-------|----------|

| Frontmatter | Has name + description, valid YAML |

| Name | hyphen-case, ≤64 chars, matches directory |

| Description | Third person, 3-5 triggers, has "Use when" + "Not for" |

| Body length | < 500 lines (warn at 500, error at 800) |

| No angle brackets | Description has no < or > |

| References used | Detailed content in references/, not SKILL.md body |

| Output Contract | Defined what the skill produces |

| Decision Tree | AI knows "what situation → which action" |

4.2 Portability Checklist

| Check | Criteria |

|-------|----------|

| No hardcoded paths | No absolute paths or project-specific directories |

| No hardcoded tool names | Uses generic tool categories, not specific MCP servers |

| No project-specific context | Works without knowledge of a specific codebase |

| Synthetic examples | Examples are self-contained, not from a real project |

| Platform-agnostic | Works in any AI coding assistant environment |

4.3 User Final Confirmation

-> references/user-confirmation-protocol.md

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

GATE: Delivery Gate

| Condition | On Failure |

|-----------|------------|

| Validation checks pass | Fix and re-validate |

| User explicitly confirms | Fix and re-confirm |

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

| Condition | On Failure |

|-----------|------------|

| Score + analysis documented | Complete before closing |

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

| Item | Constraint |

|------|------------|

| name | hyphen-case, ≤64 chars, must match directory name |

| description | No < >, ≤1024 chars, third person, 3-5 triggers |

| license | Optional, license name or reference to bundled file |

| compatibility | Optional, ≤500 chars, environment requirements |

| allowed-tools | Optional, space-delimited tool names |

| SKILL.md body | < 500 lines recommended, hard limit 800 |

| Universality | No project paths, no hardcoded tool names, portable examples |

Output Contract

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

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

Gate System Summary

| Gate | Phase | Pass Condition | On Failure |

|------|-------|----------------|------------|

| Hypothesis Validation | 0 | ≥1 hypothesis confirmed by user | Keep asking |

| User Confirmation | 1 | User explicitly confirms requirements | Redo mining |

| Knowledge Freshness | 2 | Source < 1 year old | Re-acquire |

| Knowledge Accuracy | 2 | Official + 2 independent sources | Cross-validate |

| Knowledge Completeness | 2 | Core 100%, scenarios 80%+ | Supplement |

| Knowledge Fusion | 2 | Own vs new knowledge compared | Must compare |

| Writing Gate | 3 | Pre/post invocation checks pass | Fix and retry |

| Delivery Gate | 4 | Scripts pass + user confirms | Fix and redo |

| Reflection Complete | 5 | Score + analysis done | Complete it |

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

| File | Purpose | Phase |

|------|---------|-------|

| hypothesis-ladder-for-skills.md | Hypothesis generation + 5 Whys | 0 |

| skill-discovery-protocol.md | Skill discovery (reuse-first) | 0 |

| task-narrowing-framework.md | Task narrowing (5-layer) | 0 |

| requirement-elicitation-protocol.md | Requirement elicitation | 1 |

| user-requirement-validation.md | Requirement validation | 1 |

| user-confirmation-protocol.md | User confirmation template | 1, 4 |

| skill-type-taxonomy.md | Skill type taxonomy | 1 |

| knowledge-acquisition-guide.md | Research protocol + 4-layer gate | 2 |

| knowledge-validation-checklist.md | Knowledge validation | 2 |

| deep-research-methodology.md | Deep research + domain expertise | 2 |

| skill-templates.md | Skill structure templates | 3 |

| writing-style-guide.md | Writing standards + style | 3 |

| universality-guide.md | Portability guide | 3 |

Supporting References

| File | Purpose |

|------|---------|

| non-technical-methodology-research.md | Non-technical methodology |

| methodology-seed-database.md | Methodology seed database |

| learn-from-github-protocol.md | Learn from GitHub protocol |

| domain-expertise-protocol.md | Domain expertise protocol |

| docs-generation-workflow.md | Docs generation workflow |

| examples.md | Complete examples + patterns |

| patterns.md | Workflow patterns |

| troubleshooting.md | Common issues and fixes |

| official-best-practices.md | Anthropic official guidelines |

Official Resources

| Resource | URL |

|----------|-----|

| AgentSkills.io | https://agentskills.io/ |

| Skills Overview | https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview |

| Best Practices | https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices |

| Anthropic Skills Repo | https://github.com/anthropics/skills |