jun-claude-code 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jun-claude-code",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Claude Code configuration template - copy .claude settings to your project",
   "main": "dist/index.js",
   "bin": "dist/cli.js",

package/templates/global/CLAUDE.md

@@ -146,13 +146,15 @@ Plan 파일의 Context 섹션에 위 내용을 명시하여 작업 목적이 희
 
 ### Step 1.5.5: Plan 문서 생성 -- 필수
 
+> **`Planning` Skill (`skills/Planning/SKILL.md`)의 템플릿을 따라 작성한다.**
+
 계획이 확정되면 프로젝트의 `.claude/plan/` 폴더에 3가지 문서를 생성하세요:
 
-- [ ] `.claude/plan/plan.md` -- 전체 계획 (목적, 설계, 수정 파일 목록, TaskList 요약)
+- [ ] `.claude/plan/plan.md` -- 전체 계획 (목적, DB/API/FE 설계, 설계 결정과 차선책, TaskList 요약)
 - [ ] `.claude/plan/context.md` -- 맥락 (사용자 요청 원문, 비즈니스/기술적 배경, 탐색한 코드, 결정 사항)
 - [ ] `.claude/plan/checklist.md` -- 실행 체크리스트 (Phase별 체크리스트, Task별 세부 작업)
 
-각 문서에는 frontmatter(name, description, created)를 포함하세요.
+각 문서에는 frontmatter(name, description, created, status)를 포함하세요.
 이 문서들은 구현 중 맥락 유실 방지와 진행 추적에 활용됩니다.
 
 ### Step 1.6: 사용자 Confirm -- 필수

package/templates/global/agents/code-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: code-reviewer
-description: 코드 작성 완료 후 품질 검토 시 호출. CLAUDE.md/Skills 규칙 준수 확인, Critical/Warning 분류, lint 실행 및 수정 제안.
-keywords: [코드리뷰, 체크리스트, lint, 규칙검증, 품질검사, Critical, Warning, 수정제안]
+description: 코드 품질 검토 및 GitHub PR line-level comment 게시. CLAUDE.md/Skills 규칙 준수 확인, Critical/Warning 분류, lint 실행, PR 리뷰 코멘트 작성.
+keywords: [코드리뷰, 체크리스트, lint, 규칙검증, 품질검사, Critical, Warning, 수정제안, PR리뷰, GitHub, comment, 라인코멘트]
 model: opus
 color: yellow
 disallowedTools: [Edit, Write, NotebookEdit]
@@ -13,12 +13,13 @@ memory: project
 
 <role>
 
-작성된 코드가 프로젝트 규칙을 준수하는지 검토하는 전문 Agent입니다.
+작성된 코드가 프로젝트 규칙을 준수하는지 검토하고, PR 리뷰 시 GitHub에 line-level comment를 게시하는 전문 Agent입니다.
 
 1. **규칙 준수 확인**: CLAUDE.md, 프로젝트 체크리스트 기준 검토
 2. **코드 품질 검사**: 가독성, 유지보수성, 일관성
 3. **Lint 실행**: lint 실행 및 결과 확인
 4. **개선 제안**: 발견된 문제에 대한 수정 방안 제시
+5. **PR 리뷰 코멘트**: GitHub PR에 파일/라인별 review comment 게시
 
 </role>
 
@@ -28,7 +29,16 @@ memory: project
 
 ## 검토 프로세스
 
-### Step 1: 공통 체크리스트
+### Step 1: 리뷰 모드 판별
+
+호출 시 전달받은 정보로 리뷰 모드를 결정합니다.
+
+| 조건 | 모드 | 동작 |
+|------|------|------|
+| PR 번호가 주어짐 | **PR 리뷰 모드** | diff 분석 → 코드 검토 → GitHub PR에 line-level comment 게시 |
+| PR 번호 없음 | **로컬 리뷰 모드** | 코드 검토 → 터미널에 결과 출력 |
+
+### Step 2: 공통 체크리스트
 
 | 항목 | 확인 |
 |------|------|
@@ -39,11 +49,11 @@ memory: project
 | 불필요한 코드 없음 | ☐ |
 | 네이밍 컨벤션 준수 | ☐ |
 
-### Step 2: 프로젝트별 체크리스트
+### Step 3: 프로젝트별 체크리스트
 
 프로젝트의 `.claude/skills/` 에 정의된 체크리스트 확인
 
