@simplysm/sd-claude 13.0.85 → 13.0.87

package/claude/skills/sd-commit/SKILL.md

@@ -1,63 +1,152 @@
 ---
 name: sd-commit
-description: Used when requesting "commit", "sd-commit", etc.
+description: 변경사항을 분석하여 [type] scope 형식의 커밋 메시지를 생성하고 커밋. 사용자가 커밋을 요청할 때 사용
+argument-hint: "[all]"
 ---
 
-# SD Commit — Analyze Changes and Commit
+# sd-commit: 커밋
 
-Stage changes, analyze the diff to generate a commit message, and commit.
+변경사항을 분석하여 커밋 메시지를 생성하고 커밋한다.
 
-ARGUMENTS: `all` (optional). If specified, target all changes; if omitted, target only files modified during the current conversation.
+## 1. 인자 파싱
 
----
+`$ARGUMENTS`에서 staging 전략을 결정한다.
+
+| 인자 | 동작 |
+|------|------|
+| (없음) | 현재 대화에서 수정한 파일만 `git add {파일1} {파일2} ...`로 staging (시크릿 파일 제외) |
+| `all` | `git add -A`로 모든 변경사항(untracked 포함)을 staging |
+
+## 2. 정보 수집
+
+### `all` 인자인 경우
+
+1. Bash로 `git add -A`를 실행하여 모든 변경사항을 먼저 staging한다
+2. 이후 다음 명령어를 Bash로 **병렬 실행**한다:
+   - `git status` (staging 결과 확인, `-uall` 플래그 금지)
+   - `git diff --staged` (staging된 전체 변경사항 확인)
+
+### 인자 없음인 경우
+
+현재 대화에서 Edit/Write 도구로 수정한 파일 목록을 대화 맥락에서 파악한다.
+
+다음 명령어를 Bash로 **병렬 실행**한다:
+
+- `git status` (전체 상태 확인, `-uall` 플래그 금지)
+- `git diff -- {대화에서 수정한 파일들}` (해당 파일들의 unstaged 변경사항)
+- `git diff --staged -- {대화에서 수정한 파일들}` (해당 파일들의 staged 변경사항)
+
+대화에서 수정한 파일이 없으면 "현재 대화에서 수정한 파일이 없습니다."를 출력하고 종료한다.
 
-## Step 1: Parse Arguments and Stage
+## 3. 변경사항 분석
 
-Check whether `all` is present in ARGUMENTS.
+### 3-1. 변경사항 없음
 
-- **`all`**: Stage all changes in the working tree (modified, deleted, and new files).
-- **Not `all` or no arguments**: Stage only files that were modified or created via the Edit or Write tools during the current conversation. Review the conversation context and extract the list of those files.
+git status/diff 결과가 모두 비어있으면 (staged, unstaged, untracked 모두 없음):
+- "커밋할 변경사항이 없습니다."를 출력하고 종료한다
 
-## Step 2: Check for Changes
+### 3-2. 시크릿 파일 확인
 
-If there are no staged changes, inform the user "No changes to commit." and **stop**.
+변경 파일 중 시크릿 파일(`.env`, `credentials.json`, `*.key`, `*.pem` 등)이 포함되어 있으면:
+- 해당 파일명을 명시하여 경고를 출력한다
+- staging 대상 및 커밋 메시지에서 제외한다
 
-## Step 3: Generate Commit Message and Commit
+### 3-3. 변경사항 분류
 
-Analyze the staged diff and generate a commit message according to the rules below, then commit.
+변경된 파일과 diff 내용을 분석하여 변경의 성격을 파악한다:
+- `feat`: 새 기능 추가
+- `fix`: 버그 수정
+- `refactor`: 리팩터링 (동작 변경 없음)
+- `test`: 테스트 추가/수정
+- `docs`: 문서 변경
+- `chore`: 빌드, 설정, 의존성 등 기타 변경
 
