스킬 작성 가이드

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

1. Description 작성 패턴

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

트리거 메커니즘 이해

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

작성 원칙

스킬이 하는 일 + 구체적 트리거 상황을 모두 기술
유사하지만 트리거하면 안 되는 경우를 구분하는 경계 조건 명시
약간 "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에 확장된 사용 범위를 반영한다.

스킬 작성 가이드 ​

목차 ​

1. Description 작성 패턴 ​

트리거 메커니즘 이해 ​

작성 원칙 ​

좋은 예시 ​

나쁜 예시 ​

2. 본문 작성 스타일 ​

Why-First 원칙 ​

일반화 원칙 ​

명령형 어조 ​

컨텍스트 절약 ​

3. 출력 형식 정의 패턴 ​

4. 예시 작성 패턴 ​

5. Progressive Disclosure 패턴 ​

패턴 1: 도메인별 분리 ​

패턴 2: 조건부 상세 ​

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

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

7. 데이터 스키마 표준 ​

eval_metadata.json ​

grading.json ​

timing.json ​

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

9. 스킬 재사용 설계 ​

어디까지 일반화할지 ​

스킬 작성 가이드

목차

1. Description 작성 패턴

트리거 메커니즘 이해

작성 원칙

좋은 예시

나쁜 예시

2. 본문 작성 스타일

Why-First 원칙

일반화 원칙

명령형 어조

컨텍스트 절약

3. 출력 형식 정의 패턴

4. 예시 작성 패턴

5. Progressive Disclosure 패턴

패턴 1: 도메인별 분리

패턴 2: 조건부 상세

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

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

7. 데이터 스키마 표준

eval_metadata.json

grading.json

timing.json

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

9. 스킬 재사용 설계

어디까지 일반화할지