skill-expert-skills

Creates, optimizes, validates, and packages AI Agent Skills (SKILL.md format). Mandatory 6-Phase workflow with quality gates: Phase 0: Task Classification +...

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