Chore(project): AI 에이전트 스킬 시스템 셋업 (#334)

.agents/skills/code/component/SKILL.md

@@ -0,0 +1,26 @@
+# code/component
+
+## 트리거
+
+- "컴포넌트 만들어줘"
+- "{이름} 컴포넌트 생성해줘"
+
+## 참조
+
+- `docs/conventions/component.md` → 네이밍/코드 스타일 (rafce, fragment, 타입 위치 등)
+- `docs/conventions/architecture.md` → 폴더 구조
+
+## Phase 1 — 계획 확인
+
+1. 컴포넌트 성격을 확인한다:
+   - 여러 페이지에서 재사용 → `apps/{app}/src/shared/components/`
+   - 특정 페이지 전용 → `apps/{app}/src/pages/{page}/components/`
+   - 디자인 시스템(범용 UI) → `packages/design-system/src/components/`
+2. 컴포넌트명(PascalCase)과 폴더명(camelCase), props 타입 필요 여부를 확인한다.
+3. 배치 경로·파일명·props 타입 초안을 출력하고 사용자 승인을 기다린다. 승인 없이 Phase 2로 넘어가지 않는다.
+
+## Phase 2 — 실행
+
+1. `{경로}/{folderCamelCase}/{ComponentPascalCase}.tsx`를 생성한다.
+2. `docs/conventions/component.md`의 컴포넌트 규칙을 따른다: `rafce` 형태, 의미 없는 `div` 대신 fragment, children 불필요 시 selfClosing, props 타입은 컴포넌트 상단에 정의.
+3. 생성된 파일 경로를 요약해 보고한다.

.agents/skills/code/page/SKILL.md

@@ -0,0 +1,22 @@
+# code/page
+
+## 트리거
+
+- "새 페이지 만들어줘"
+- "{이름} 페이지 스캐폴딩해줘"
+
+## 참조
+
+- `docs/conventions/architecture.md` → 폴더 구조
+
+## Phase 1 — 계획 확인
+
+1. 페이지명(camelCase)과 위치(`apps/{app}/src/pages/{name}`)를 확인한다.
+2. 필요한 하위 폴더(`components`, `hooks`, `utils`, `types`, `apis`, `constants` 중 실제로 쓸 것만)를 확인한다.
+3. 생성할 폴더/파일 목록을 출력하고 사용자 승인을 기다린다. 승인 없이 Phase 2로 넘어가지 않는다.
+
+## Phase 2 — 실행
+
+1. 승인된 하위 폴더만 `apps/{app}/src/pages/{name}/` 아래 생성한다 (빈 폴더는 자리표시 파일 없이 실제 파일과 함께 생성).
+2. 라우팅 연결이 필요하면 `routes` 설정에 추가할지 사용자에게 확인한다.
+3. 생성된 구조를 요약해 보고한다.

.agents/skills/figma/to-code/SKILL.md

@@ -0,0 +1,29 @@
+# figma/to-code
+
+## 트리거
+
+- "이 피그마 디자인 구현해줘"
+- "피그마 링크 보고 컴포넌트 만들어줘"
+
+## 사전 설정
+
+- `docs/setup/figma-mcp.md` → Figma MCP 연동 설정. 세션에 Figma MCP 도구가 없으면 먼저 이 문서를 안내한다.
+
+## 참조
+
+- `docs/conventions/component.md` → 네이밍/코드 스타일
+- `docs/conventions/architecture.md` → 폴더 구조
+- `docs/design/tokens.md` → 색상/spacing/타이포그래피 토큰
+- `.agents/skills/code/component/SKILL.md` → 배치 위치(shared/pages/design-system) 판단 및 파일 생성 절차
+
+## Phase 1 — 디자인 컨텍스트 확보 및 계획
+
+1. 공유된 Figma URL로 디자인 컨텍스트(구조, 스크린샷, 변수/토큰)를 가져온다.
+2. 추출한 구조를 컴포넌트 단위로 분해하고, `code/component` 스킬의 Phase 1 배치 기준을 그대로 적용해 각 컴포넌트의 배치 위치(shared/pages/design-system)를 정한다.
+3. 컴포넌트 목록 + 배치 경로 + 스타일 매핑 개요(어떤 값이 `docs/design/tokens.md`에 있고, 없는 값은 무엇인지)를 출력하고 사용자 승인을 기다린다. 승인 없이 Phase 2로 넘어가지 않는다.
+
+## Phase 2 — 구현
+
+1. `code/component` 스킬의 Phase 2를 그대로 따라 파일을 생성한다 (rafce, fragment, props 타입 위치 등 `component.md` 규칙 적용).
+2. 색상/spacing/타이포그래피는 `docs/design/tokens.md`에 등록된 토큰으로만 매핑한다. 표에 없는 값이 필요하면 hex/px를 하드코딩하지 않고, 토큰을 새로 추가할지 먼저 사용자에게 확인한다.
+3. 구현 결과를 디자인 스크린샷과 비교해 자체 점검하고 요약 보고한다.

.agents/skills/figma/to-figma/SKILL.md

@@ -0,0 +1,21 @@
+# figma/to-figma
+
+## 트리거
+
+- "이 컴포넌트 피그마로 만들어줘"
+- "이 페이지 디자인 동기화해줘"
+
+## 사전 설정
+
+- `docs/setup/figma-mcp.md` → Figma MCP 연동 설정. 세션에 Figma MCP 도구가 없으면 먼저 이 문서를 안내한다.
+
+## Phase 1 — 대상 확인
+
+1. 반영할 코드 범위(컴포넌트/페이지)와 대상 Figma 파일·위치를 확인한다.
+2. Figma MCP 도구를 호출하기 전에 해당 MCP가 제공하는 사전 스킬(`/figma-use` 등)이 있으면 먼저 로드한다.
+3. 반영 계획(대상 코드, 대상 Figma 파일, 생성/수정 범위)을 출력하고 사용자 승인을 기다린다. **외부 Figma 파일을 직접 수정하는 작업이므로 승인 없이 Phase 2로 넘어가지 않는다.**
+
+## Phase 2 — 실행
+
+1. 승인된 범위로 Figma MCP 도구를 호출해 반영한다.
+2. 결과 Figma 파일 링크를 보고한다.

.agents/skills/git/branch/SKILL.md

@@ -0,0 +1,25 @@
+# git/branch
+
+## 트리거
+
+- "이슈 #123 브랜치 만들어줘"
+- "브랜치 새로 파줘"
+- "{기능} 작업 브랜치 만들어줘"
+
+## 참조
+
+- `docs/conventions/branch.md` → 브랜치 네이밍 형식
+- `docs/conventions/merge.md` → develop 최신화 규칙
+
+## Phase 1 — 계획 확인
+
+1. 이슈번호와 작업 타입(`docs/conventions/commit.md`의 타입 목록 중 하나)을 확인한다. 사용자가 알려주지 않았다면 GitHub 이슈 제목/라벨을 조회하거나 직접 물어본다.
+2. `docs/conventions/branch.md` 형식에 맞춘 브랜치명을 제안한다: `{타입}/#{이슈번호}/{기능명}`
+3. 현재 브랜치가 `develop`이 아니거나 `develop`이 최신이 아닐 수 있으면 함께 안내한다.
+4. 브랜치명과 실행 계획을 출력하고 사용자 승인을 기다린다. 승인 없이 Phase 2로 넘어가지 않는다.
+
+## Phase 2 — 실행
+
+1. `develop`으로 이동해 `git pull origin develop`으로 최신화한다.
+2. 승인된 이름으로 `git checkout -b {브랜치명}`을 실행한다.
+3. 생성된 브랜치명과 시작 커밋을 요약해 보고한다.

.agents/skills/git/commit/SKILL.md

@@ -0,0 +1,54 @@
+# git/commit
+
+## 트리거
+
+- "커밋해줘"
+- "커밋 만들어줘"
+- "지금까지 한 거 커밋해줘"
+- "변경사항 나눠서 커밋해줘"
+
+## 참조
+
+- `docs/conventions/commit.md` → 타입 목록과 메시지 형식
+- `docs/conventions/merge.md` → main/develop 직접 커밋 금지 규칙
+
+## 핵심 원칙
+
+1. **secret guard 먼저**: `.env`류 파일, password, api key, secret, token 패턴이 스테이징/변경분에 있으면 즉시 멈추고 알린다.
+2. **atomic 단위 분리**: 논리적으로 무관한 변경은 별도 커밋으로 나눈다.
+3. **2단계 진행**: Phase 1(계획표+승인) → Phase 2(실행). 승인 없이 커밋하지 않는다.
+4. **push는 명시적 요청 시에만** 수행한다.
+
+## Phase 1 — 계획 확인
+
+1. `git status`, `git diff`(staged+unstaged), 최근 `git log`로 변경 내용을 파악한다.
+2. 현재 브랜치가 `main`/`develop`이면 즉시 중단하고 사용자에게 알린다.
+3. **secret guard**: 변경된 파일에서 `.env`류 파일, `password`, `api_key`, `secret`, `token` 패턴을 검색한다. 발견되면 즉시 멈추고 사용자에게 알린다 — 확인 없이 다음 단계로 넘어가지 않는다.
+4. 변경 파일들을 도메인/기능/계층 단위로 분류한다. 서로 무관한 변경(예: 의존성 변경 vs 핵심 구현 vs 설정)은 별도 커밋으로 나눈다.
+5. 각 그룹마다 `docs/conventions/commit.md` 형식(`{타입}: {메시지}`)의 커밋 메시지 초안을 작성한다.
+6. 아래 형식으로 계획표를 출력하고 사용자 승인을 기다린다. 승인 없이 Phase 2로 넘어가지 않는다.
+
+```
+## 커밋 계획
+
+### 커밋 1: feat: 소셜 로그인 컴포넌트 추가
+- apps/client/src/pages/login/components/SocialLogin.tsx
+
+### 커밋 2: chore: turbo filter 스크립트 추가
+- package.json
+
+계속 진행할까요?
+```
+
+## Phase 2 — 실행
+
+1. 승인된 각 그룹만 순서대로 `git add {파일명}`으로 스테이징한다 (`git add -A`/`git add .` 금지, 파일명을 지정한다).
+2. 그룹별로 승인된 메시지로 커밋한다.
+3. `git log --oneline -n {커밋 수}`로 결과를 확인하고 요약 보고한다.
+
+## 금지
+
+- `--no-verify` 사용 금지 (사용자가 요청해도 이유를 먼저 묻는다).
+- 스테이징되지 않은 파일을 임의로 전부 `add`하지 않는다.
+- `.env`, 인증서, 토큰 파일을 커밋에 포함하지 않는다.
+- 승인 없이 커밋을 실행하지 않는다.

.agents/skills/git/issue/SKILL.md

@@ -0,0 +1,80 @@
+# git/issue
+
+## 트리거
+
+- "이슈 만들어줘"
+- "이슈 올려줘"
+- "이슈 써줘"
+- 새 기능 개발 또는 버그 수정을 시작하기 전
+
+인자 없이 실행하면 현재 대화 컨텍스트에서 작업 내용을 추론한다.
+
+## 참조
+
+- `.github/ISSUE_TEMPLATE/{feature,fix,refactor}.yml` → 이슈 제목/라벨/본문 템플릿 (Pinback은 이 3종류만 존재)
+- `.agents/skills/git/branch/SKILL.md` → 브랜치 생성은 이 스킬에 위임한다 (중복 구현 금지)
+
+## Phase 1 — 계획 확인
+
+1. 타입을 확인한다: `Feat`(새 기능) / `Fix`(버그) / `Refactor`(리팩터링) 중 하나. 대화 컨텍스트로 추론하고, 애매하면 사용자에게 확인한다.
+   - Pinback 이슈 템플릿은 이 3종류만 존재한다. `setting`/`chore` 등 나머지 타입은 이슈 없이 바로 `git/branch`로 진행할 수 있다.
+2. 제목: 템플릿에 고정된 프리픽스(`[Feat] `/`[Fix] `/`[Refactor] `) + 한국어 요약.
+3. 본문: 해당 템플릿의 `Task Description`(필수) / `ETC`(선택) 필드에 맞춰 작성한다.
+4. 아래 형식으로 계획표를 출력하고 사용자 승인을 기다린다. 승인 없이 Phase 2로 넘어가지 않는다.
+
+```
+## 이슈 생성 계획
+
+타입: Feat
+제목: [Feat] 소셜 로그인 기능 구현
+라벨: 📌 feat
+Assignee: @me
+
+### 본문 미리보기
+---
+### Task Description
+
+...
+
+### ETC
+
+...
+---
+
+계속 진행할까요?
+```
+
+## Phase 2 — 이슈 생성
+
+```bash
+gh issue create \
+  --title "[Feat] 소셜 로그인 기능 구현" \
+  --body "$(cat <<'EOF'
+### Task Description
+
+...
+
+### ETC
+
+...
+EOF
+)" \
+  --label "📌 feat" \
+  --assignee "@me"
+```
+
+생성된 이슈 URL에서 이슈 번호를 추출한다.
+
+## Phase 3 — 브랜치 생성
+
+이슈 번호를 확보했으면 `.agents/skills/git/branch/SKILL.md`의 Phase 1로 이어서 진행한다. 브랜치 네이밍·develop 최신화는 해당 스킬 규칙을 그대로 따른다.
+
+## 주의사항
+
+- assignee는 항상 `@me`.
+- `gh` CLI 미인증 시 `gh auth login`을 안내하고 중단한다.
+- 같은 이름의 이슈/브랜치가 이미 있으면 사용자에게 알리고 다른 이름을 제안한다.
+
+## 금지
+
+- 사용자 승인 없이 이슈를 생성하지 않는다.

.agents/skills/git/pr/SKILL.md

@@ -0,0 +1,50 @@
+# git/pr
+
+## 트리거
+
+- "PR 만들어줘"
+- "PR 열어줘"
+- "이 브랜치로 PR 생성해줘"
+- 브랜치 작업이 완료되고 `develop`으로 머지 준비가 된 시점
+
+## 참조
+
+- `.github/pull_request_template.md` → PR 본문 템플릿
+- `docs/conventions/merge.md` → 병합 방식(squash), approve 조건
+- `docs/conventions/commit.md` → 제목에 쓰는 타입 목록
+
+## 핵심 원칙
+
+1. **전체 diff 기준**: `develop` 대비 전체 변경을 분석한다. 최신 커밋 하나만 보지 않는다.
+2. **제목은 `{Type}(scope): 한국어 요약` 형식** — `docs/conventions/commit.md` 타입 목록을 따른다 (예: `Feat(client): 소셜 로그인 기능 구현`).
+3. **근거 기반으로 쓴다**: 실제로 실행·확인한 명령/화면만 적는다. 확인하지 않은 증거를 만들지 않는다.
+4. **구현 의도를 설명한다**: 무엇을 바꿨는지는 diff가 대신한다. 왜 이 구조를 택했는지, 어떤 문제를 해결했는지를 적는다.
+5. **실제 검증과 계획된 검증을 분리한다**: 실행하지 않은 명령은 통과했다고 쓰지 않는다.
+6. **base 브랜치 확인**: 기본값은 `develop`. 다르면 먼저 사용자에게 물어본다.
+
+## Phase 1 — 계획 확인
+
+1. base 브랜치를 확인한다 (기본 `develop`, 다르면 먼저 사용자에게 확인).
+2. `git log {base}..HEAD --oneline --reverse`, `git diff {base}...HEAD --stat`, `--name-only`으로 전체 변경사항을 파악한다.
+3. 브랜치명에서 이슈번호를 추출하고 관련 이슈 내용을 확인한다.
+4. `pnpm check-types`, `pnpm lint`를 실행해 통과 여부를 확인한다. 실패하면 PR 작성 전에 먼저 사용자에게 알리고 진행 여부를 묻는다.
+5. `.github/pull_request_template.md` 형식에 맞춰 초안을 작성한다:
+   - **Related Issues**: 브랜치의 이슈번호로 `close #N`
+   - **Tasks**: 변경 파일 나열로 끝내지 않는다. 변경 단위(도메인/기능)별로 무엇을·왜 바꿨는지 서술한다.
+   - **PR Point (To Reviewer)**: 판단이 필요한 구조 선택, 남은 리스크, 의도적으로 제외한 범위, `pnpm check-types`/`pnpm lint` 실행 결과를 적는다.
+   - **Screenshot**: UI 변경이 있으면 실제로 확인한 화면만 첨부하도록 안내한다 (표로 정리 제안). UI 변경이 없거나 확인하지 않았으면 섹션을 생략한다.
+6. 초안을 출력하고 사용자 승인을 기다린다. 승인 없이 Phase 2로 넘어가지 않는다.
+
+## Phase 2 — 실행
+
+1. 필요 시 원격에 브랜치를 push한다.
+2. 승인된 제목/본문으로 `gh pr create --base {base}`를 실행한다.
+3. 리뷰어는 `review-assign.yml` 워크플로우가 자동 지정하므로 별도로 지정하지 않는다. reviewer/milestone은 사용자가 명시한 경우에만 추가한다.
+4. PR URL을 보고한다.
+
+## 금지
+
+- PR을 병합하지 않는다. 병합은 2명 이상 approve 후 사용자가 직접 처리한다.
+- force-push로 base 브랜치를 덮어쓰지 않는다.
+- 실행하지 않은 명령을 통과했다고 기록하지 않는다.
+- 없는 증거(screenshot, 실행 결과 등)를 있는 것처럼 쓰지 않는다.

.agents/skills/meta/manage/SKILL.md

@@ -0,0 +1,30 @@
+# meta/manage
+
+## 트리거
+
+- "이거 스킬로 만들어줘"
+- "스킬 수정해줘"
+- "이 스킬 이제 안 써, 폐기해줘"
+
+## 참조
+
+- `AGENTS.md` → 트리거 → 스킬 매핑 표
+
+## 스킬화 기준
+
+아래 중 2개 이상 해당해야 새 스킬로 만든다:
+- 3번 이상 같은 방식으로 반복 요청됨
+- 순서/절차 실수가 잦음
+- 참조해야 할 문서·파일이 명확함
+- Phase가 자연스럽게 2개 이상으로 나뉨
+
+## Phase 1 — 변경 내용 확인
+
+추가/수정/폐기 대상과 이유를 확인하고, 어떤 파일이 바뀌는지 계획을 출력해 승인을 받는다.
+
+## Phase 2 — 실행
+
+- **추가**: `.agents/skills/{category}/{name}/SKILL.md`를 생성한다. 컨벤션 원문이 필요하면 `docs/conventions/`에 별도 파일로 만들고, SKILL.md에는 복제하지 않고 경로만 참조한다.
+- **수정**: 해당 SKILL.md만 수정한다.
+- **폐기**: 파일을 삭제하지 않고 최상단에 `> ⚠️ DEPRECATED — {대체 스킬명} 사용`을 추가한다.
+- 위 어떤 경우든 마지막에 `AGENTS.md`의 트리거 표를 동기화한다 (추가/수정 시 행 추가·갱신, 폐기 시 행 제거).

.agents/skills/meta/orchestrate/SKILL.md

@@ -0,0 +1,25 @@
+# meta/orchestrate
+
+## 트리거
+
+- "커밋하고 PR까지 만들어줘"
+- "브랜치 파서 작업하고 PR 열어줘"
+- 하나의 요청이 두 개 이상의 스킬 트리거에 걸릴 때
+
+## 참조
+
+- `AGENTS.md` → 트리거 → 스킬 매핑 표
+
+## Phase 1 — 스킬 체인 도출
+
+요청을 분석해 실행할 스킬들의 순서를 정한다 (예: `git/branch` → `git/commit` → `git/pr`).
+
+## Phase 2 — 계획 출력 및 승인
+
+도출된 스킬 체인과 각 스킬에서 수행할 작업을 요약해 출력하고, 사용자 승인을 기다린다.
+
+## Phase 3 — 순차 실행
+
+1. 각 스킬의 SKILL.md를 순서대로 Read하고 그 Phase를 그대로 따른다.
+2. 각 스킬은 자신의 Phase 1(계획+승인)을 그대로 유지한다 — orchestrate 단계의 승인이 개별 스킬의 승인 게이트를 대체하지 않는다.
+3. 한 스킬에서 실패하거나 예상과 다른 상태(블로커)를 만나면 즉시 중단하고 사용자에게 보고한다.