-### Commit Message Rules
+## 4. 커밋 메시지 작성
 
-- **Conventional Commits** format: prefix + description
-  - prefix examples: `feat`, `fix`, `refactor`, `chore`, `docs`, `style`, `test`, `perf`, `ci`, `build`
-- **subject** (first line): Summary of changes. 70 characters or fewer.
-- **body**: After a blank line, list the key changes. If changes span multiple topics, group them with `[prefix]` tags per topic.
-- Include `Co-Authored-By: Claude <noreply@anthropic.com>` at the end.
+### 형식
+
+첫 줄은 전체 변경사항을 요약하는 **커밋 헤더**이다.
+빈 줄 후 `[type] scope` 헤더와 bullet point로 세부 내용을 기술한다.
+마지막에 `Co-Authored-By` 트레일러를 포함한다.
 
-Single-topic example:
 ```
-feat: Add user authentication logic
+{전체 요약 커밋 헤더}
 
-- Implement JWT token verification in AuthService
-- Add form validation to the login page
+[type] {변경 대상 요약}
+- {세부 변경 내용}
+- {세부 변경 내용}
 
 Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
-Multi-topic example:
+### 다중 변경사항
+
+여러 종류의 변경이 있으면 `[type] scope` 그룹을 빈 줄로 구분하여 나열한다.
+
 ```
-chore: Add authentication feature and fix payment error
+core-common 유틸 함수 추가 및 solid DatePicker 버그 수정
 
-[feat] User authentication
-- Implement JWT token verification in AuthService
-- Add form validation to the login page
+[feat] core-common 유틸 함수 추가
+- StringUtil에 camelToKebab 변환 함수 추가
 
-[fix] Payment module
-- Fix retry logic on payment failure
+[fix] solid DatePicker 버그 수정
+- timezone 오프셋 미적용으로 인한 날짜 표시 오류 수정
 
 Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
-## Step 4: Output Result
+### 단일 변경사항
+
+변경이 한 종류이면 `[type] scope` 그룹 1개만 작성한다.
+
+```
+solid DatePicker timezone 버그 수정
+
+[fix] solid DatePicker 버그 수정
+- timezone 오프셋 미적용으로 인한 날짜 표시 오류 수정
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### 메시지 작성 원칙
+
+- "what"이 아닌 "why"에 초점을 맞춘다
+- 커밋 헤더는 간결하게 작성한다
+- scope는 변경 대상을 요약한다
+
+## 5. Staging 및 커밋
+
+### Staging
+
+- `all` 인자: 2단계에서 이미 staging 완료. 추가 작업 없음
+- 인자 없음: 현재 대화에서 수정한 파일 중 시크릿 파일을 제외하고 `git add {파일1} {파일2} ...`로 staging한다
+
+### 커밋
+
+HEREDOC 형식으로 커밋 메시지를 전달한다. `--no-verify`, `--no-gpg-sign` 등 hook 우회 플래그를 사용하지 않는다.
+
+```bash
+git commit -m "$(cat <<'EOF'
+{커밋 메시지}
+EOF
+)"
+```
+
+`--amend`는 사용하지 않는다. 항상 새 커밋을 생성한다.
+
+## 6. 커밋 후 검증
+
+### 성공 시
+
+Bash로 `git status`를 실행하여 커밋이 정상적으로 완료되었는지 확인한다.
+
+### pre-commit hook 실패 시
+
+실패 원인을 사용자에게 보고하고 중단한다.
+
+## 7. 완료 안내
+
+커밋 후 `git rev-parse HEAD`로 새 커밋 해시를 얻고, 해시와 커밋 메시지 전문을 함께 출력한다.
+마지막에 "커밋을 취소하려면 수동으로 되돌리세요."라고 안내한다.
 
-After the commit is complete, show the full commit message to the user.
+`git push`는 수행하지 않는다. git config는 수정하지 않는다.

package/claude/skills/sd-debug/SKILL.md

@@ -1,122 +1,136 @@
 ---
 name: sd-debug
-description: Used when requesting "debug", "sd-debug", "error analysis", "error cause", "find bug", etc.
+description: 문제의 근본 원인을 분석하고 해결책을 제시하여 debug.md로 저장. 사용자가 버그/에러/오류/예외/비정상 동작의 원인 분석을 요청할 때 사용
+argument-hint: "<문제 현상 설명>"
 ---
 
-# SD Debug — Root Cause Analysis and Resolution Planning
+# sd-debug: 근본 원인 분석 및 해결
 
-Receives error messages, stack traces, or problem descriptions, performs in-depth codebase analysis to diagnose the root cause, and formulates a resolution plan via the `/sd-plan` process.
+사용자가 문제(버그, 에러, 비정상 동작 등)를 만났을 때, 현상을 입력받아 근본적 원인을 깊이 분석하고 해결책을 제시한다. 채택된 해결책은 debug.md로 저장되어 `/sd-plan`의 입력으로 사용 가능하다.
 
-ARGUMENTS: Error message, stack trace, or problem description (optional). If not provided, the skill infers from the conversation context or asks the user.
+## 1. 입력 파싱
 
----
+`$ARGUMENTS`에서 문제 현상 텍스트를 추출한다.
+- `$ARGUMENTS`가 비어있으면 현재 대화 맥락에서 문제 현상을 파악한다. 대화 맥락도 없으면 AskUserQuestion으로 문제 현상을 요청한다
+- 문제 현상에서 topic을 영문 kebab-case로 변환한다 (예: "createEffect 무한루프" → `create-effect-infinite-loop`, "DB 연결 타임아웃" → `db-connection-timeout`)
+- 특수문자(`#`, `/`, `\`, `(`, `)`, `.` 등)는 제거하거나 `-`로 치환한다 (예: "ORM 쿼리 오류 (v2.0)" → `orm-query-error-v2-0`)
+- 이미 kebab-case이면 그대로 사용한다
 
