skill-expert-skills

---

name: skill-expert-skills description: | Creates, optimizes, validates, and packages AI Agent Skills (SKILL.md format).

Mandatory 6-Phase workflow with quality gates: Phase 0: Task Classification + Hypothesis Generation Phase 1: Deep Requirement Mining + 5 Whys Phase 2: Knowledge Acquisition + Validation Phase 3: Skill Writing + Quality Check Phase 4: Validation + User Confirmation Phase 5: Self-Reflection + Knowledge Precipitation

Use when: - Creating a new Skill (writing a SKILL.md) - Optimizing an existing Skill (structure, triggers, portability) - Validating a Skill package - Packaging or distributing a Skill

Not for: regular programming or business logic (use domain-specific skills). license: Apache-2.0 compatibility: Python 3.8+ for validation scripts allowed-tools: Read Write Bash Grep Glob metadata: version: 4.0.0 last_updated: 2026-03-06 enhancement: - v4.0 Added Fast Track Decision (Simple/Standard/Complex classification) - v4.0 Adopted reference pointer pattern (-> references/xxx.md) - v4.0 Added SKILL.md Positioning rules (NON-NEGOTIABLE) - v4.0 Added Conciseness Checklist (5-point) - v4.0 Consolidated references navigation (phase-based) - v4.0 Kept Definition of Done and Source Credibility Tiers

---

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 "" --root 
Initialize new skill
python scripts/init_skill.py  --path 
Validate (required before delivery)
python scripts/quick_validate.py 
python scripts/universal_validate.py 
Package for distribution (optional)
python scripts/package_skill.py  ./dist
Maintenance
python scripts/upgrade_skill.py 
python scripts/diff_with_official.py 
python scripts/analyze_trigger.py 

---

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 |