setup-skills

목적

프로젝트마다 언어, 프레임워크, 도메인이 다르다. principles.md의 원칙은 범용적이지만, 실제 코드에 적용하려면 프로젝트 맥락에 맞는 구체적인 지침이 필요하다. 이 스킬은 추상적 원칙을 프로젝트 특화 스킬로 변환하는 다리 역할을 한다.

작업 순서

1단계: 원칙 문서 로드

이 스킬 파일과 같은 디렉토리의 references/ 아래 원칙 문서를 읽는다.

파일	내용
fundamentals.md	근본 원칙 — 모든 스킬이 참조하는 기반
code.md	자명한 코드 — 코드 레벨 실천
architecture.md	아키텍처 — 구조 설계 원칙
testing.md	테스트 전략 — 검증 원칙
ai-collaboration.md	AI 협업 — 하네스와 역할 분담

추천/생성할 스킬 유형에 따라 관련 원칙 문서만 참조한다. fundamentals.md는 항상 읽는다.

원칙은 언제든 수정될 수 있다. 이 스킬을 다시 실행하면 현재 원칙과 기존 커스텀 스킬 사이의 차이를 감지하고, 업데이트가 필요한 스킬을 알려준다.

2단계: 프로젝트 분석

프로젝트의 성격을 파악한다. 아래 항목을 순서대로 확인한다.

기본 정보 수집:

• 빌드 파일 / 패키지 매니저 (build.gradle.kts, package.json, Cargo.toml, pyproject.toml 등)
• 주요 언어 및 프레임워크
• 디렉토리 구조 (src 레이아웃, 모듈 구성)
• 기존 CLAUDE.md 유무 및 내용
• 기존 .claude/skills/ 유무

심화 분석 (스킬 2개 이상 구체적으로 추천할 수 있을 때까지):

• 코드 패턴 샘플링 (핵심 모듈 2~3개의 코드 스타일)
• 테스트 구조 및 컨벤션
• 에러 처리 패턴
• 상태 관리 방식

위 조건을 충족하면 분석을 멈추고 다음 단계로 진행한다. 확신이 없으면 사용자에게 질문한다.

3단계: 기존 스킬 점검 및 추천

먼저 프로젝트에 이미 생성된 커스텀 스킬(.claude/skills/)이 있는지 확인한다.

기존 스킬이 있는 경우: references/의 원칙 문서와 기존 스킬의 내용을 직접 비교한다. 아래 기준으로 모순을 찾는다.

• 스킬이 권장하는 패턴이 원칙 문서의 판단 기준과 반대인 경우
• 스킬이 언급하는 구조/컨벤션이 원칙 문서에서 삭제되거나 변경된 경우
• 원칙 문서에 새로 추가된 항목이 스킬에 반영되지 않아 스킬이 불완전해진 경우

해당하는 부분이 있으면 업데이트 대상으로 보고한다.

## 업데이트 필요 스킬

### 1. [스킬 이름]
- 현재 내용: [기존 스킬의 해당 부분]
- 변경된 원칙: [principles.md에서 바뀐 부분]
- 제안: [어떻게 수정해야 하는지]

그 다음, 분석 결과와 원칙 문서를 교차하여 이 프로젝트에 추가로 유용할 스킬 목록을 추천한다.

추천 형식:

## 추천 스킬 목록

### 1. [스킬 이름]
- 목적: 한 줄 설명
- 원칙 근거: principles.md의 어떤 원칙을 구체화하는지
- 예시 사용: 어떤 상황에서 쓰이는지

### 2. [스킬 이름]
...

추천 시 고려할 스킬 유형들:

유형	설명	원칙 연결
코드 리뷰	프로젝트 컨벤션에 맞는 리뷰 기준	명확성, 가독성, 심플함
테스트 생성	프로젝트 테스트 컨벤션에 맞는 테스트 작성	목적 기반 테스트, 모킹 최소화
아키텍처 검증	VSA 슬라이스 경계, 단방향 상태 등 구조 점검	아키텍처 원칙
에러 처리	프로젝트의 에러 처리 패턴에 맞는 가이드	대수적 타입, 명시적 에러
리팩토링	원칙에 맞지 않는 코드를 개선	전체 원칙
코드 생성	새 기능/모듈 생성 시 컨벤션 준수	자명한 코드, 아키텍처

이 목록은 예시다. 프로젝트 성격에 따라 전혀 다른 스킬이 필요할 수 있다. 게임 프로젝트라면 씬 구조 검증, 웹 프로젝트라면 API 엔드포인트 생성 등 도메인에 맞게 추천한다.

기존에 이미 있는 스킬과 중복되지 않도록 확인한다.

4단계: 스킬 생성

사용자가 추천 목록에서 생성을 요청하면, 해당 스킬을 프로젝트 내에 생성한다.

생성 위치: 프로젝트의 .claude/skills/ 디렉토리

스킬 작성 원칙:

• principles.md의 원칙을 해당 프로젝트의 언어/프레임워크 맥락으로 번역한다
• 추상적 지침("명확하게 작성하라")이 아니라 구체적 행동("변수명에 단위를 포함하라: timeMinutes")을 제시한다
• 프로젝트에서 실제로 사용하는 패턴을 예시로 포함한다
• 스킬은 독립적으로 동작해야 한다 — principles.md를 매번 참조하지 않아도 되도록 구체화한다

스킬 구조:

---
name: [스킬 이름]
description: [트리거 설명]
---

## 목적
[이 스킬이 왜 필요한지, 어떤 원칙을 구체화하는지]

## [프로젝트 특화 지침]
[구체적인 행동 규칙, 예시 포함]

5단계: 결과 보고

생성한 스킬의 경로와 요약을 보여준다.

## 생성 완료

- 경로: .claude/skills/[스킬명]/SKILL.md
- 목적: [한 줄 요약]
- 원칙 근거: [관련 원칙]

행동 원칙

• 프로젝트 분석이 불충분하면 사용자에게 질문한다 — 추측보다 확인이 명확하다
• 추천을 먼저 보여주고, 사용자가 선택하면 생성한다 — 사람이 결정한다 (AI 협업 원칙)
• 이미 존재하는 스킬과 중복 생성하지 않는다
• 생성된 스킬은 principles.md 없이도 독립적으로 동작할 수 있을 만큼 구체적이어야 한다