moai-core | Skill creation based on the revfactory/harness methodology
Overview
This skill converts the 6-Phase skill creation workflow of the harness open-source project to fit the MoAI cowork-plugins context. It reduces quality variance in manual skill authoring and produces consistently high-quality skills through a systematic creation process.
Name History: Up to v1.3.x,
skill-forgethe skill provided asskill-builderwas renamed toskill-builderin v1.5.x. The alias is not maintained, and all references must be updated to
Trigger Keywords
skill creation skill authoring skill-builder create new skill add skill new skill harness workflow
Workflow
Phase 1: Requirements → 사용자 의도 분석, 트리거 키워드 정의
Phase 1.5: Research → 공식 자료·베스트 프랙티스 외부 조사 (WebSearch + Context7) ★ v1.6.0
Phase 2: Architecture → 에이전트 패턴 선택 (6종 중 매핑)
Phase 3: Skill Draft → skill-template 기반 SKILL.md 초안 + ## 출처 섹션
Phase 4: Test Gen → 테스트 프롬프트 2-3개 + 기대 출력 정의
Phase 5: Validation → 4차원 루브릭 스코어링 (skill-tester 본문 §스코어링 루브릭)
Phase 6: Review → 품질 게이트 통과 확인, 파일 배치
Execution Rules
Phase 1: Requirements (requirements analysis)
Extract skill requirements from the user's natural-language request.
Required items to collect:
| Item | Question | Example |
|---|---|---|
| Purpose | "What problem will this skill solve?" | "I want to automatically generate sales proposals" |
| Target plugin | "Which plugin should it be placed in?" | moai-business |
| Input | "What will the user input?" | Company name, target industry, product information |
| Output | "What deliverable is expected?" | Proposal DOCX file |
| Complexity | "How complex is the skill?" | Standard (50-150줄) |
Deliverable: Requirements document (in-memory, confirmed via AskUserQuestion)
Phase 1.5: Research (external material research) ★ New in v1.6.0
Research official materials, standard formats, and best practices in the skill domain to ensure the accuracy and authority of SKILL.md.
Research triggers (Phase 1.5 is mandatory if any of the following applies):
- Related to Korean laws/regulations or standard formats (tax, labor, contracts, hiring, medical, etc.)
- Use of external libraries, SDKs, APIs, or CLIs
- Domains requiring citation of global best practices (B2B SaaS, HR, BI, DevOps, etc.)
- Citation of quantitative figures, statistical data, or market size
Research procedure:
-
WebSearch 2-4 times (parallel recommended)
- Korean query 1-2 times:
"<도메인> <핵심 키워드> <연도>"format (e.g., "Korean Employment Procedure Act NCS 2026") - English query 1-2 times (when citing global best practices):
"<topic> best practice <year>"format - Check the recency of search results (prioritize materials within 2 years)
- Korean query 1-2 times:
-
Context7 MCP (when the skill relates to libraries, SDKs, or CLIs)
resolve-library-id→get-library-docsorder- Check latest API/CLI changes and deprecations
- Supplement training data cutoff
-
Official source whitelist by domain (preferred citations):
Domain Primary recommended sources Korean tax and finance National Tax Service nts.go.kr, HomeTax hometax.go.kr, DART dart.fss.or.kr Korean labor and employment Ministry of Employment and Labor moel.go.kr, NCS ncs.go.kr, Korea Labor Institute kli.re.kr Korean medical and health MFDS mfds.go.kr, Ministry of Health and Welfare mohw.go.kr, National Health Insurance Service nhis.go.kr Korean government support K-Startup k-startup.go.kr, BIZINFO bizinfo.go.kr Korean statistics and market KOSIS kosis.kr, Bank of Korea ECOS ecos.bok.or.kr Korean law National Law Information Center law.go.kr, Supreme Court Comprehensive Legal Information glaw.scourt.go.kr Global accounting standards K-IFRS, IFRS Foundation ifrs.org Global hiring regulations EEOC eeoc.gov, NYC Local Law 144, ISO 42001:2023 Global SaaS BP Official product documentation (HubSpot, Salesforce, Greenhouse, etc.) + industry-leading blogs -
Source preservation:
- Preserve URLs, publication dates, and key quoted sentences from research results in memory
- In Phase 3, SKILL.md
## 출처cite in the section as markdown hyperlink format - Quantitative figures must be cited inline with sources or
[추정]tag enforced
Deliverables: research notes (in memory, passed as Phase 3 input)
Prohibited:
- Citing quantitative figures without sources (must specify source or
[추정]tag) - Missing Korean official sources in Korean domain skills
- Not using Context7 MCP for library/SDK-related skills (when available)
- Citing outdated materials (if older than 3 years, re-search for the latest materials)
Skip conditions (Phase 1.5 may be omitted):
- Simple format conversion/text processing skills (no domain knowledge required)
- User explicitly
--skip-researchflag specified - Only minor improvements to existing cowork skills or trigger keyword adjustments
Phase 2: Architecture (architecture selection)
Select the optimal pattern among 6 agent patterns.
| Pattern | Application scenario | Skill example |
|---|---|---|
| Pipeline | Sequential processing, each step's output becomes the next input | docx-generator, blog |
| Fan-out/Fan-in | Parallel analysis then result integration | ux-designer, market-analysis |
| Expert Pool | Combining multi-domain expert knowledge | consulting-brief, startup-launchpad |
| Producer-Reviewer | Generation + quality review cycle | sales-playbook, copywriting |
| Supervisor | Orchestrating multiple expert skills | moai-business:ai-diagnostic, project |
| Hierarchical Delegation | Hierarchical decomposition of complex tasks | startup-launchpad |
Selection criteria: Judge based on the skill's number of workflow steps, whether parallelism is needed, and quality verification requirements.
Output: Selected pattern + rationale (1-2 sentences)
Phase 3: Skill Draft (skill draft generation)
skill-template Generate a SKILL.md draft based on the template.
Required application:
- Use the required section structure of skill-template
- Frontmatter는
name,descriptionInclude only (metadata prohibited) - Check that trigger keywords do not duplicate the existing 73 skills
- Include at least 2 usage examples
- Specify before/after/alternative relationships in the related skills section
## 출처Section mandatory: Specify URLs and citations collected in Phase 1.5 as markdown hyperlinks (skills subject to Phase 1.5)- Quantitative value citation rule: All numerical values must have inline source attribution or
[추정]tag
Reference: moai-core/skills/skill-tester/SKILL.md §Scoring rubric (single source of quality criteria)
Reference: moai-core/skills/skill-template/SKILL.md (template)
Output: <target-plugin>/skills/<skill-name>/SKILL.md draft
Phase 4: Test Generation (test generation)
Generate test cases for skill validation.
Test composition:
tests:
- name: "happy-path"
prompt: "<대표적인 사용 프롬프트>"
expected_output:
format: "<출력 형식>"
contains: ["<필수 포함 내용>"]
not_contains: ["<금지 내용>"]
- name: "edge-case"
prompt: "<경계 조건 프롬프트>"
expected_output:
handles_gracefully: true
fallback_behavior: "<설명>"
- name: "complex-input"
prompt: "<복잡한 입력 프롬프트>"
expected_output:
completeness: "모든 요구사항 충족"
Output: <skill-dir>/tests/test-cases.yaml
Phase 5: Validation (quality validation)
Evaluate the skill with a 4-dimension rubric.
| Dimension | Weight | Evaluation |
|---|---|---|
| Correctness | 30% | Purpose achievement |
| Completeness | 25% | Edge case coverage |
| Clarity | 25% | User comprehensibility |
| Efficiency | 20% | Quality relative to tokens |
Pass criteria: Weighted average >= 0.70, all dimensions >= 0.50
If not met: Return to Phase 3 and supplement the deficient dimension(s). Repeat up to 3 times.
Reference: moai-core/skills/skill-tester/SKILL.md §Scoring rubric (anchor score table + evaluation procedure)
Phase 6: Review (final review)
Run the final checklist before distribution.
Checklist:
- Frontmatter format compliance (only name, description; no metadata)
- All required sections exist (overview, triggers, workflow, examples, output, cautions, related skills)
- Trigger keywords do not duplicate existing skills
- Guide whether plugin.json version needs updating
- Skill chain relationships match the project's skill chain definition (if applicable)
- Test cases have been generated
- Rubric score passes 0.70 or higher
-
## 출처Section exists (skills subject to Phase 1.5,--skip-researchif unspecified) - All quantitative values have sources or
[추정]tag (skills subject to Phase 1.5)
Placement: <target-plugin>/skills/<skill-name>/SKILL.md Place the final file in
Usage examples
Example 1: Creating a new skill
"Create a sales proposal auto-generation skill in moai-business. When company name and target company are entered, a proposal DOCX should be produced"
Example 2: Creating a Vibe gap skill
"Create a UX design analysis skill in moai-product with skill-builder. Refer to the Vibe Designing feature"
Output format
| Deliverables | Location | Description |
|---|---|---|
| SKILL.md | <plugin>/skills/<name>/SKILL.md |
Completed skill definition |
| test-cases.yaml | <plugin>/skills/<name>/tests/ |
Test cases |
| score-report | In-memory | Rubric score report |
Precautions
- Not for modifying existing skills, creating new skillsused only for
- Plugin directory (
moai-*) must be checked in advance for existence - After skill creation, plugin.json version bump is handled collectively in the release process
- If trigger keywords overlap, the existing skill's description must be checked to clearly distinguish them
Related skills
| Skill | Relationship | Description |
|---|---|---|
| skill-template | before | Base skill that provides the template structure |
| skill-tester | after | Test execution + rubric scoring of the generated skill |
| ai-slop-reviewer | after | AI pattern review of the skill body (optional) |
Related commands
| Command | Description |
|---|---|
/harness |
Automatic new→test→review chain (orchestration of this skill + skill-tester + ai-slop-reviewer) |
Source: revfactory/harness 6-Phase workflow (Apache 2.0) + MoAI adaptation
Changelog
- 1.6.0 (2026-05-01): Phase 1.5 Research newly established — external source research (WebSearch·Context7) made mandatory, domain-specific official source whitelist added,
## 출처section made mandatory + quantitative figure sources/[추정]tag enforced - 1.5.x: skill-forge → skill-builder renamed
- Previously: absorbed harness 6-Phase workflow