Skill 작성 모범 사례

## PDF 텍스트 추출

텍스트 추출을 위해 pdfplumber를 사용하세요:

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## PDF 텍스트 추출

PDF(Portable Document Format) 파일은 텍스트, 이미지 및 기타 콘텐츠를 포함하는 일반적인 파일 형식입니다. PDF에서 텍스트를 추출하려면 라이브러리를 사용해야 합니다. PDF 처리에 사용할 수 있는 많은 라이브러리가 있지만, pdfplumber를 권장합니다. 사용하기 쉽고 대부분의 경우를 잘 처리하기 때문입니다. 먼저 pip를 사용하여 설치해야 합니다. 그런 다음 아래 코드를 사용할 수 있습니다...

## 코드 리뷰 프로세스

1. 코드 구조와 조직을 분석합니다
2. 잠재적 버그나 엣지 케이스를 확인합니다
3. 가독성과 유지보수성 개선을 제안합니다
4. 프로젝트 규칙 준수를 확인합니다

## 보고서 생성

이 템플릿을 사용하고 필요에 따라 사용자 정의하세요:

```python
def generate_report(data, format="markdown", include_charts=True):
    # 데이터 처리
    # 지정된 형식으로 출력 생성
    # 선택적으로 시각화 포함
```

## 데이터베이스 마이그레이션

정확히 이 스크립트를 실행하세요:

```bash
python scripts/migrate.py --verify --backup
```

명령을 수정하거나 추가 플래그를 추가하지 마세요.

description: PDF 파일에서 텍스트 및 표 추출, 양식 작성, 문서 병합. PDF 파일로 작업하거나 사용자가 PDF, 양식 또는 문서 추출을 언급할 때 사용합니다.

description: Excel 스프레드시트 분석, 피벗 테이블 생성, 차트 생성. Excel 파일, 스프레드시트, 표 형식 데이터 또는 .xlsx 파일을 분석할 때 사용합니다.

description: git diff를 분석하여 설명적인 커밋 메시지 생성. 사용자가 커밋 메시지 작성 또는 스테이징된 변경 사항 검토에 대한 도움을 요청할 때 사용합니다.

description: 문서 작업을 도와줍니다

description: 데이터를 처리합니다

description: 파일로 작업을 수행합니다

pdf/
├── SKILL.md              # 주요 지침 (트리거될 때 로드됨)
├── FORMS.md              # 양식 작성 가이드 (필요에 따라 로드됨)
├── reference.md          # API 참조 (필요에 따라 로드됨)
├── examples.md           # 사용 예 (필요에 따라 로드됨)
└── scripts/
    ├── analyze_form.py   # 유틸리티 스크립트 (로드되지 않고 실행됨)
    ├── fill_form.py      # 양식 작성 스크립트
    └── validate.py       # 검증 스크립트

---
name: pdf-processing
description: PDF 파일에서 텍스트 및 표 추출, 양식 작성, 문서 병합. PDF 파일로 작업하거나 사용자가 PDF, 양식 또는 문서 추출을 언급할 때 사용합니다.
---

# PDF 처리

## 빠른 시작

pdfplumber로 텍스트 추출:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 고급 기능

**양식 작성**: 전체 가이드는 [FORMS.md](FORMS.md) 참조
**API 참조**: 모든 메서드는 [REFERENCE.md](REFERENCE.md) 참조
**예**: 일반적인 패턴은 [EXAMPLES.md](EXAMPLES.md) 참조

bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
    ├── finance.md (수익, 청구 지표)
    ├── sales.md (기회, 파이프라인)
    ├── product.md (API 사용, 기능)
    └── marketing.md (캠페인, 속성)

# DOCX 처리

## 문서 생성

새 문서에 docx-js를 사용하세요. [DOCX-JS.md](DOCX-JS.md) 참조.

## 문서 편집

간단한 편집의 경우 XML을 직접 수정하세요.

**추적된 변경의 경우**: [REDLINING.md](REDLINING.md) 참조
**OOXML 세부 정보의 경우**: [OOXML.md](OOXML.md) 참조

# SKILL.md
[advanced.md](advanced.md) 참조...

# advanced.md
[details.md](details.md) 참조...

# details.md
실제 정보는 여기...

# SKILL.md

**기본 사용**: [SKILL.md의 지침]
**고급 기능**: [advanced.md](advanced.md) 참조
**API 참조**: [reference.md](reference.md) 참조
**예**: [examples.md](examples.md) 참조

# API 참조

## 목차
- 인증 및 설정
- 핵심 메서드 (생성, 읽기, 업데이트, 삭제)
- 고급 기능 (배치 작업, 웹훅)
- 오류 처리 패턴
- 코드 예

## 인증 및 설정
...

## 핵심 메서드
...

## 연구 종합 워크플로우

이 체크리스트를 복사하고 진행 상황을 추적하세요:

