# 스킬 작성 가이드

하네스에서 생성하는 스킬의 품질을 높이기 위한 상세 작성 가이드. SKILL.md Phase 4의 보충 레퍼런스.

---

## 목차

1. [Description 작성 패턴](#1-description-작성-패턴)
2. [본문 작성 스타일](#2-본문-작성-스타일)
3. [출력 형식 정의 패턴](#3-출력-형식-정의-패턴)
4. [예시 작성 패턴](#4-예시-작성-패턴)
5. [Progressive Disclosure 패턴](#5-progressive-disclosure-패턴)
6. [스크립트 번들링 판단 기준](#6-스크립트-번들링-판단-기준)
7. [데이터 스키마 표준](#7-데이터-스키마-표준)
8. [스킬에 포함하지 않을 것](#8-스킬에-포함하지-않을-것)

---

## 1. Description 작성 패턴

Description은 스킬의 유일한 트리거 메커니즘이다. Claude는 `available_skills` 목록에서 name + description만 보고 스킬 사용 여부를 결정한다.

### 트리거 메커니즘 이해

Claude는 자신의 기본 도구로 쉽게 처리할 수 있는 단순 작업에는 스킬을 호출하지 않는 경향이 있다. "이 PDF 읽어줘" 같은 단순 요청은 description이 완벽해도 트리거되지 않을 수 있다. 복잡하고 다단계이며 전문적인 작업일수록 스킬 트리거 확률이 높다.

### 작성 원칙

1. **스킬이 하는 일** + **구체적 트리거 상황**을 모두 기술
2. 유사하지만 트리거하면 안 되는 경우를 구분하는 경계 조건 명시
3. 약간 "pushy"하게 — Claude가 트리거를 보수적으로 판단하는 경향을 보상

### 좋은 예시

```yaml
description: "PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크,
  암호화/복호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나
  PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것. 단순히 PDF를
  '읽어달라'는 요청이 아닌 변환/편집/분석이 필요할 때 특히 유용."
```

```yaml
description: "엑셀/CSV/TSV 파일의 열 추가, 수식 계산, 서식, 차트,
  데이터 정제를 포함한 모든 스프레드시트 작업. 사용자가 스프레드시트
  파일을 언급하면 — 심지어 캐주얼하게('다운로드 폴더의 xlsx')라고만
  해도 — 이 스킬을 사용할 것."
```

### 나쁜 예시

- `"데이터를 처리하는 스킬"` — 너무 모호, 어떤 파일/작업인지 불분명
- `"PDF 관련 작업"` — 구체적 동작 나열 없음, 트리거 상황 미기술

---

## 2. 본문 작성 스타일

### Why-First 원칙

LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. 강압적 규칙보다 맥락 전달이 효과적이다.

**나쁜 예:**
```markdown
ALWAYS use pdfplumber for table extraction. NEVER use PyPDF2 for tables.
```

**좋은 예:**
```markdown
테이블 추출에는 pdfplumber를 사용한다. PyPDF2는 텍스트 추출에 특화되어
있어 테이블의 행/열 구조를 보존하지 못하기 때문이다. pdfplumber는
셀 경계를 인식하여 구조화된 데이터를 반환한다.
```

### 일반화 원칙

피드백이나 테스트 결과에서 문제가 발견되면, 특정 예시에만 맞는 좁은 수정 대신 **원리 수준에서 일반화**한다.

**오버피팅 수정:**
```markdown
"Q4 매출" 열이 있으면 해당 열을 숫자로 변환하라.
```

**일반화된 수정:**
```markdown
열 이름에 "매출", "금액", "수량" 등 수치를 암시하는 키워드가 있으면
해당 열을 숫자 타입으로 변환한다. 변환 실패 시 원본 값을 유지한다.
```

### 명령형 어조

"~합니다", "~할 수 있습니다" 대신 "~한다", "~하라" 형태를 사용한다. 스킬은 지시서이다.

### 컨텍스트 절약

컨텍스트 윈도우는 공공재다. 모든 문장이 토큰 비용을 정당화하는지 자문한다:
- "Claude가 이미 알고 있는 내용인가?" → 삭제
- "이 설명이 없으면 Claude가 실수하는가?" → 유지
- "구체적 예시 하나가 긴 설명보다 효과적인가?" → 예시로 대체

---

## 3. 출력 형식 정의 패턴

산출물의 형식이 중요한 스킬에서 사용:

```markdown
## 보고서 구조
다음 템플릿을 정확히 따른다:

# [제목]
## 요약
## 핵심 발견
## 권장 사항
```

형식 정의는 간결하게, 실제 예시를 포함하면 더 효과적이다.

---

## 4. 예시 작성 패턴

예시는 긴 설명보다 효과적이다:

```markdown
## 커밋 메시지 형식

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

**예시 2:**
입력: 로그인 페이지에서 비밀번호 표시 버튼이 동작하지 않는 버그 수정
출력: fix(login): 비밀번호 표시 토글 버튼 동작 수정
```

---

## 5. Progressive Disclosure 패턴

### 패턴 1: 도메인별 분리

```
bigquery-skill/
├── SKILL.md (개요 + 도메인 선택 가이드)
└── references/
    ├── finance.md (매출, 빌링 메트릭)
    ├── sales.md (기회, 파이프라인)
    └── product.md (API 사용량, 기능)
```

사용자가 매출에 대해 물으면 finance.md만 로드.

### 패턴 2: 조건부 상세

```markdown
# DOCX 처리

## 문서 생성
docx-js로 새 문서를 생성한다. → [DOCX-JS.md](references/docx-js.md) 참조.

## 문서 편집
단순 편집은 XML을 직접 수정.
**추적 변경이 필요하면**: [REDLINING.md](references/redlining.md) 참조
```

### 패턴 3: 대형 레퍼런스 파일 구조

300줄 이상의 reference 파일은 상단에 목차를 포함한다:

```markdown
# API 레퍼런스

## 목차
1. [인증](#인증)
2. [엔드포인트 목록](#엔드포인트-목록)
3. [에러 코드](#에러-코드)
4. [레이트 리밋](#레이트-리밋)

---

## 인증
...
```

---

## 6. 스크립트 번들링 판단 기준

테스트 실행에서 에이전트들의 트랜스크립트를 관찰한다. 다음 패턴이 보이면 번들링 대상:

| 신호 | 조치 |
|------|------|
| 3개 테스트 중 3개에서 동일한 헬퍼 스크립트 생성 | `scripts/`에 번들링 |
| 매번 같은 pip install/npm install 실행 | 스킬에 의존성 설치 단계 명시 |
| 동일한 다단계 접근법 반복 | 스킬 본문에 표준 절차로 기술 |
| 매번 비슷한 에러 후 같은 회피책 적용 | 스킬에 알려진 문제와 해결법 기술 |

번들링된 스크립트는 반드시 실행 테스트를 거친다.

---

## 7. 데이터 스키마 표준

스킬 간 데이터 교환의 일관성을 위해 표준 스키마를 사용한다. 하네스에서 생성하는 스킬의 테스트/평가에 사용할 수 있다.

### eval_metadata.json

각 테스트 케이스의 메타데이터:

```json
{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "사용자의 작업 프롬프트",
  "assertions": [
    "산출물에 X가 포함되어 있다",
    "Y 형식으로 파일이 생성되었다"
  ]
}
```

### grading.json

assertion 기반 채점 결과:

```json
{
  "expectations": [
    {
      "text": "산출물에 '서울'이 포함됨",
      "passed": true,
      "evidence": "3번째 단계에서 '서울 지역 데이터 추출' 확인"
    }
  ],
  "summary": {
    "passed": 2,
    "failed": 1,
    "total": 3,
    "pass_rate": 0.67
  }
}
```

**필드명 주의:** `text`, `passed`, `evidence`를 정확히 사용한다 (`name`/`met`/`details` 등 변형 금지).

### timing.json

실행 시간/토큰 측정:

```json
{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}
```

서브에이전트 완료 알림에서 `total_tokens`와 `duration_ms`를 즉시 저장한다. 이 데이터는 알림 시점에만 접근 가능하고 이후 복구 불가.

---

## 8. 스킬에 포함하지 않을 것

- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md 등 부가 문서
- 스킬 생성 과정의 메타 정보 (테스트 결과, 반복 이력)
- 사용자 대상 설명서 (스킬은 AI 에이전트를 위한 지시서)
- 이미 Claude가 알고 있는 일반적 지식

---

## 9. 스킬 재사용 설계

신규 스킬 생성 전, 기존 스킬과의 중복을 확인한다. 하네스를 반복 구축하다 보면 기능이 겹치는 스킬이 다른 이름으로 누적되기 쉽다.

| 상황 | 조치 |
|------|------|
| 기존 스킬이 신규 기능을 완전히 포함 | 신규 생성 금지 — 기존 스킬을 에이전트에 연결 |
| 기존 스킬이 부분 포함이고 일반화 가능 | 기존 스킬을 일반화하여 확장 |
| 도메인 특화가 의도된 부분 포함 | 신규 생성 진행 — 별개 스킬로 유지 |
| 기능 범위가 완전히 다름 | 신규 생성 진행 |

**원칙:** 하나의 스킬이 하나의 역할에 집중할수록 재사용성이 높고 중복이 줄어든다. 역할이 두 가지 이상이면 분리할 수 있는지 먼저 검토한다.

### 어디까지 일반화할지

일반화는 무한히 가능하므로 **의도된 책임 범위**에서 멈춘다. 의도된 도메인 특화는 유지하고, 우연한 종속만 제거한다.

예: "fintech 리스크 평가 PDF" 스킬

| 단계 | 결과 |
|------|------|
| fintech 종속 제거 | "평가 결과 PDF" — 책임 범위가 평가 리포트면 여기서 멈춤 |
| 평가 종속 제거 | "PDF 포매팅" — 이미 존재한다면 별개 스킬 생성하지 말고 재사용 |

책임 범위가 "fintech 리스크 평가"로 의도된 특화라면 일반화하지 않고 별개 스킬로 유지한다.

해당 스킬에 의존하는 에이전트의 동작이 변경될 수 있다. 확장 전 의존성을 확인하고, description에 확장된 사용 범위를 반영한다.