-### Step 3: Lint 실행
+### Step 4: Lint 실행
 
 ```bash
 # 프로젝트에 맞는 lint 명령어 실행
@@ -52,6 +62,130 @@ npm run lint
 yarn lint
 ```
 
+### Step 5: PR 리뷰 코멘트 게시 (PR 리뷰 모드 전용)
+
+PR 리뷰 모드에서는 발견된 이슈를 GitHub PR에 line-level review comment로 게시합니다.
+
+#### 5-1. PR diff 수집
+
+```bash
+# PR의 변경된 파일과 diff 확인
+gh pr diff {PR_NUMBER}
+```
+
+#### 5-2. 이슈별 comment 데이터 구성
+
+각 이슈를 아래 형식으로 수집합니다:
+
+```json
+{
+  "path": "src/example.ts",
+  "line": 42,
+  "body": "**[Critical]** 설명\n\n수정 방안: ..."
+}
+```
+
+- `path`: 리포지토리 루트 기준 상대 경로
+- `line`: diff에서 변경된 라인 번호 (새 파일 기준)
+- `body`: Markdown 형식의 코멘트 본문
+
+**여러 라인에 걸친 이슈**는 `start_line`과 `line`을 함께 사용합니다:
+
+```json
+{
+  "path": "src/example.ts",
+  "start_line": 10,
+  "line": 15,
+  "body": "**[Warning]** 설명"
+}
+```
+
+#### 5-3. comment body 작성 규칙
+
+심각도에 따라 접두사를 붙입니다:
+
+| 심각도 | 접두사 | 예시 |
+|--------|--------|------|
+| Critical | `🔴 **[Critical]**` | `🔴 **[Critical]** any 타입 사용 — 구체적 타입으로 변경 필요` |
+| Warning | `🟡 **[Warning]**` | `🟡 **[Warning]** 매직 넘버 사용 — 상수로 추출 권장` |
+| Info | `🔵 **[Info]**` | `🔵 **[Info]** Optional chaining으로 간소화 가능` |
+
+본문 구성:
+
+```markdown
+{접두사} 이슈 제목
+
+**문제**: 구체적인 문제 설명
+**수정 방안**:
+\`\`\`typescript
+// 수정 예시 코드
+\`\`\`
+```
+
+#### 5-4. GitHub PR Review Comment 게시
+
+수집한 comment들을 개별 review comment로 게시합니다.
+
+```bash
+# owner/repo 확인
+gh repo view --json nameWithOwner -q '.nameWithOwner'
+
+# 최신 commit SHA 확인
+gh pr view {PR_NUMBER} --json headRefOid -q '.headRefOid'
+```
+
+**단일 라인 comment 게시:**
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments \
+  --method POST \
+  -f path="src/example.ts" \
+  -F line=42 \
+  -f side="RIGHT" \
+  -f commit_id="{COMMIT_SHA}" \
+  -f body="코멘트 내용"
+```
+
+**여러 라인 comment 게시:**
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments \
+  --method POST \
+  -f path="src/example.ts" \
+  -F start_line=10 \
+  -F line=15 \
+  -f start_side="RIGHT" \
+  -f side="RIGHT" \
+  -f commit_id="{COMMIT_SHA}" \
+  -f body="코멘트 내용"
+```
+
+#### 5-5. 전체 요약 comment 게시
+
+모든 line comment 게시 후, PR에 전체 요약을 일반 comment로 남깁니다.
+
+```bash
+gh pr comment {PR_NUMBER} --body "$(cat <<'EOF'
+# Code Review 결과 요약
+
+- **검토 파일**: N개
+- **발견 이슈**: Critical N개, Warning N개, Info N개
+- **전체 평가**: 통과 / 수정 필요 / 재작업 필요
+
+## diff 범위 밖 이슈
+- `path/to/file.ts:100` - 설명 (해당되는 경우만)
+
+## 다음 단계
+- ...
+EOF
+)"
+```
+
+#### 5-6. 주의사항
+
+- **diff에 포함된 라인만 comment 가능**: 변경되지 않은 라인에는 comment를 달 수 없음 → diff 범위 밖 이슈는 요약 comment에 포함
+- **이슈가 없으면 요약 comment만 게시**: line comment 없이 "이슈 없음" 요약만 남김
+
 </instructions>
 
 ---
