스킬 작성 컨벤션

03-skills/ 하위 모든 스킬 파일(SKILL.md)에 적용되는 바인딩 규칙. 재사용 코드 컨벤션(docs/rules/reusable-code.md)과 동일한 체계(포지셔닝 → 규칙 → 체크리스트)로 구성합니다.

Section 0: 포지셔닝

기존 자료와의 관계

적용 범위

• 필수 적용: 03-skills/ 하위 모든 SKILL.md
• 권장 적용: 프로젝트별 .claude/skills/ 하위 스킬 파일
• 적용 제외: 00-community-reference/ 하위 문서 (외부 참조 자료)

Section 1: Frontmatter

필수 필드

권장 필드

선택 필드

description 작성 패턴

{기능 설명}. {핵심 동작 나열}. "{한국어 트리거 1}", "{한국어 트리거 2}", "{영어 트리거}" 요청 시 사용.

예시:

description: 코드 컨벤션 검증 + 조건부 자기반성 스킬. 규칙 기반 능동 스캔, 자동 수정, 임계값 초과 시 에이전트 자동 발동. "컨벤션 검사", "코딩 규칙 검증", "convention check", "코드 스타일 점검" 요청 시 사용.

필수 요소:

1. 기능 한 줄 요약
2. 한국어 트리거 키워드 2개 이상
3. 영어 트리거 키워드 1개 이상 (또는 스킬명 자체)

Section 2: 파일 구조

표준 섹션 순서

SKILL.md의 섹션은 아래 순서를 따릅니다. 모든 섹션이 필수는 아니며, 스킬 복잡도에 따라 선택합니다.

Phase 구조 규칙

• Phase 번호는 0부터 시작 (Phase 0 = 컨텍스트 탐지)
• 각 Phase 내부 Step은 ### Step N-M: {단계명} 또는 ### N-M. {단계명} 형식
• 각 Step은 구체적 도구 호출 또는 액션을 명시

줄 수 규칙

500줄 초과 시: 핵심 워크플로우만 SKILL.md에 유지하고, 상세 규칙/패턴/데이터는 references/로 분리합니다. SKILL.md에서 references/{파일}.md 참조 형태로 연결합니다.

Section 3: Input/Output 계약

Input Envelope (인수 테이블)

인수가 있는 스킬은 반드시 인수 테이블을 포함합니다:

## 인수 처리

사용자가 제공한 인수: $ARGUMENTS

| 인수 | 설명 |
|------|------|
| (없음) | 기본 동작 설명 |
| `--flag` | 플래그 설명 |
| `<path>` | 위치 인수 설명 |

Output Envelope

스킬 출력에 포함해야 하는 4가지 요소:

Section 4: 관계 선언

관계 유형

테이블 형식

## 관련 스킬/에이전트

| 도구 | 역할 | 관계 |
|------|------|------|
| `/kdygenesis` | 메타 오케스트레이션 | Trigger (kdygenesis → 이 스킬) |
| `code-reviewer` | 코드 품질 분석 | Invoke (조건부) |
| `/kdypick` | 재사용 코드 적용 | Recommend |

Section 5: 네이밍

스킬명

파일명

• 메인 파일: SKILL.md (대문자)
• 참조 파일: kebab-case (rule-registry.md, library-selection-guide.md)

주석 언어

• 한국어 사용 (에러 메시지 문자열은 영어 허용)
• frontmatter의 description 내 트리거 키워드는 한/영 혼합

Section 6: 변경 관리

적용 이력 섹션

컨벤션 문서 자체의 변경 이력을 기록합니다:

frontmatter 변경 시 동기화 규칙

스킬의 name 또는 description을 변경한 경우:

1. CLAUDE.md의 스킬 테이블 갱신 (또는 /kdyupdate 실행)
2. _COMPONENT_MAP.md의 관련 노드 갱신 (또는 /inception 실행)
3. 해당 스킬을 참조하는 다른 스킬/에이전트의 관계 테이블 확인

Section 7: 품질 체크리스트

생성 시 체크리스트 (8항목)

리뷰 시 체크리스트 (5항목)

Section 8: 경로 이식성 (Path Portability)

스킬이 여러 머신에서 동작하도록 하드코딩된 절대 경로를 금지합니다.

8.1 절대 경로 금지 규칙

8.2 GENERAL_PRO 표준 결정 패턴

00 general-pro 경로를 참조하는 스킬은 ## 기본 경로 섹션에 아래 패턴을 포함해야 합니다:

GENERAL_PRO 결정 순서:
1. 환경변수 GENERAL_PRO_PATH
2. CWD가 00-general-pro* 내부이면 해당 루트
3. ~/{develop,dev}/00-general-pro-web 존재 탐색
4. 실패 시 AskUserQuestion: "00-general-pro-web 경로를 입력해주세요"

GENERAL_PRO = {결정된 경로}

8.3 홈 디렉토리 규칙

• C:\Users\<username>\.claude\ → ~/.claude/
• Git Bash와 Claude Code 모두 ~ 확장을 지원함

8.4 사용 예시 플레이스홀더

예시 코드에서 사용자 프로젝트 경로를 보여줄 때는 {프로젝트 경로} 또는 {DEV_DIR} 플레이스홀더를 사용합니다:

# 좋은 예
/kdyextract {프로젝트 경로}/my-project

# 나쁜 예
/kdyextract F:\11_dev\my-project

Section 9: Superpowers 연계

9.1 목적

superpowers 플러그인의 프로세스 스킬은 세션 레벨에서 동작하지만, 커스텀 스킬이 Skill 도구로 로드되면 자연 발동이 차단됨. 관련 superpowers 원칙을 스킬 내에 명시하여 품질 게이트를 보장한다.

9.2 섹션 위치

SKILL.md 표준 섹션 순서에서 ## 예외사항 바로 앞에 배치:

... → Phase N → Superpowers 연계 → 예외사항 → 관련 스킬/에이전트

9.3 테이블 형식

## Superpowers 연계

> 이 스킬 실행 중 아래 superpowers 원칙을 적용한다.

| 원칙 | 적용 시점 | 적용 방법 |
|------|----------|----------|
| `verification-before-completion` | Phase N 완료 시 | {구체적 검증 방법} |
| `systematic-debugging` | 에러 발생 시 | {구체적 진단 순서} |

kdyswarm 위임 조건이 있는 경우:

### kdyswarm 위임 조건

> 다음 조건이 모두 충족될 때 `/kdyswarm`으로 위임을 권장한다:
> - {조건 1}
> - {조건 2}

9.4 적용 대상 판별

9.5 kdyswarm 위임 조건

대규모 병렬 구현이 필요한 스킬에만 조건부 포함. 조건 미충족 시 포함 금지.

9.6 적용 제외 기준

다음 유형의 스킬은 Superpowers 연계 섹션을 포함하지 않는다:

• 순수 문서화/세션 프로토콜 스킬 (cs, kdyplanon)
• 단순 파일 작업 스킬 (kdyclean, kdyupdate, inception)
• 이미지 프롬프트 전용 스킬 (kdyimagemid, kdyimageanti)
• 설정 관리 스킬 (kdymcp)
• 특수 배포 스킬 (polnetuploadset)

적용 이력