-## Step 1: Gather Problem Information
+## 2. 코드베이스 분석
 
-- Gather problem information in the following priority order:
-  1. **ARGUMENTS**: Error message, stack trace, or problem description passed along with the skill invocation
-  2. **Current conversation**: If no ARGUMENTS are provided, identify error messages, logs, or problem context from the current conversation
-  3. **AskUserQuestion**: If neither of the above yields sufficient information, ask: "What problem would you like to debug? Please provide an error message, stack trace, or describe the issue."
-- Extract the following from the gathered problem information:
-  - **Error type**: Compilation error / runtime error / type error / logic error / build error / unexpected behavior, etc.
-  - **Related clues**: Keywords useful for codebase exploration, such as file paths, function names, line numbers, package names, error codes, etc.
+문제 현상과 관련된 코드베이스를 분석한다.
+- Agent tool (subagent_type: Explore)을 활용하여 관련 파일, 패키지, 의존성을 탐색한다
+- 에러 메시지, 스택 트레이스, 코드 경로 등을 기반으로 관련 코드를 파악한다
+- 필요에 따라 Glob, Grep, Read 등을 직접 사용할 수도 있다
+- 분석 결과로 현재 상태, 관련 코드/패키지, 기존 구현 방식을 파악한다
 
-## Step 2: In-Depth Codebase Analysis
+## 3. 근본 원인 분석 및 해결책 제시
 
-Based on the problem information and clues gathered in Step 1, autonomously determine and perform the investigation needed to identify the root cause of the problem. Use the Agent tool (subagent_type: Explore) to explore the codebase, deciding the scope and method of investigation freely based on the nature of the problem.
+코드베이스 분석 결과를 바탕으로 문제의 근본 원인을 깊이 파고들어 분석하고, 각 원인별 해결책을 방안으로 제시한다.
 