@@ -70,6 +204,8 @@ yarn lint
 
 <output_format>
 
+## 로컬 리뷰 모드 출력
+
 ```markdown
 # Code Review 결과
 
@@ -116,6 +252,32 @@ yarn lint
 - 이슈 없음: 최종 검증 진행
 ```
 
+## PR 리뷰 모드 출력
+
+```markdown
+# PR Review 완료
+
+## 1. 요약
+- **PR**: #{PR_NUMBER}
+- **검토 파일**: N개
+- **게시된 comment**: N개 (Critical N, Warning N, Info N)
+
+## 2. 게시된 comment 목록
+
+| 파일 | 라인 | 심각도 | 이슈 |
+|------|------|--------|------|
+| `src/example.ts` | L42 | Critical | 설명 |
+| `src/util.ts` | L10-15 | Warning | 설명 |
+
+## 3. diff 범위 밖 이슈 (요약 comment에 포함)
+- `path/to/file.ts:100` - 설명
+
+## 4. Lint 결과
+```
+[lint 출력]
+```
+```
+
 </output_format>
 
 ---
@@ -125,5 +287,6 @@ yarn lint
 - **실제 문제만 지적**: 코드에 실질적 영향이 있는 부분만 리뷰
 - **대안 제시 필수**: 문제 지적 시 해결책도 함께 제시
 - **컨텍스트 고려**: 프로젝트 상황에 맞게 유연하게 판단
+- **diff 범위 준수**: PR comment는 diff에 포함된 라인에만 게시 (범위 밖 이슈는 요약 comment에 기재)
 
 </constraints>

package/templates/global/agents/plan-verifier.md

@@ -1,7 +1,7 @@
 ---
 name: plan-verifier
 description: Plan 수립 후 구현 전에 Plan 품질을 검증하는 Agent. 목적 정합성, 완전성, 논리적 일관성, 실현 가능성, 스코프 초과 여부를 코드베이스 탐색을 통해 능동적으로 검증.
-skills: [Reporting]
+skills: [Planning, Reporting]
 keywords: [Plan검증, 목적정합성, 완전성, 논리적일관성, 실현가능성, 스코프검증, PlanReview]
 model: opus
 color: cyan

package/templates/global/agents/task-planner.md

@@ -1,7 +1,7 @@
 ---
 name: task-planner
 description: 복잡한 작업 시작 전 계획 수립 시 호출. 요구사항 명확화 질문, TaskList 생성, 파일별 수정 계획 작성, 의존성 순서 정의.
-skills: [Reporting]
+skills: [Planning, Reporting]
 keywords: [TaskList, 계획수립, 요구사항명확화, 작업분해, 질문, 수정계획, 파일목록, 의존성]
 model: opus
 color: green

package/templates/global/skills/Git/git.md

@@ -144,13 +144,15 @@ grep -r "import.*변경된함수명" --include="*.ts" --include="*.tsx"
 
 ## 🔄 주요 변경사항
 
-### [변경 제목 1]
-**파일:** `path/to/file.ts`
+> 파일별이 아닌 **기능/목적 단위**로 묶어서 설명합니다.
+
+### [기능/변경 목적 1]
 - 변경 내용 설명
+- 관련 파일: `file1.ts`, `file2.ts`
 
-### [변경 제목 2]
-**파일:** `path/to/file.ts`
+### [기능/변경 목적 2]
 - 변경 내용 설명
+- 관련 파일: `file3.ts`
 
 ## ⚠️ 사이드 이펙트
 

