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