-### Analysis Principles
+**핵심 원칙 — 편법/우회방법 절대 금지:**
+- 증상을 숨기는 해결이 아닌, 원인 자체를 제거하는 방향으로 분석한다
+- 예: `setTimeout` 추가, `try-catch`로 에러 무시, 플래그 변수로 조건 우회 등은 편법이다
+- 반드시 "왜 이 문제가 발생하는가?"를 근원까지 추적한다
 
-> **Key rule**: Do not propose solutions until you fully understand the root cause. Always follow the order: "Analyze -> Understand -> Solve."
+하나의 문제에 대해 근본 원인을 여러 관점에서 분석할 수 있다. 각 원인 분석 + 그에 따른 해결책이 하나의 **방안**이 된다.
 
-1. **Understand intended behavior first**: Before analyzing the bug, first understand what the problematic code is *supposed* to do. Read the surrounding context, callers, and tests to grasp the original intent. Document this intended behavior explicitly — it becomes the baseline that any fix must preserve.
-2. **No speculative fixes**: Do not attempt to find the cause through trial-and-error by modifying code and checking results. Read the code and trace the logic to identify the cause.
-3. **No workarounds**: Do not propose solutions that mask symptoms, such as `as` type assertions, `any`, `// @ts-ignore`, hardcoding, or swallowing exceptions (ignoring after `catch`).
-4. **Test failure triage**: When tests fail, first compare the intended behavior the test validates against the code's actual behavior. If the behavior change was intentional, update the test; if unintentional, fix the code. If intent cannot be determined, ask the user.
-5. **Distinguish symptoms from causes**: The point where the error message appears may not be the actual cause. Trace back from the error location to find the real cause.
+다음 구조로 방안들을 제시한다:
 
-### Organize Analysis Results
+```
+### 방안 1: {방안 제목}
+- 근본 원인: {이 관점에서 본 원인 상세 분석}
+- 해결 방안: {상세 설명}
+- 점수: {N}/10
+
+### 방안 2: {방안 제목}
+- 근본 원인: {이 관점에서 본 원인 상세 분석}
+- 해결 방안: {상세 설명}
+- 점수: {N}/10
+
+### 방안 3: {방안 제목}
+- 근본 원인: {이 관점에서 본 원인 상세 분석}
+- 해결 방안: {상세 설명}
+- 점수: {N}/10
+
+### 반론
+- 설명: {이 문제를 굳이 수정하지 않아도 되는 이유}
+- 점수: {N}/10
+```
 
-Once the analysis is complete, organize the following items:
-- **Intended behavior**: What the problematic code is supposed to do (the baseline that must be preserved)
-- **Error location**: The specific code location where the problem occurs (file_path:line)
-- **Root cause**: Analysis of why this problem occurs
-- **Impact scope**: List of files/functions affected by this problem
-- **Resolution options**: Possible solutions (including target files for each)
+- 1개 이상의 방안을 제시한다 (방안 수는 유동적)
+- 각 방안과 "반론"은 모두 10점 만점으로 점수를 부여한다
+- 점수 기준: 높을수록 해당 선택이 적절함을 의미한다
+- 모든 방안은 편법/우회가 아닌 근원적 해결책이어야 한다
 
-## Step 3: Consolidate Diagnosis and User Confirmation
+## 4. 결과 표시 및 선택
 
-Consolidate the analysis results from Step 2 into a diagnostic report in the format below and present it to the user:
+근본 원인 분석 결과 방안이 하나도 도출되지 않은 경우 "분석 결과 코드베이스에서 근본 원인을 식별할 수 없습니다."를 출력하고 문서 저장 없이 종료한다.
 