package/templates/global/skills/Planning/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: Planning
+description: 개발 계획 문서(plan.md, context.md, checklist.md) 작성 템플릿. DB/API/FE 설계와 의사결정 근거 포함.
+keywords: [plan, 계획, DB설계, API구성, FE플로우, 의사결정, 차선책, planning, 마이그레이션]
+user-invocable: true
+context: fork
+agent: task-planner
+---
+
+# 개발 계획 문서 작성 스킬
+
+> `.claude/plan/` 폴더에 작성하는 3개 문서의 템플릿과 작성 규칙을 정의한다.
+
+## Plan 문서 개요
+
+| 문서 | 역할 | 핵심 내용 |
+|------|------|----------|
+| `plan.md` | 전체 설계 문서 | 목적, DB/API/FE 설계, 설계 결정, TaskList |
+| `context.md` | 맥락 기록 | 사용자 요청 원문, 비즈니스/기술 배경, 탐색한 코드 |
+| `checklist.md` | 실행 추적 | Phase별 체크리스트, Task별 세부 작업 |
+
+### 문서 생명주기
+
+```
+draft → confirmed → in-progress → done
+```
+
+| 상태 | 의미 | 전환 시점 |
+|------|------|----------|
+| `draft` | 초안 작성 중 | 문서 생성 시 |
+| `confirmed` | 사용자 승인 완료 | 사용자 Confirm 후 |
+| `in-progress` | 구현 진행 중 | Phase 3 시작 시 |
+| `done` | 작업 완료 | 모든 Task 완료 시 |
+
+> Stop Hook에서 `plan.md`와 `checklist.md`를 참조하여 진행 상황을 추적한다.
+
+---
+
+<instructions>
+
+## plan.md 템플릿
+
+> 전체 설계를 담는 핵심 문서. 목적, 설계 결정, TaskList를 한 곳에 정리한다.
+
+### Frontmatter
+
+```yaml
+---
+name: [작업명]-plan
+description: [작업명] 개발 계획
+created: YYYY-MM-DD
+status: draft  # draft | confirmed | in-progress | done
+---
+```
+
+### 전체 구조
+
+```markdown
+# [작업명] Plan
+
+## 목적 (Why)
+- 목적: [이 작업을 왜 하는가]
+- 문제: [어떤 문제를 해결하는가]
+- 방법: [어떻게 해결할 것인가]
+
+## DB 수정 계획
+### 테이블 변경
+| 테이블 | 변경 유형 | 컬럼 | 타입 | 설명 |
+|--------|----------|------|------|------|
+| users  | ADD      | role | varchar(20) | 사용자 역할 |
+
+### 마이그레이션 순서
+1. [첫 번째 마이그레이션]
+2. [두 번째 마이그레이션]
+
+### 설계 결정
+- **선택:** [채택한 방안]
+- **이유:** [왜 이 방안을 선택했는지]
+- **차선책:** [고려했지만 선택하지 않은 방안]
+- **차선책 미채택 이유:** [왜 차선책을 선택하지 않았는지]
+
+## API 구성
+### 엔드포인트 목록
+| Method | Path | 설명 | Request | Response |
+|--------|------|------|---------|----------|
+| POST   | /api/users | 사용자 생성 | CreateUserDto | UserResponse |
+
+### 각 API 상세
+#### POST /api/users
+- Request Body: ...
+- Response: ...
+- 에러 케이스: ...
+
+### 설계 결정
+- **선택:** [채택한 방안]
+- **이유:** [왜 이 방안을 선택했는지]
+- **차선책:** [고려했지만 선택하지 않은 방안]
+- **차선책 미채택 이유:** [왜 차선책을 선택하지 않았는지]
+
+## FE 페이지 Flow
+### 화면 목록
+| 페이지 | 경로 | 설명 |
+|--------|------|------|
+| 사용자 목록 | /users | 사용자 리스트 조회 |
+
+### 페이지 흐름도
+[목록] -> [상세] -> [수정]
+          ↓
+        [삭제 확인 모달]
+
+### 컴포넌트 구조
+UserListPage
+├── UserTable
+│   └── UserRow
+├── UserSearchBar
+└── Pagination
+
+### 설계 결정
+- **선택:** [채택한 방안]
+- **이유:** [왜 이 방안을 선택했는지]
+- **차선책:** [고려했지만 선택하지 않은 방안]
+- **차선책 미채택 이유:** [왜 차선책을 선택하지 않았는지]
+
+## 설계 결정 요약
+| 영역 | 결정 | 이유 | 차선책 |
+|------|------|------|--------|
+
+## TaskList 요약
+| Task | 설명 | 의존성 |
+|------|------|--------|
+```
+
+</instructions>
+
+---
+
+<instructions>
+
+## context.md 템플릿
+
+> 작업의 맥락을 기록하여 구현 중 목적 희석을 방지한다.
+
+### Frontmatter
+
+```yaml
+---
+name: [작업명]-context
+description: [작업명] 작업 맥락
+created: YYYY-MM-DD
+---
+```
+
+### 전체 구조
+
+```markdown
+# [작업명] Context
+
+## 사용자 요청 원문
+> (원문 그대로 인용)
+
+## 비즈니스 배경
+- 왜 이 작업이 필요한가
+- 비즈니스 제약 조건
+
+## 기술적 배경
+- 현재 아키텍처 상태
+- 관련 기존 코드/모듈
+
+## 탐색한 코드
+| 파일 | 관련 내용 |
+|------|----------|
+
+## 결정 사항
+| 결정 | 근거 | 일시 |
+|------|------|------|
+```
+
+</instructions>
+
+---
+
+<instructions>
+
+## checklist.md 템플릿
+
+> Phase별 진행 상황을 추적하고, Task별 세부 작업을 관리한다.
+
+### Frontmatter
+
+```yaml
+---
+name: [작업명]-checklist
+description: [작업명] 실행 체크리스트
+created: YYYY-MM-DD
+---
+```
+
+### 전체 구조
+
+```markdown
+# [작업명] Checklist
+
+## Phase 1: 계획
+- [x] 목적 확인
+- [x] Context 수집
+- [x] Plan 문서 작성
+
+## Phase 2: 검증
+- [ ] Code Flow 분석
+- [ ] UserFlow 분석
+- [ ] Breaking Change 확인
+
+## Phase 3: 구현
+### Task 1: [제목]
+- [ ] 세부 작업 1
+- [ ] 세부 작업 2
+- [ ] 커밋
+
+### Task 2: [제목]
+- [ ] 세부 작업 1
+- [ ] 세부 작업 2
+- [ ] 커밋
+
+## Phase 4: 리뷰
+- [ ] 전체 요구사항 충족 확인
+- [ ] 엣지케이스 점검
+```
+
+</instructions>
+
+---
+
+<rules>
+
+## 설계 결정(Decision) 작성 규칙
+
+> 모든 설계 결정에는 "왜 이것을 선택했고, 왜 다른 것을 선택하지 않았는가"를 명시한다.
+
+### 필수 항목
+
+| 항목 | 설명 | 필수 |
+|------|------|------|
+| 선택 (What) | 무엇을 채택했는가 | 필수 |
+| 이유 (Why) | 왜 이것을 선택했는가 | 필수 |
+| 차선책 (Alternative) | 어떤 대안을 검토했는가 | 필수 |
+| 차선책 미채택 이유 (Why Not) | 왜 차선책을 선택하지 않았는가 | 필수 |
+| 트레이드오프 (Tradeoff) | 현재 선택의 단점은 무엇인가 | 선택 |
+
+### 작성 형식
+
+```markdown
+- **선택:** JSON 컬럼 대신 별도 테이블로 분리
+- **이유:** 검색/인덱싱 성능과 스키마 변경 유연성 확보
+- **차선책:** JSON 컬럼으로 저장
+- **차선책 미채택 이유:** 복잡한 쿼리 시 성능 저하, 타입 안정성 부족
+- **트레이드오프:** JOIN 비용 증가 (캐싱으로 완화 가능)
+```
+
+### 적용 범위
+
+> DB, API, FE 모든 영역의 설계 결정에 이 형식을 동일하게 적용한다.
+
+| 영역 | 설계 결정 예시 |
+|------|--------------|
+| DB | 테이블 구조, 인덱스 전략, 정규화 수준 |
+| API | 엔드포인트 설계, 인증 방식, 에러 처리 전략 |
+| FE | 상태 관리 방식, 컴포넌트 구조, 라우팅 전략 |
+
+</rules>
+
+---
+
+<rules>
+
+## 선택적 섹션 규칙
+
+> 모든 프로젝트에 DB/API/FE가 모두 존재하는 것은 아니다. 해당 영역이 있는 섹션만 선택하여 작성한다.
+
+### 최소 필수 섹션
+
+| 섹션 | 필수 여부 | 설명 |
+|------|----------|------|
+| 목적 (Why) | 필수 | 항상 포함 |
+| 설계 결정 요약 | 필수 | 항상 포함 |
+| TaskList 요약 | 필수 | 항상 포함 |
+| DB 수정 계획 | 선택 | DB 변경이 있을 때만 |
+| API 구성 | 선택 | API 변경이 있을 때만 |
+| FE 페이지 Flow | 선택 | FE 변경이 있을 때만 |
+
+### 영역별 선택 기준
+
+```
+DB 변경 있음  → DB 수정 계획 섹션 포함
+API 변경 있음 → API 구성 섹션 포함
+FE 변경 있음  → FE 페이지 Flow 섹션 포함
+해당 없음     → 섹션 생략
+```
+
+</rules>
+
+---
+
+<checklist>
+
+## Plan 문서 작성 시 검증
+
+- [ ] plan.md에 목적(Why) 섹션이 있는가?
+- [ ] 각 설계 결정에 이유와 차선책이 명시되어 있는가?
+- [ ] context.md에 사용자 요청 원문이 인용되어 있는가?
+- [ ] checklist.md에 Task별 세부 작업이 있는가?
+- [ ] status 필드가 올바르게 설정되어 있는가?
+- [ ] 선택적 섹션이 프로젝트에 맞게 포함/생략되어 있는가?
+- [ ] 설계 결정에 트레이드오프가 기록되어 있는가? (선택 사항이지만 권장)
+
+</checklist>
+
+---
+
+<reference>
+
+## 관련 문서
+
+| 문서 | 설명 |
+|------|------|
+| `CLAUDE.md` 워크플로우 | Plan 문서 생성 시점 (Step 1.5.5) |
+| `.claude/skills/Documentation/SKILL.md` | 문서 작성 공통 규칙 |
+| `.claude/skills/PromptStructuring/SKILL.md` | XML 태그 구조화 가이드 |
+
+</reference>

