moai-cc-skill-factory

Create and maintain high-quality Claude Code Skills through interactive discovery, web research, and comprehensive description writing standards. Use when building new Skills, researching latest best practices, updating existing Skills, writing skill descriptions with proper trigger keywords, or generating Skill packages backed by official documentation and real-world examples.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️3downloads

When & Why to Use This Skill

The Skill Factory is a comprehensive system designed to create, optimize, and maintain high-quality Claude Code Skills. It leverages interactive discovery and web research to generate standardized skill packages that adhere to official documentation, ensuring optimal agent performance through structured metadata and progressive disclosure patterns.

Use Cases

  • 1. Automated Skill Creation: Streamline the development of new Claude Skills by researching best practices and generating standardized SKILL.md files with optimized trigger keywords.
  • 2. Skill Maintenance and Auditing: Analyze existing skill packages to identify outdated patterns and provide actionable recommendations for updates based on the latest Claude capabilities.
  • 3. Documentation Standardization: Ensure all agent skills follow a consistent structure (metadata, instructions, and resources) to improve discoverability and multi-model compatibility.
  • 4. Quality Validation: Use built-in checklists to audit skill metadata length, tool justification, and content quality before deployment to ensure reliable agent behavior.
namemoai-cc-skill-factory
version2.2.0
created2025-10-22
updated2025-11-05
statusactive
descriptionCreate and maintain high-quality Claude Code Skills through interactive discovery, web research, and comprehensive description writing standards. Use when building new Skills, researching latest best practices, updating existing Skills, writing skill descriptions with proper trigger keywords, or generating Skill packages backed by official documentation and real-world examples.
keywords[skill-creation, claude-skills, best-practices, web-research, interactive-discovery, skill-updates, description-writing, metadata-standards]

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

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

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

Complete Documentation

Core Guides:

Advanced Features:

Workflows:

References:


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


End of Skill | Refactored 2025-10-27