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)

Define Problem (10 min): What gap does this Skill fill?
Design Metadata (10 min): Name (gerund + domain), description, allowed-tools
Structure Content (30 min): High (20%) + Medium (50%) + Low (30%) freedom
Add Examples & References (30 min): 3-4 examples, detailed reference
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

moai-cc-skill-factory

SKILL.md.claude/skills/moai-cc-skill-factory