package/templates/global/skills/PromptStructuring/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: PromptStructuring
-description: "Claude Code 프롬프트의 XML 태그 구조화, 긍정 표현 전환, 출력 최적화 가이드"
-keywords: [prompt, xml-tags, positive-phrasing, output-optimization, 프롬프트, 구조화, 긍정표현, XML, 출력최적화]
+description: ".claude/skills/ 또는 .claude/agents/ 하위 파일을 생성·수정할 때 반드시 이 Skill을 읽고 규칙을 적용한다. XML 태그 구조화, 긍정 표현, 출력 최적화, Skills 2.0 frontmatter(context:fork, agent, hooks, skills preload) 스펙 포함."
+keywords: [prompt, xml-tags, positive-phrasing, output-optimization, 프롬프트, 구조화, 긍정표현, XML, 출력최적화, frontmatter, SKILL.md, agent.md, skills-2.0, hooks, context-fork, skills-preload]
 user-invocable: false
 ---
 
 # 프롬프트 구조화 스킬
 
-프롬프트의 형식과 표현 방식은 LLM 출력 품질에 직접적인 영향을 준다.
+> Skill, Agent, Hook 파일 작성/수정 시 이 스킬의 규칙을 적용한다.
 
 ## 핵심 원칙
 
@@ -17,4 +17,14 @@ user-invocable: false
 | 2. 긍정 표현 | "~금지" 대신 "~한다"로 행동 직접 유도 | `positive-phrasing.md` |
 | 3. 흐름 기호 | 단계/변환/위임에 `->` 사용: 계획 -> 구현 -> 검증 | - |
 | 4. 출력 최적화 | 반복 제거, 테이블 > 산문, Hook 출력 150줄 이내 | `output-optimization.md` |
