Skill Factory - High-Quality Skill Creation System

Skill Metadata

Field	Value
Version	2.1.0
Tier	CC (Claude Code Meta)
Auto-load	Proactively when building Skills
Purpose	Interactive discovery → Web research → Skill generation

---

What It Does

Interactive discovery, web research, continuous updates를 통한 고품질 Claude Code Skill 생성 및 유지관리 시스템을 제공합니다.

Core capabilities:

• ✅ Interactive user surveys via moai-alfred-ask-user-questions
• ✅ Web research for latest information (WebFetch/WebSearch)
• ✅ Skill analysis and update recommendations
• ✅ Official documentation validation
• ✅ Progressive Disclosure pattern
• ✅ Multi-model compatibility testing

---

When to Use

• 새로운 Skill 패키지를 생성할 때
• 최신 best practices와 공식 문서를 조사할 때
• 기존 Skill을 분석하고 업데이트할 때
• Skill generation workflow를 orchestrate할 때

---

Core Principles

1. Conciseness Over Completeness

• SKILL.md should stay under 500 words
• Trust that Claude is already intelligent—provide guidance, not lectures
• Reference patterns, provide decision trees, link to supporting files

2. Appropriate Freedom Levels

Freedom Level	When to Use	Content Style
High	Flexible, creative work	Principles, trade-offs, considerations
Medium	Standard patterns exist	Pseudocode, flowcharts, annotated code
Low	Deterministic, error-prone	Specific scripts with error handling

3. Three-Level Progressive Disclosure

Level 1: Metadata (Always Active)
├── name, description, allowed-tools
└── ~100 tokens total
    ↓
Level 2: Instructions (On Demand)
├── SKILL.md main body
└── Loads when Claude recognizes relevance
    ↓
Level 3: Resources (As Needed)
├── reference.md, examples.md
└── Consumed when explicitly referenced

---

Quick Start: Creating a Skill

5-Step Process (Total: ~2 hours)

1. Define Problem (10 min): What gap does this Skill fill?
2. Design Metadata (10 min): Name (gerund + domain), description, allowed-tools
3. Structure Content (30 min): High (20%) + Medium (50%) + Low (30%) freedom
4. Add Examples & References (30 min): 3-4 examples, detailed reference
5. Validate & Test (20 min): CHECKLIST.md, multi-model testing

---

YAML Metadata Requirements

Frontmatter Structure

---
name: "Skill Name"
description: "What it does and when to use it"
allowed-tools: "Tool1, Tool2, Tool3"
---

Field Specifications

name (Required):

• Max 64 characters
• Format: Gerund (action verb) + domain
• Example: "Processing CSV Files with Python"

description (Required):

• Max 1024 characters
• Format: Third person, action-oriented
• Must include: capabilities + trigger scenarios + 3+ keywords
• Critical: Use "Use when" pattern with 3-5 trigger keywords
• For complete description writing guidelines: See Description Writing Standards

allowed-tools (Recommended):

• Minimal principle: Only tools actually used
• Format: Comma-separated list
• Example: "Read, Write, Edit, Bash(git:*)"

Detailed metadata guide: See METADATA.md

---

File Organization

Recommended Structure

skill-name/
├── SKILL.md                    # Main instructions (~500 words)
├── reference.md                # Detailed specs, API docs
├── examples.md                 # 3-4 real-world examples
├── CHECKLIST.md                # Quality validation (optional)
├── scripts/                    # Utility scripts
└── templates/                  # Reusable templates

Rules

Rule	Rationale
One level deep	Avoids nested discovery
Relative paths	Cross-platform compatibility
Forward slashes	Unix convention
<500 lines per file	Manageable context

Detailed organization guide: See STRUCTURE.md

---

Quality Validation

Before publishing, audit your Skill:

Metadata Completeness

• name ≤ 64 characters, gerund format
• description ≤ 1024 chars, includes 3+ triggers
• allowed-tools is minimal and justified

Content Quality

• SKILL.md ≤ 500 words
• All major concepts have examples
• Terminology is consistent
• Progressive Disclosure applied

Multi-Model Compatibility

• Haiku can understand concise examples
• Sonnet exploits full Skill capabilities
• Opus can extend patterns beyond examples

Complete validation checklist: See CHECKLIST.md

---

Advanced Features

Interactive Discovery

Use TUI surveys to clarify vague requirements and capture all user needs.

Detailed guide: INTERACTIVE-DISCOVERY.md

Web Research

Gather latest information, best practices, and official documentation.

Detailed guide: WEB-RESEARCH.md

Skill Update Advisor

Analyze existing Skills and propose updates based on latest information.

Detailed guide: SKILL-UPDATE-ADVISOR.md

---

Common Failure Modes

Issue	Root Cause	Fix
Not activating	Description too generic	Add 5+ specific keywords
Haiku ignores it	Examples too complex	Simplify pseudocode
Over-specifying	Too much low-freedom content	Increase principles
Scope creep	Covers too many domains	Split into 2-3 focused Skills
File too large	SKILL.md > 500 words	Move content to reference.md

---

Integration

With moai-alfred-skill-generator Sub-Agent

User: "/alfred:1-plan Create Skill for X"
    ↓
skill-generator Sub-Agent (ANALYZE → DESIGN → ASSURE phases)
    ↓
moai-skill-factory Skill (PRODUCE phase)
    ↓
Complete Skill package created

Tools Used

• WebFetch: Fetch official documentation
• WebSearch: Search for latest best practices
• Read/Glob: Review existing Skills
• Bash: Directory creation, file operations

---

Related Skills

• moai-alfred-ask-user-questions: Interactive user surveys (delegated)
• moai-alfred-skill-generator: Skill generation orchestrator

---

Complete Documentation

Core Guides:

• METADATA.md — Metadata authoring guide
• STRUCTURE.md — File organization patterns
• CHECKLIST.md — Pre-publication validation

Advanced Features:

• INTERACTIVE-DISCOVERY.md — TUI survey patterns
• WEB-RESEARCH.md — Web research strategies
• SKILL-UPDATE-ADVISOR.md — Skill analysis & updates

Workflows:

• SKILL-FACTORY-WORKFLOW.md — Complete workflow
• STEP-BY-STEP-GUIDE.md — Practical walkthrough

References:

• reference.md — Detailed API reference
• examples.md — Real-world case studies
• EXAMPLES.md — Additional examples

---

Key Differentiator: User-centric + research-driven + always-current + delegation-first orchestration

---

End of Skill | Refactored 2025-10-27