-```
-## Diagnosis Results
+1. 모든 방안을 **자세한 설명을 텍스트로 먼저 출력**한다
+   - 각 방안의 근본 원인 분석 + 해결 방안 + 점수를 명확히 표시
+   - 반론의 상세 설명 + 점수를 명확히 표시
+   - 각 선택지 간 트레이드오프를 포함
+2. **자동 결정 조건**에 해당하면 결정 결과를 텍스트로 출력한다
+3. 자동 결정 조건에 해당하지 않으면 `AskUserQuestion`을 **1개만** 호출하여 방안 선택을 요청한다
+   - 선택지: 각 방안명 + "안함"
 
-### Problem Summary
-<Summarize the error/problem in one sentence>
+**자동 결정 조건 (묻지 않는 경우):**
 
-### Intended Behavior
-<Describe what the problematic code is supposed to do. This is the baseline — any fix must preserve this behavior.>
+모든 선택지(방안들 + 반론)를 동등하게 놓고 비교한다:
+- 반론 점수가 모든 방안 점수보다 높으면 (단 1점이라도) → 무조건 자동 거부 (안함, 사용자에게 묻지 않음)
+  - 예: 방안1 5점, 방안2 3점, 반론 6점 → 반론(6) > 방안1(5) 이므로 무조건 자동 거부
+- 가장 높은 점수가 나머지 모든 점수 각각의 2배 이상이면 → 자동 결정
+  - 가장 높은 것이 방안이면 → 해당 방안 자동 채택
+  - 가장 높은 것이 반론이면 → 자동 거부 (안함)
+- 예: 방안1 8점, 방안2 3점, 반론 2점 → 8 ≥ 3×2 이고 8 ≥ 2×2 이므로 방안1 자동 채택
+- 예: 방안1 6점, 방안2 5점, 반론 4점 → 6 < 5×2 이므로 자동 결정 미충족 → AskUserQuestion
+- 예: 방안1 3점, 방안2 2점, 반론 8점 → 8 ≥ 3×2 이고 8 ≥ 2×2 이므로 자동 거부
+- 모든 선택지의 점수가 0이면 → "분석 결과 유효한 해결책을 도출할 수 없습니다."를 출력하고 종료한다
+- 가장 높은 점수가 동점이면 → 자동 결정 불가 → AskUserQuestion으로 사용자에게 질문
 
-### Root Cause
-<Explain the root cause clearly and specifically. Include file paths and line numbers.>
+## 5. 결과 문서 저장
 
-### Impact Scope
-- <Affected file/function 1>
-- <Affected file/function 2>
+채택된 방안을 debug.md로 저장한다.
 
-### Resolution Options
+**파일 경로:**
+- 디렉토리: `.tasks/{yyMMddHHmmss}_{topic}/`
+  - `yyMMddHHmmss`는 현재 시간 (Bash `date +%y%m%d%H%M%S`로 생성)
+  - `{topic}`은 1단계에서 변환한 kebab-case topic
+- 파일명: `debug.md`
+- 디렉토리가 없으면 먼저 생성한다
 
-1. **<Option 1 title>**: <Description>
-   - Target files: <List of file paths>
-   - Behavioral change: <Does this change any existing behavior? "None — preserves intended behavior" or describe what changes>
-   - Pros: ...
-   - Cons: ...
+**debug.md 구조:**
 
-2. **<Option 2 title>**: <Description> (if applicable)
-   - Target files: <List of file paths>
-   - Behavioral change: <Does this change any existing behavior? "None — preserves intended behavior" or describe what changes>
-   - Pros: ...
-   - Cons: ...
+```markdown
+# 디버그 결과: {topic 설명}
 
-### Recommended Option
-<The most appropriate option and the reasoning>
-```
+## 개요
 
-After outputting the diagnostic report, ask the following via AskUserQuestion:
+{문제 현상의 목적과 배경}
 
-```
-Please review the diagnosis results.
-1. The diagnosis is accurate — proceed with the recommended option
-2. The diagnosis is accurate, but proceed with a different option (specify number)
-3. The diagnosis is inaccurate — I will provide additional information
-```
+## 현재 상태
 
-- **Option 1 selected**: Proceed to Step 4 based on the recommended option.
-- **Option 2 selected**: Proceed to Step 4 based on the option specified by the user.
-- **Option 3 selected**: Return to Step 2 incorporating the additional information provided by the user.
+{코드베이스 분석 결과 - 관련 기존 코드/패키지, 현재 구현 방식, 관련 의존성}
 
-## Step 4: Formulate Resolution Plan via sd-plan
+## 요구사항
 
-Using the user-confirmed diagnosis and the selected resolution option as the task description, invoke `sd-plan` via the Skill tool. Pass the following in args:
-
-```
-Formulate a plan to implement the resolution based on the following debugging diagnosis:
+### R1. {채택된 방안명}
 