```
연구 진행:
- [ ] 단계 1: 모든 소스 문서 읽기
- [ ] 단계 2: 주요 테마 식별
- [ ] 단계 3: 주장 교차 참조
- [ ] 단계 4: 구조화된 요약 생성
- [ ] 단계 5: 인용 확인
```

**단계 1: 모든 소스 문서 읽기**

`sources/` 디렉토리의 각 문서를 검토하세요. 주요 주장과 뒷받침하는 증거를 기록하세요.

**단계 2: 주요 테마 식별**

소스 전체에서 패턴을 찾으세요. 어떤 테마가 반복적으로 나타나나요? 소스가 동의하거나 불일치하는 곳은 어디인가요?

**단계 3: 주장 교차 참조**

각 주요 주장에 대해 소스 자료에 나타나는지 확인하세요. 각 포인트를 지원하는 소스를 기록하세요.

**단계 4: 구조화된 요약 생성**

테마별로 결과를 구성하세요. 다음을 포함하세요:
- 주요 주장
- 소스의 뒷받침하는 증거
- 상충하는 관점 (있는 경우)

**단계 5: 인용 확인**

모든 주장이 올바른 소스 문서를 참조하는지 확인하세요. 인용이 불완전하면 단계 3으로 돌아가세요.

## PDF 양식 작성 워크플로우

이 체크리스트를 복사하고 완료하면서 체크하세요:

```
작업 진행:
- [ ] 단계 1: 양식 분석 (analyze_form.py 실행)
- [ ] 단계 2: 필드 매핑 생성 (fields.json 편집)
- [ ] 단계 3: 매핑 검증 (validate_fields.py 실행)
- [ ] 단계 4: 양식 작성 (fill_form.py 실행)
- [ ] 단계 5: 출력 확인 (verify_output.py 실행)
```

**단계 1: 양식 분석**

실행: `python scripts/analyze_form.py input.pdf`

이는 양식 필드와 위치를 추출하여 `fields.json`에 저장합니다.

**단계 2: 필드 매핑 생성**

`fields.json`을 편집하여 각 필드에 값을 추가하세요.

**단계 3: 매핑 검증**

실행: `python scripts/validate_fields.py fields.json`

계속하기 전에 검증 오류를 수정하세요.

**단계 4: 양식 작성**

실행: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**단계 5: 출력 확인**

실행: `python scripts/verify_output.py output.pdf`

검증이 실패하면 단계 2로 돌아가세요.

## 콘텐츠 검토 프로세스

1. STYLE_GUIDE.md의 지침에 따라 콘텐츠를 작성하세요
2. 체크리스트에 대해 검토하세요:
   - 용어 일관성 확인
   - 예가 표준 형식을 따르는지 확인
   - 필요한 모든 섹션이 있는지 확인
3. 문제가 발견된 경우:
   - 각 문제를 특정 섹션 참조와 함께 기록하세요
   - 콘텐츠를 수정하세요
   - 체크리스트를 다시 검토하세요
4. 모든 요구사항이 충족될 때만 진행하세요
5. 문서를 완성하고 저장하세요

## 문서 편집 프로세스

1. `word/document.xml`에 편집을 수행하세요
2. **즉시 검증**: `python ooxml/scripts/validate.py unpacked_dir/`
3. 검증이 실패하면:
   - 오류 메시지를 주의 깊게 검토하세요
   - XML의 문제를 수정하세요
   - 검증을 다시 실행하세요
4. **검증이 통과할 때만 진행하세요**
5. 다시 빌드: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. 출력 문서를 테스트하세요

2025년 8월 이전에 이를 수행하는 경우 이전 API를 사용하세요.
2025년 8월 이후에는 새 API를 사용하세요.

## 현재 방법

v2 API 엔드포인트를 사용하세요: `api.example.com/v2/messages`

## 이전 패턴

<details>
<summary>레거시 v1 API (2025-08 사용 중단됨)</summary>

v1 API는 다음을 사용했습니다: `api.example.com/v1/messages`

이 엔드포인트는 더 이상 지원되지 않습니다.
</details>

## 보고서 구조

항상 이 정확한 템플릿 구조를 사용하세요:

```markdown
# [분석 제목]

## 요약
[주요 결과의 한 단락 개요]

## 주요 결과
- 뒷받침하는 데이터가 있는 결과 1
- 뒷받침하는 데이터가 있는 결과 2
- 뒷받침하는 데이터가 있는 결과 3

## 권장사항
1. 구체적인 실행 가능한 권장사항
2. 구체적인 실행 가능한 권장사항
```

## 보고서 구조

다음은 합리적인 기본 형식이지만 분석에 따라 최선의 판단을 사용하세요:

```markdown
# [분석 제목]

## 요약
[개요]

## 주요 결과
[발견한 내용에 따라 섹션 조정]

## 권장사항
[특정 컨텍스트에 맞게 조정]
```

