kdysync — 프로젝트↔글로벌 스킬 동기화

프로젝트 원본(03-skills/)과 글로벌 Claude 스킬 폴더(~/.claude/skills/)간 파일을 비교하고 동기화합니다. 프로젝트 폴더를 source of truth(원본 우선)로 취급하며, 비파괴적으로 복사/덮어쓰기만 수행합니다.

인수 처리

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

기본 경로

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

PROJECT_SKILLS = {결정된 경로}/03-skills
GLOBAL_SKILLS  = ~/.claude/skills
EXCLUDE_DIRS   = 00-community-reference

Phase 0: 경로 검증

양쪽 디렉토리의 존재 여부를 확인합니다.

0.1 프로젝트 스킬 디렉토리 확인

Bash: ls "$PROJECT_SKILLS" > /dev/null 2>&1

존재하지 않으면 에러 메시지를 출력하고 종료합니다:

"프로젝트 스킬 디렉토리를 찾을 수 없습니다: $PROJECT_SKILLS"

0.2 글로벌 스킬 디렉토리 확인

Bash: ls "$GLOBAL_SKILLS" > /dev/null 2>&1

존재하지 않으면 생성 여부를 사용자에게 확인합니다:

"글로벌 스킬 디렉토리가 없습니다. 생성할까요? $GLOBAL_SKILLS"

승인 시 mkdir -p로 생성합니다.

Phase 1: 인벤토리 수집

양쪽 스킬 디렉토리의 파일 목록을 재귀적으로 수집합니다.

1.1 프로젝트 스킬 목록 수집