-## Problem
-<Problem summary from Step 3>
+**근본 원인**
 
-## Root Cause
-<Root cause from Step 3>
+{채택된 방안의 근본 원인 상세 분석}
 
-## Resolution
-<Detailed content of the resolution option selected by the user>
+**해결 방안**
 
-## Target Files
-<List of target file paths from the resolution option>
+{채택된 방안의 상세 내용}
 ```
 
-## Step 5: Execute the Plan
+- "안함"이 선택된 경우 debug.md를 저장하지 않고 "채택된 해결책이 없어 문서를 저장하지 않습니다."를 출력한다
 
-Once sd-plan completes and produces a finalized plan, modify the code according to that plan.
+## 6. 완료 안내
 
-After applying the fix, verify that the intended behavior documented in Step 2 is preserved. Review the changes and confirm they correct the defect without altering what the code is supposed to do.
+문서 작성이 완료되면 다음을 출력한다:
+- 완성된 문서의 파일 경로
+- 사용자에게 직접 문서를 확인할 것을 권장
+- 다음 단계 안내: "다음 단계로 `/sd-plan`을 실행하세요."

package/claude/skills/sd-document/SKILL.md

@@ -1,109 +1,115 @@
 ---
 name: sd-document
-description: Used when requesting "read/analyze documents", "extract file content", "create DOCX/XLSX", "review customer documents", or "export data" related to .docx, .xlsx, .pptx, .pdf files.
+description: 문서 파일(.docx/.xlsx/.pptx/.pdf)을 읽어 분석하거나, 새 문서를 생성. 사용자가 워드/엑셀/PPT/PDF 파일의 분석이나 생성을 요청할 때 사용
+argument-hint: "<문서 파일 경로>"
 ---
 
-# SD Document — Read/Write Document Files
+# sd-document: 문서 파일 읽기/쓰기
 
-Reads or writes document files (.docx/.xlsx/.pptx/.pdf) using Python scripts. When reading, extracts text and images along with positional information, saves images to files, and analyzes them with Claude Read.
+문서 파일(.docx/.xlsx/.pptx/.pdf)을 Python 스크립트로 읽어 텍스트와 이미지를 추출하거나, 새 문서를 생성한다.
 
-ARGUMENTS: Document file path (required). Specify a `.docx`, `.xlsx`, `.pptx`, or `.pdf` file path.
+## 1. 인자 파싱
 
----
+`$ARGUMENTS`에서 문서 파일 경로를 추출한다.
+- `$ARGUMENTS`가 비어있으면 현재 대화 맥락에서 `.docx`, `.xlsx`, `.pptx`, `.pdf` 파일 경로를 찾는다. 대화 맥락도 없으면 AskUserQuestion으로 파일 경로를 요청한다
+- 지원 확장자(`.docx`, `.xlsx`, `.pptx`, `.pdf`)가 아니면 "지원하지 않는 파일 형식입니다"를 안내하고 종료한다
 
-## Step 1: Determine Task Direction
+## 2. 작업 방향 결정
 
-Extract the file path from ARGUMENTS and determine whether the user's request is **read** (analyze/extract) or **write** (create/edit).
+사용자의 요청이 **읽기**(분석/추출)인지 **쓰기**(생성)인지 **편집**(기존 파일 수정)인지 판단한다.
 
-- **Read** → Go to Step 2
-- **Write** → Go to Step 4
+- **읽기** → 3단계로 이동
+- **쓰기** → 5단계로 이동
+- **편집** → 3단계로 먼저 이동하여 기존 내용을 파악한 뒤, 5단계에서 수정 스크립트를 작성한다
 
-### Format Support Matrix
+### 포맷별 지원 현황
 
-| Format | Read | Write | Library |
-|--------|------|-------|---------|
-| DOCX | Supported | Supported | `python-docx` |
-| XLSX | Supported | Supported | `openpyxl`, `pandas` |
-| PPTX | Supported | Not supported | `python-pptx` |
-| PDF  | Supported | Not supported | `pdfplumber`, `pypdf` |
+| 포맷 | 읽기 | 쓰기 | 라이브러리 |
+|------|------|------|-----------|
+| DOCX | 지원 | 지원 | `python-docx` |
+| XLSX | 지원 | 지원 | `openpyxl`, `pandas` |
+| PPTX | 지원 | 미지원 | `python-pptx` |
+| PDF  | 지원 | 미지원 | `pdfplumber`, `pypdf` |
 
-Missing packages are automatically installed on first script execution.
+누락 패키지는 스크립트 최초 실행 시 자동 설치된다.
 
-## Step 2: Read Document (Run Extraction Script)
+## 3. 읽기: 추출 스크립트 실행
 
-Run the extraction script matching the file extension:
+파일 확장자에 맞는 추출 스크립트를 Bash로 실행한다:
 
 ```bash