필요에 따라 섹션을 조정하세요.

## 커밋 메시지 형식

다음 예를 따르는 커밋 메시지를 생성하세요:

**예 1:**
입력: JWT 토큰으로 사용자 인증 추가
출력:
```
feat(auth): JWT 기반 인증 구현

로그인 엔드포인트 및 토큰 검증 미들웨어 추가
```

**예 2:**
입력: 보고서에서 날짜가 잘못 표시되는 버그 수정
출력:
```
fix(reports): 시간대 변환에서 날짜 형식 수정

보고서 생성 전체에서 UTC 타임스탬프를 일관되게 사용
```

**예 3:**
입력: 의존성 업데이트 및 오류 처리 리팩토링
출력:
```
chore: 의존성 업데이트 및 오류 처리 리팩토링

- lodash를 4.17.21로 업그레이드
- 엔드포인트 전체에서 오류 응답 형식 표준화
```

이 스타일을 따르세요: type(scope): 간단한 설명, 그 다음 상세 설명.

## 문서 수정 워크플로우

1. 수정 유형을 결정하세요:

   **새 콘텐츠를 생성하나요?** → 아래 "생성 워크플로우" 따르기
   **기존 콘텐츠를 편집하나요?** → 아래 "편집 워크플로우" 따르기

2. 생성 워크플로우:
   - docx-js 라이브러리 사용
   - 처음부터 문서 빌드
   - .docx 형식으로 내보내기

3. 편집 워크플로우:
   - 기존 문서 압축 해제
   - XML 직접 수정
   - 각 변경 후 검증
   - 완료 시 다시 압축

{
  "skills": ["pdf-processing"],
  "query": "이 PDF 파일에서 모든 텍스트를 추출하고 output.txt에 저장하세요",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "적절한 PDF 처리 라이브러리 또는 명령줄 도구를 사용하여 PDF 파일을 성공적으로 읽습니다",
    "페이지를 놓치지 않고 문서의 모든 페이지에서 텍스트 콘텐츠를 추출합니다",
    "추출된 텍스트를 명확하고 읽기 쉬운 형식으로 output.txt라는 파일에 저장합니다"
  ]
}

**나쁜 예: 너무 많은 선택** (혼란스러움):
"pypdf, pdfplumber, PyMuPDF, pdf2image 또는... 를 사용할 수 있습니다"

**좋은 예: 기본값 제공** (탈출구 포함):
"텍스트 추출을 위해 pdfplumber를 사용하세요:
```python
import pdfplumber
```

OCR이 필요한 스캔된 PDF의 경우 대신 pdf2image와 pytesseract를 사용하세요."

def process_file(path):
    """파일을 처리하고 존재하지 않으면 생성합니다."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # 실패하는 대신 기본 콘텐츠로 파일 생성
        print(f"파일 {path}을(를) 찾을 수 없어 기본값 생성")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # 실패하는 대신 대안 제공
        print(f"{path}에 액세스할 수 없어 기본값 사용")
        return ''

def process_file(path):
    # 그냥 실패하고 Claude가 알아내도록 하기
    return open(path).read()

# HTTP 요청은 일반적으로 30초 이내에 완료됩니다
# 더 긴 타임아웃은 느린 연결을 고려합니다
REQUEST_TIMEOUT = 30

# 3번의 재시도는 안정성과 속도의 균형을 맞춥니다
# 대부분의 일시적 실패는 두 번째 재시도로 해결됩니다
MAX_RETRIES = 3

TIMEOUT = 47  # 왜 47?
RETRIES = 5   # 왜 5?

## 유틸리티 스크립트

**analyze_form.py**: PDF에서 모든 양식 필드 추출

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

출력 형식:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: 겹치는 경계 상자 확인

```bash
python scripts/validate_boxes.py fields.json
# 반환: "OK" 또는 충돌 나열
```

**fill_form.py**: PDF에 필드 값 적용

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

## 양식 레이아웃 분석

1. PDF를 이미지로 변환:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. 각 페이지 이미지를 분석하여 양식 필드 식별
3. Claude는 시각적으로 필드 위치 및 유형을 볼 수 있음

bigquery-skill/
├── SKILL.md (개요, 참조 파일 지시)
└── reference/
    ├── finance.md (수익 지표)
    ├── sales.md (파이프라인 데이터)
    └── product.md (사용 분석)

BigQuery:bigquery_schema 도구를 사용하여 테이블 스키마를 검색합니다.
GitHub:create_issue 도구를 사용하여 문제를 생성합니다.

**나쁜 예: 설치를 가정**:
"pdf 라이브러리를 사용하여 파일을 처리합니다."

**좋은 예: 의존성에 대해 명시적**:
"필수 패키지 설치: `pip install pypdf`

그런 다음 사용:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"