Skill Builder — 스캐폴딩 및 생성

프로세스

1단계: 입력 수집

무엇을 기반으로 구축할지 결정합니다:

계획 문서: /skill-forge plan의 출력 (선호)
설명: 스킬에 대한 자연어 설명
기존 스킬: 기반으로 사용할 스킬의 경로

계획이 없으면 간단한 계획 수립 패스를 실행합니다 (3가지 핵심 질문):

이 스킬은 무엇을 하나요? (1-2문장)
어떤 명령어가 있어야 하나요? (목록)
스크립트나 외부 도구가 필요한가요? (예/아니오)

2단계: 프론트매터 생성

가장 중요한 단계입니다. description 필드가 활성화를 결정합니다.

설명 작성을 위한 프레임워크:

[능력 기술] + [상세 기능] + [트리거 구문]

규칙:

총 1024자 미만
XML 꺾쇠괄호(< >) 없음
사용자가 말할 5-10개의 트리거 구문 포함
관련 파일 형식이 있으면 언급
과잉 트리거 위험이 있을 경우 부정 트리거 추가

전체 프레임워크는 references/description-guide.md를 참조하세요.

3단계: 메인 SKILL.md 작성

다음 템플릿에 따라 본문을 구성합니다:

# [스킬 이름] -- [태그라인]

[1-2문장 개요]

## 빠른 참조

| 명령어 | 기능 |
|---------|------|
| /name cmd1 | 설명 |
| /name cmd2 | 설명 |

## 오케스트레이션 로직

[명령어가 서브 스킬로 라우팅되는 방식]
[조건부 라우팅을 위한 결정 트리]

## [도메인별 섹션]

[핵심 규칙, 임계값, 품질 게이트]

## 참조 파일

[온디맨드 참조 파일 목록]

## 서브 스킬

[한 줄 설명이 포함된 서브 스킬 목록]

중요 SKILL.md 규칙:

500줄 미만
5000토큰 미만
실행 가능한 지침 (모호하지 않음)
오류 처리 포함
참조는 인라인으로 포함하지 말고 링크

4단계: 서브 스킬 생성 (Tier 3-4)

각 서브 스킬에 대해 다음 형식의 SKILL.md를 생성합니다:

---
name: parent-child
description: >
  [기능 설명]. 사용자가 "[트리거 1]", "[트리거 2]",
  "[트리거 3]", 또는 "[트리거 4]"라고 말할 때 사용합니다.
---

서브 스킬 본문 가이드라인:

하나의 워크플로우에 대한 자체 포함된 지침
다른 서브 스킬은 이름으로 상호 참조 (내용을 인라인으로 포함하지 않음)
부모 스킬의 references/ 디렉토리에 있는 공유 파일 참조
명시적인 입력/출력 정의 포함

5단계: 스크립트 생성 (Tier 2-4)

각 스크립트:

#!/usr/bin/env python3
"""
목적: [이 스크립트의 기능]
입력: [예상 입력 형식]
출력: [예상 출력 형식]
사용법: python scripts/script_name.py [인수]
"""

import argparse
import json
import sys
from typing import Any

def main(args: argparse.Namespace) -> dict[str, Any]:
    """주 실행 함수."""
    # 입력 검증
    # 작업 수행
    # 구조화된 출력 반환
    pass

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="[스크립트 설명]")
    parser.add_argument("input", help="[입력 설명]")
    parser.add_argument("--output", "-o", help="출력 파일 경로")
    args = parser.parse_args()

    try:
        result = main(args)
        print(json.dumps(result, indent=2))
    except Exception as e:
        print(json.dumps({"error": str(e)}), file=sys.stderr)
        sys.exit(1)

스크립트 규칙:

하나의 스크립트, 하나의 책임
argparse를 사용한 CLI 인터페이스
구조화된 JSON 출력
명확한 오류 메시지
가능하면 stdlib 외부 의존성 없음

6단계: 참조 파일 생성

각 참조 파일:

하나의 주제에 집중
200줄 미만
구체적인 예제 포함
임계값 및 사양에는 표 사용
부모 SKILL.md에 "Load on-demand"라고 표시

7단계: 에이전트 정의 생성 (Tier 4)

에이전트 파일은 YAML 프론트매터를 사용합니다 (스킬과 다름):

---
name: [스킬-이름]-[역할]
description: >
  [이 에이전트가 분석하는 내용].
  <example>사용자 말: "[트리거]"</example>
model: inherit
color: blue
tools:
  - Read
  - Grep
  - Glob
---

당신은 [역할] 전문가입니다.

## 당신의 역할
[이 에이전트가 하는 일]

## 프로세스
1. [단계...]

## 출력 형식
구조화된 마크다운으로 결과 및 권장 사항을 반환합니다.

스킬과의 주요 차이점: 에이전트 name은 3-50자이며, 설명은 <example> 블록을 사용할 수 있고, 에이전트 전용 필드에는 tools, color, permissionMode, maxTurns, memory가 포함됩니다. 본문은 시스템 프롬프트가 됩니다 (2인칭).

8단계: 설치 스크립트 생성

파일을 ~/.claude/skills/ 및 ~/.claude/agents/에 복사하는 install.sh를 생성합니다.

9단계: 검증

생성된 스킬에 대해 python scripts/validate_skill.py <path>를 실행합니다. 메인 SKILL.md의 모든 품질 게이트를 확인합니다.

10단계: 결과 요약

사용자에게 다음을 제공합니다:

생성된 파일 트리
주요 파일 및 그 목적
설치 지침
제안된 테스트 쿼리 (트리거되어야 할 3개, 트리거되지 말아야 할 3개)
다음 단계 (테스트, 반복, 게시)

스캐폴딩 명령어

빠른 스캐폴딩을 위해 다음을 사용합니다:

python scripts/init_skill.py <스킬-이름> --tier <1-4> --path <출력-경로>

전체 디렉토리 구조를 플레이스홀더 콘텐츠와 함께 생성합니다.

skill-forge-build