-python .claude/skills/sd-document/extract_docx.py <file_path>
-python .claude/skills/sd-document/extract_xlsx.py <file_path>
-python .claude/skills/sd-document/extract_pptx.py <file_path>
-python .claude/skills/sd-document/extract_pdf.py  <file_path>
+python ${CLAUDE_SKILL_DIR}/extract_docx.py <파일경로>
+python ${CLAUDE_SKILL_DIR}/extract_xlsx.py <파일경로>
+python ${CLAUDE_SKILL_DIR}/extract_pptx.py <파일경로>
+python ${CLAUDE_SKILL_DIR}/extract_pdf.py  <파일경로>
 ```
 
-### Output
-- **stdout**: Text and positional information (Markdown format)
-- **Image files**: Saved to `<filename>_files/` directory
+### 출력
 
-### Positional Information
+- **stdout**: 텍스트 및 위치 정보 (Markdown 형식)
+- **이미지 파일**: `<파일명>_files/` 디렉토리에 저장
 
-| Format | Position Representation |
-|--------|----------------------|
-| DOCX | Paragraph flow order (text-image inline) |
-| XLSX | Cell position (A1, B2, etc.) |
-| PPTX | Shape left/top coordinates (inches) + slide number |
-| PDF  | Page number |
+### 위치 정보
 
-## Step 3: Analyze Extraction Results
+| 포맷 | 위치 표현 |
+|------|----------|
+| DOCX | 문단 흐름 순서 (텍스트-이미지 인라인) |
+| XLSX | 셀 위치 (A1, B2 등) |
+| PPTX | Shape 좌표 (left/top 인치) + 슬라이드 번호 |
+| PDF  | 페이지 번호 |
 
-Check the extracted file paths from Step 2 output and perform the following:
+## 4. 읽기: 추출 결과 분석
 
-1. **Images**: Open each image saved in the `_files/` directory with the **Read** tool for visual analysis
-2. **Text**: Analyze/summarize the text output to stdout according to the user's request
+3단계 출력에서 추출된 파일 경로를 확인하고 다음을 수행한다:
 
-## Step 4: Write Document
+1. **이미지**: `_files/` 디렉토리에 저장된 각 이미지를 **Read** 도구로 열어 시각적 분석
+2. **텍스트**: stdout에 출력된 텍스트를 사용자 요청에 맞게 분석/요약
 
-Write a Python script to create or edit documents according to the user's request.
+분석 완료 후 종료한다.
 
-### DOCX (`python-docx`)
+## 5. 쓰기: 문서 생성/편집
 
-For email templates and simple reports.
+사용자 요청에 따라 Python 스크립트를 작성하여 문서를 생성하거나 편집한다.
+PPTX, PDF 쓰기는 미지원이므로 요청 시 안내한다.
+
+### DOCX (`python-docx`)
 
 ```python
 from docx import Document
 