-| 5. Frontmatter | Skill/Agent YAML frontmatter 필드 선택과 작성 기준 | `skills-frontmatter.md` |
+| 5. Skills 2.0 Frontmatter | Skill/Agent YAML frontmatter 필드, context:fork + agent 조합, hooks, skills preload | `skills-frontmatter.md` |
+
+## 적용 시점
+
+| 상황 | 참조할 문서 |
+|------|-----------|
+| Skill SKILL.md 새로 작성 | `skills-frontmatter.md` (frontmatter) + `xml-tags.md` (구조) |
+| Agent .md 새로 작성 | `skills-frontmatter.md` (frontmatter) + `xml-tags.md` (구조) |
+| Hook 스크립트 출력 작성 | `output-optimization.md` (줄 수 제한) |
+| 기존 프롬프트 개선 | `positive-phrasing.md` + `xml-tags.md` |
+| Skill ↔ Agent 연결 설계 | `skills-frontmatter.md` (양방향 연결 패턴) |

package/templates/global/skills/PromptStructuring/skills-frontmatter.md

@@ -17,6 +17,7 @@ SKILL.md와 Agent .md 파일의 YAML frontmatter 필드 가이드.
 |------|------|--------|------|
 | `name` | string | 디렉토리명 | 스킬 이름. `/slash-command`가 됨. 소문자+하이픈, 최대 64자 |
 | `description` | string | 첫 단락 | 용도 및 트리거 조건. Claude가 자동 호출 판단에 사용 |
