# Guide Maker

> 프로젝트 기능에 대한 사용자 가이드를 Notion에 생성하는 스킬. 테이블, 색상, 코드블록, 화살표, 이모지를 활용한 가시성 높은 문서 생성. "가이드 만들어줘", "사용자 매뉴얼 작성해줘", "도움말 문서 생성해줘", "Notion에 문서 작성해줘" 요청 시 사용. Notion 공식 remote MCP (OAuth) 사용.

- Skill: `rungchan2/guide-maker` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add rungchan2/guide-maker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rungchan2/guide-maker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: rungchan2 (https://skillmd.com/u/rungchan2)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/rungchan2/guide-maker

---


# Guide Maker

프로젝트 기능에 대한 **가시성 높은** 사용자 가이드를 Notion에 생성.

## 사전 요구사항

- **Notion remote MCP** 연결 (이 플러그인 설치 시 자동 등록됨)
- 최초 사용 시 Claude Code에서 OAuth 로그인 1회만 하면 됨 (별도 환경변수 불필요)
- 가이드를 작성할 **부모 페이지**가 본인 Notion workspace에 존재하고, 해당 integration이 그 페이지에 connection으로 추가되어 있어야 함

## 워크플로우

### 0. 부모 페이지 확보 (동적)

대화 시작 시 **부모 페이지 ID를 다음 순서로 확보**:

1. 사용자가 메시지에 부모 페이지 URL/ID를 직접 제공했으면 → 그것 사용
2. 아니면 Notion MCP의 `search` 도구로 사용자가 말한 부모 페이지명을 검색해서 후보 제시
3. 그래도 모호하면 사용자에게 명시적으로 묻기:
   > "가이드를 어느 Notion 페이지 아래에 만들까요? 페이지 URL이나 이름을 알려주세요."

**❌ 금지:** 페이지 ID를 하드코딩하거나 임의로 가정하기
**✅ 필수:** 매 호출마다 사용자 컨텍스트에서 부모 페이지를 동적으로 결정

확보한 page_id는 이번 대화 turn에서만 변수로 보관, 스킬 내부 어디에도 영구 저장하지 않음.

Notion 페이지 URL에서 ID 추출:
```
https://www.notion.so/Workspace-abc123def456...
                                ^^^^^^^^^^^^^^^
                                마지막 32자 = page_id (하이픈 추가하여 사용)
```

### 1. 기능 분석
해당 기능의 코드 분석 → 주요 버튼, 폼, 테이블, 상태값 파악

### 2. 콘텐츠 구조 설계
문서 구조에 맞춰 **전체 블록 배열 설계** (페이지 위치, Part별 Step, 테이블, FAQ 등)

### 3. 한 번에 생성 (🚨 필수!)

Notion remote MCP는 표준 Notion API를 그대로 노출합니다. 일반적으로 다음 두 도구를 사용:

- `notion-create-pages` (또는 `API-post-page`): 새 페이지 생성
- `notion-update-page` / `notion-patch-block-children` (또는 `API-patch-block-children`): 페이지에 자식 블록 추가

> 정확한 도구명은 MCP 클라이언트가 노출하는 이름을 따릅니다. `/mcp` 슬래시 메뉴에서 사용 가능한 도구명을 확인하세요.

**전체 가이드는 단 한 번의 페이지 생성 + 한 번의 블록 추가로 완성:**

```text
1. create-page 호출
   - parent: { page_id: <step 0에서 확보한 부모 페이지 ID> }
   - properties.title: "📑 [기능명]"
   → 응답에서 새 페이지 id 획득

2. patch-block-children 호출
   - block_id: 위에서 받은 새 페이지 id
   - children: [전체 블록 배열 — Part 헤더, Step, divider, 테이블, FAQ 토글 모두 포함]

3. 사용자에게 URL 반환:
   https://www.notion.so/<page_id에서 하이픈 제거>
```

**❌ 금지:** Step별/Part별로 나눠서 여러 번 API 호출
**✅ 필수:** 전체 블록을 하나의 배열로 → 단 1회 API 호출

### 4. 완료
URL 전달: `https://www.notion.so/[page_id_without_hyphens]`

---

## 문서 구조 (필수)

```
## 페이지 위치
**[상위 메뉴]** → **[기능명]**
[이미지]
---

## [기능] 방법

### Step 1. [작업 제목]
[설명]
[이미지]
1. **'버튼명'**을 클릭합니다.
2. [동작]
💡 Tip: [정보]
---

### Step 2. ...

## [테이블명] 컬럼 설명
| 컬럼명 | 설명 |
|--------|------|
| ... | ... |
---

## [상태] 안내
| 상태 | 색상 | 설명 |
|------|------|------|
| ✅ 완료 | 🟢 초록 | ... |
| ⏳ 대기 | 🟡 노랑 | ... |
| ❌ 실패 | 🔴 빨강 | ... |
---

## 자주 묻는 질문
> Q: [질문]?
A: [답변]
```

---

## 가시성 원칙

| 요소 | 용도 | 예시 |
|------|------|------|
| **테이블** | 컬럼/상태/필드 설명 | 상태 테이블, 입력 필드 테이블 |
| **→ 화살표** | 경로/흐름 | `대시보드 → 설정 → 알림` |
| **이모지+색상** | 상태 구분 | `✅ 완납 🟢`, `❌ 미납 🔴` |
| **굵은 텍스트** | 버튼/메뉴 강조 | `**'저장'**` |
| **인라인 코드** | 입력값/형식 | `` `010-1234-5678` `` |
| **콜아웃** | 팁/주의/자동화 | 💡⚠️⚡ |
| **코드 블록** | 예시 데이터 | 입력 예시 |

---

## 레퍼런스

- **Notion 블록 JSON**: [references/notion-blocks.md](references/notion-blocks.md)
- **가시성 패턴 예시**: [references/visual-patterns.md](references/visual-patterns.md)

---

## 체크리스트

### 필수
- [ ] 페이지 위치 (→ 화살표 + 이미지)
- [ ] 모든 Step에 이미지 블록
- [ ] 버튼/메뉴: **'작은따옴표'와 굵게**
- [ ] 각 Step 끝에 divider
- [ ] FAQ 섹션 (최소 3개 토글)

### 가시성
- [ ] 컬럼 설명 테이블
- [ ] 상태값 테이블 (이모지+색상)
- [ ] 입력 형식: 인라인 코드
- [ ] 콜아웃 활용 (💡⚠️⚡)