-doc = Document()                          # New document
-# doc = Document("existing.docx")         # Edit existing document
-doc.add_heading("Title", level=1)
-doc.add_paragraph("Body content")
+doc = Document()                          # 새 문서
+# doc = Document("existing.docx")         # 기존 문서 편집
+doc.add_heading("제목", level=1)
+doc.add_paragraph("본문 내용")
 table = doc.add_table(rows=2, cols=3)
-table.cell(0, 0).text = "Item"
+table.cell(0, 0).text = "항목"
 doc.save("output.docx")
 ```
 
-Edit existing document: Open with `Document("existing.docx")` and replace `paragraph.text`, modify `table.cell().text`.
+기존 문서 편집: `Document("existing.docx")`로 열어 `paragraph.text`, `table.cell().text`를 수정한다.
 
 ### XLSX (`openpyxl`)
 
-Data and formula focused. Formatting (colors, borders) is not required.
+데이터와 수식 중심. 서식(색상, 테두리)은 필수가 아니다.
 
 ```python
 from openpyxl import Workbook
 
 wb = Workbook()
 ws = wb.active
-ws["A1"] = "Item"
-ws["B1"] = "Quantity"
-ws.append(["Apple", 10])
-ws.append(["Pear", 20])
+ws["A1"] = "항목"
+ws["B1"] = "수량"
+ws.append(["사과", 10])
+ws.append(["배", 20])
 ws["B4"] = "=SUM(B2:B3)"
 wb.save("output.xlsx")
 ```
 
-Edit existing file: Open with `load_workbook("existing.xlsx")` and modify.
-Export pandas DataFrame: `df.to_excel("output.xlsx", index=False)`
+기존 파일 편집: `load_workbook("existing.xlsx")`로 열어 수정한다.
+pandas DataFrame 내보내기: `df.to_excel("output.xlsx", index=False)`
 
-## Common Mistakes
+## 6. 주의사항
 
-- **Character encoding**: Scripts have built-in UTF-8 handling, so always extract through scripts
-- **Missing images**: After extraction, always read images in the `_files/` directory
-- **XLSX data_only**: `load_workbook(data_only=True)` removes formulas — use `data_only=False` to preserve formulas
+- **문자 인코딩**: 스크립트에 UTF-8 처리가 내장되어 있으므로 반드시 스크립트를 통해 추출한다
+- **이미지 누락**: 추출 후 `_files/` 디렉토리의 이미지를 반드시 Read한다
+- **XLSX data_only**: `load_workbook(data_only=True)`는 수식을 제거한다. 수식 보존이 필요하면 `data_only=False`를 사용한다

package/claude/skills/sd-document/_common.py

@@ -32,13 +32,8 @@ def print_header(file_path: Path):
     print(f"# {file_path.name}\n")
 
 
-_created_dirs: set[Path] = set()
-
-
 def save_image(out_dir: Path, img_idx: int, blob: bytes, ext: str) -> Path:
-    if out_dir not in _created_dirs:
-        out_dir.mkdir(parents=True, exist_ok=True)
-        _created_dirs.add(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
     img_path = out_dir / f"img_{img_idx:03d}.{ext}"
     img_path.write_bytes(blob)
     return img_path

package/claude/skills/sd-document/extract_docx.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """Extract text and images from DOCX files in paragraph flow order."""
 
-import sys
 from _common import (
     setup_encoding, make_output_paths, print_header, save_image,
     ext_from_content_type, print_image_summary, run_cli,