+| `keywords` | array | - | 검색/매칭용 키워드. 영문+한글 혼용 권장. 예: `[plan, 계획, DB설계]` |
 | `argument-hint` | string | - | 자동완성 시 인자 힌트. 예: `[PR-number]` |
 | `disable-model-invocation` | boolean | `false` | `true` -> Claude 자동 호출 차단. description이 컨텍스트에 로딩되지 않아 토큰 절약 |
 | `user-invocable` | boolean | `true` | `false` -> `/` 메뉴에서 숨김. Claude만 자동 호출 가능 |
@@ -71,6 +72,7 @@ argument-hint: "[PR-number]"
 |------|------|--------|------|
 | `name` | string | **필수** | Agent 이름. 소문자+하이픈 |
 | `description` | string | **필수** | 위임 판단 기준. 언제 이 Agent를 사용하는지 명시 |
+| `keywords` | array | - | 검색/매칭용 키워드. 영문+한글 혼용 권장 |
 | `disallowedTools` | array | - | 명시적 거부 도구 목록 |
 | `model` | string | `inherit` | `sonnet`, `opus`, `haiku`, 모델 ID |
 | `permissionMode` | string | `default` | 권한 모드 |
@@ -108,6 +110,68 @@ skills: [Git]
 
 -> hook으로 "Skill을 먼저 읽으세요"라고 안내하는 간접 방식 대신, frontmatter로 자동 주입.
 
+## Skill ↔ Agent 연결 패턴
+
+> Skill(무엇을 할지) + Agent(어떻게/누가 할지) + Context 격리(어디서 할지)를 조합한다.
+
+### 패턴 1: 참조 Skill (인라인 주입)
+
+Agent가 Skill을 배경 지식으로 preload. 메인 컨텍스트에서 실행.
+
+```yaml
+# Agent frontmatter
+skills: [Coding, Backend]    # Agent 시작 시 Skill 전체 내용 주입
+
+# Skill frontmatter
+user-invocable: false         # 직접 호출 불가, Agent에 의해서만 사용
+```
+
+적용 예: Coding, Backend, React, Reporting
+
+### 패턴 2: 작업 Skill (격리 실행)
+
+Skill 호출 시 fork된 Agent에서 독립 실행. 메인 컨텍스트와 격리.
+
+```yaml
+# Skill frontmatter
+context: fork                 # 격리된 subagent에서 실행
+agent: task-planner           # 사용할 agent 타입 지정
+user-invocable: true          # /slash-command로 호출 가능
+```
+
+적용 예: Planning, pr-review, deploy
+
+### 패턴 3: 양방향 연결
+
+Skill과 Agent가 서로를 참조. 사용자 직접 호출과 Agent preload 모두 지원.
+
+```yaml
+# Planning Skill
+context: fork
+agent: task-planner           # /planning → fork된 task-planner에서 실행
+user-invocable: true
+
+# task-planner Agent
+skills: [Planning, Reporting] # Agent 시작 시 Planning Skill preload
+```
+
+```
+사용자 /planning → fork(task-planner) → Planning 템플릿에 따라 plan 문서 생성
+Main Agent → task-planner 호출 → Planning Skill 자동 preload → 동일 품질 보장
+```
+
+### 패턴 선택 기준
+
+| 기준 | 참조 Skill | 작업 Skill | 양방향 |
+|------|:-:|:-:|:-:|
+| 규칙/가이드 제공 | O | - | O |
+| 독립 실행 필요 | - | O | O |
+| 사용자 직접 호출 | - | O | O |
+| Agent preload | O | - | O |
+| 컨텍스트 격리 | - | O | O |
+
+---
+
 ## Hooks in Skills/Agents
 
 Skill과 Agent의 frontmatter에 `hooks` 필드를 정의하면 해당 컴포넌트가 활성화된 동안에만 실행된다.