Glob: 03-skills/*/SKILL.md
Glob: 03-skills/*/references/*.md
Glob: 03-skills/*/phases/*.md
Glob: 03-skills/*/strategies/*.md

00-community-reference/ 하위 파일은 제외합니다. README.md 파일도 제외합니다.

각 스킬 디렉토리에 대해 다음을 기록합니다:

• 디렉토리명 (스킬명)
• 포함된 파일 목록 (SKILL.md, references/.md, phases/.md 등)

1.2 글로벌 스킬 목록 수집

Glob: ~/.claude/skills/*/SKILL.md
Glob: ~/.claude/skills/*/references/*.md
Glob: ~/.claude/skills/*/phases/*.md
Glob: ~/.claude/skills/*/strategies/*.md

동일한 방식으로 파일 목록을 기록합니다.

1.3 인벤토리 출력

## 인벤토리

### 프로젝트 스킬 (N개 디렉토리, M개 파일)
| # | 스킬 | 파일 수 |
|---|------|---------|
| 1 | cs | 1 |
| 2 | kdyextract | 4 |
| ... | ... | ... |

### 글로벌 스킬 (N개 디렉토리, M개 파일)
| # | 스킬 | 파일 수 |
|---|------|---------|
| 1 | cs | 1 |
| 2 | kdyextract | 3 |
| ... | ... | ... |

Phase 2: 차이 분석

프로젝트와 글로벌 파일을 1:1로 비교하여 5가지로 분류합니다.

2.1 비교 대상 매칭

동일한 상대 경로({스킬명}/SKILL.md, {스킬명}/references/xxx.md)를 기준으로 양쪽 파일을 매칭합니다.

2.2 파일 비교 방법

각 매칭된 쌍에 대해:

Bash: diff "$PROJECT_SKILLS/{상대경로}" "$GLOBAL_SKILLS/{상대경로}" > /dev/null 2>&1

내용이 다른 경우 타임스탬프를 비교합니다:

Bash: stat -c %Y "$PROJECT_SKILLS/{상대경로}" "$GLOBAL_SKILLS/{상대경로}"

Windows 환경에서는 stat --format=%Y 대신 다음을 사용합니다:

Bash: date -r "$PROJECT_SKILLS/{상대경로}" +%s
Bash: date -r "$GLOBAL_SKILLS/{상대경로}" +%s

2.3 5가지 분류

2.4 차이 리포트 출력

## 차이 분석 결과

### 요약
| 분류 | 파일 수 |
|------|---------|
| PROJECT_ONLY | N |
| GLOBAL_ONLY | N |
| PROJECT_NEWER | N |
| GLOBAL_NEWER | N |
| IDENTICAL | N |
| **합계** | **N** |

### 상세

#### PROJECT_ONLY (글로벌에 없음)
| # | 파일 |
|---|------|
| 1 | kdysync/SKILL.md |

#### GLOBAL_ONLY (프로젝트에 없음)
| # | 파일 |
|---|------|
| (없음) |

#### PROJECT_NEWER (프로젝트가 최신)
| # | 파일 | 프로젝트 수정일 | 글로벌 수정일 |
|---|------|----------------|-------------|
| 1 | kdyextract/SKILL.md | 2026-02-19 | 2026-02-18 |

#### GLOBAL_NEWER (글로벌이 최신 — 주의)
| # | 파일 | 프로젝트 수정일 | 글로벌 수정일 |
|---|------|----------------|-------------|
| (없음) |

#### IDENTICAL (동일)
N개 파일 일치.

--scan-only 인수 시: 이 리포트를 출력하고 종료합니다.

Phase 3: 사용자 확인

--auto 또는 --scan-only가 아닌 경우, AskUserQuestion으로 동기화 방향과 범위를 확인합니다.

3.1 동기화 방향 선택

3.2 GLOBAL_NEWER 파일 처리

GLOBAL_NEWER 파일이 존재하고 프로젝트→글로벌 방향을 선택한 경우, 추가 확인합니다:

"글로벌에서 더 최신인 파일이 N개 있습니다. 프로젝트 버전으로 덮어쓸까요?"

3.3 GLOBAL_ONLY 파일 처리

GLOBAL_ONLY 파일이 존재하고 프로젝트→글로벌 방향을 선택한 경우:

"글로벌에만 존재하는 스킬이 N개 있습니다. 어떻게 처리할까요?"

3.4 --auto 모드

--auto 인수 시:

• 방향: 프로젝트→글로벌
• PROJECT_ONLY: 글로벌에 복사
• PROJECT_NEWER: 글로벌을 프로젝트 버전으로 덮어쓰기
• GLOBAL_NEWER: 건너뛰기 (안전 우선)
• GLOBAL_ONLY: 무시 (비파괴적)

3.5 --direction 인수

• --direction project-to-global: 프로젝트→글로벌 자동 선택 (사용자 확인은 유지)
• --direction global-to-project: 글로벌→프로젝트 자동 선택 (사용자 확인은 유지)

Phase 4: 동기화 실행 + 검증 + 보고서

4.1 디렉토리 생성

대상에 스킬 디렉토리가 없으면 생성합니다:

Bash: mkdir -p "$TARGET/{스킬명}"
Bash: mkdir -p "$TARGET/{스킬명}/references"  # 하위 디렉토리도 필요 시

4.2 파일 복사

Phase 3에서 확정된 파일 목록을 순차적으로 복사합니다:

Bash: cp "$SOURCE/{상대경로}" "$TARGET/{상대경로}"

각 파일 복사 후 진행 표시:

[N/M] 복사: {상대경로}

4.3 복사 검증

모든 복사가 끝난 후 diff로 원본과 대상의 일치를 검증합니다:

Bash: diff "$SOURCE/{상대경로}" "$TARGET/{상대경로}" > /dev/null 2>&1

불일치 파일이 있으면 경고를 출력합니다:

"검증 실패: {상대경로} — 원본과 대상이 일치하지 않습니다"

4.4 최종 보고서

## kdysync 동기화 완료

### 동기화 방향
프로젝트 → 글로벌 (또는 역방향/양방향)

### 동기화 통계
| 항목 | 수량 |
|------|------|
| 새로 복사 | N개 |
| 덮어쓰기 | N개 |
| 건너뛰기 | N개 |
| 검증 성공 | N/N개 |

### 복사된 파일
| # | 파일 | 액션 |
|---|------|------|
| 1 | kdysync/SKILL.md | 새로 복사 |
| 2 | kdyextract/SKILL.md | 덮어쓰기 |

### 건너뛴 파일
| # | 파일 | 사유 |
|---|------|------|
| 1 | ... | GLOBAL_NEWER (사용자 선택) |

### 다음 권장 작업
- `/kdyupdate` — 새 스킬을 CLAUDE.md 카탈로그에 등록
- `/inception` — 대규모 변경 시 의존성 맵 갱신

Superpowers 연계

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

예외사항

다음은 문제가 아닙니다:

• 00-community-reference/ 디렉토리가 글로벌에 없음 → 정상 (제외 대상)
• 글로벌에만 존재하는 스킬 → 다른 프로젝트에서 생성한 것일 수 있음 (비파괴적 유지)
• IDENTICAL 파일이 대다수 → 정상 (동기화가 잘 되어 있는 상태)

관련 스킬/에이전트

사용 예시

# 전체 스캔 + 사용자 확인 후 동기화 (기본: 프로젝트→글로벌)
/kdysync

# 차이 리포트만 출력 (파일 수정 없음)
/kdysync --scan-only

# 확인 없이 프로젝트→글로벌 자동 동기화
/kdysync --auto

# 글로벌→프로젝트 방향으로 동기화
/kdysync --direction global-to-project

# 프로젝트→글로벌 방향 명시 (기본값과 동일)
/kdysync --direction project-to-global

주의사항

1. 비파괴적 동기화: 기본적으로 삭제 없이 복사/덮어쓰기만 수행
2. 원본 우선 원칙: 프로젝트 폴더가 source of truth. 충돌 시 프로젝트 버전을 권장
3. 재귀적 비교: SKILL.md뿐 아니라 references/, phases/, strategies/ 등 하위 디렉토리 포함
4. 00-community-reference 제외: 이 디렉토리는 프로젝트 전용이므로 동기화 대상에서 항상 제외
5. GLOBAL_NEWER 안전 처리: --auto 모드에서 글로벌이 최신인 파일은 건너뜀 (데이터 손실 방지)
6. 멱등성: 동일 상태에서 여러 번 실행해도 결과가 같음
7. 파일 단위 동기화: 디렉토리 단위가 아닌 파일 단위로 비교·복사하여 정밀한 제어 가능