하네스 엔지니어링 9단계 베스트 프랙티스 #3. Skill 정의

시리즈 맥락 복기

#0~#2까지 우리는 자동화 지도, 프로젝트 규칙, Code Wiki라는 정적인 맥락을 준비했습니다. 이제부터는 에이전트가 실제로 실행할 동작 단위를 모듈화합니다. 이 단위를 Skill이라고 부릅니다.

1. #0 업무 프로세스 매핑
2. #1 프로젝트 규칙 설정
3. #2 Code Wiki 작성
4. #3 Skill 정의 ← 이번 편
5. #4 검증(Hook) 설계
6. ... (#8까지)

이 단계의 의미 — Skill이 하네스에서 차지하는 위치

Step 3은 "매번 손으로 하던 시퀀스를 한 번의 키워드로 호출할 수 있게 만드는" 단계입니다. 예컨대 "일정 동기화"라는 키워드만 던지면 내부적으로 "캘린더에서 읽기 → 파일 생성 → 정리 → 커밋 → 알림"이 순서대로 돌도록 하는 거죠. 이것이 바로 Skill의 역할입니다.

해결하려는 문제

• 같은 시퀀스를 매번 손으로 지시: "이 폴더 읽고, 그 다음 이 스크립트 돌리고..." — 매 대화마다 반복하면 실수가 생깁니다.
• 실행 순서 오류: AI가 단계를 건너뛰거나 뒤바꿔서 결과가 깨지는 경우.
• 환경변수 누락: API 키나 엔드포인트가 빠져서 디버깅에 시간 낭비.

효과 — 얼마나 체감되는가

개인 환경에서 Skill 20여 개를 정의해 두고 쓰는데, 가장 큰 효과는 신뢰성입니다. "일정 동기화해줘" 한 마디로 6단계가 일관되게 돌아가니까, 사람이 할 일은 결과 확인뿐입니다. 시간 절감도 있지만, 그보다는 "순서가 매번 같다"는 확실성이 핵심 가치입니다.

베스트 프랙티스 — SKILL.md 한 파일에 모두 담기

하나의 Skill은 하나의 SKILL.md 파일로 구성됩니다. 이 파일에 트리거·워크플로우·환경변수·GPU 의존성을 전부 적어두면, AI가 이 파일 하나만 보고 완전히 작업을 수행할 수 있습니다.

---
name: photo-enhance
description: 사진 자동 보정. "사진 보정", "보정 실행" 키워드에 반응.
version: 1.0.0
---

# 사진 자동 보정

## 워크플로우

### 1. 상태 확인 (`보정 상태`)
cd ~/photo-enhance && python3 enhance.py --status

### 2. 전체 보정 실행 (`보정 실행`)
cd ~/photo-enhance && python3 enhance.py --run --resume --batch-size 100
- 체크포인트 기반 배치 처리, GPU 스케줄러 연동

## 환경 변수
- IMMICH_API_KEY — 필수
- IMMICH_URL — 기본: http://localhost:2283

## GPU 스케줄러
- jobs.conf: photo-enhance|85|background

작성 시 반드시 지켜야 할 4원칙

1. description에 트리거 키워드를 전부 나열

AI가 사용자 메시지를 이 Skill과 매칭하는 유일한 단서가 description입니다. "사진 보정"이라고만 적어두면 "보정 실행"이라는 입력에는 반응하지 않을 수 있습니다. 변형 키워드를 전부 열거하세요.

2. 워크플로우는 번호 붙인 단계로

"1. 상태 확인", "2. 전체 보정 실행"처럼 번호를 붙이면 AI가 순서를 지킵니다. 불릿만 찍어두면 병렬 해석하기 쉽습니다.

3. 환경변수와 외부 의존성 명시

필수/선택을 구분해 적고, 기본값이 있다면 함께 기재합니다. 누락 시 어떻게 실패하는지도 적어두면 디버깅이 빠릅니다.

4. GPU 의존성은 스케줄러 규칙과 연결

GPU를 쓰는 Skill이라면 jobs.conf에 어떤 우선순위/타입으로 등록되어 있는지 명시합니다. 그래야 에이전트가 자원 선점 문제를 스스로 이해합니다.

Skill 카탈로그 설계 — 무엇을 Skill로 만들 것인가

모든 작업을 Skill로 만들 필요는 없습니다. 다음 조건을 만족하는 것만 골라내세요.

기준	Skill로 만들기 좋은 경우	Skill로 만들 필요 없는 경우
빈도	주 2회 이상 반복	1회성 작업
순서	3단계 이상의 순차 실행	한 명령으로 끝
외부 의존	API 키·URL·경로가 필요	순수 쿼리
실수 위험	순서/파라미터 실수 위험 있음	실수해도 영향 적음

자주 빠지는 실수

• description이 너무 추상적: "사진 관리"만 적어두면 사용자의 구체적인 입력과 매칭되지 않습니다. "사진 보정", "보정 실행", "photo enhance" 식으로 구체적인 키워드를 나열해야 합니다.
• 워크플로우에 동작만 적고 목적 생략: "enhance.py --run 실행"만으로는 AI가 실패 시 대응을 못 합니다. "체크포인트 기반 배치 처리"처럼 의미를 덧붙이세요.
• 여러 Skill이 같은 상태 파일 공유: 상태 파일을 쓰는 Skill이 여럿이면 충돌 가능성이 생깁니다. 각 Skill이 자신만의 네임스페이스를 쓰도록 설계합니다.

다음 단계 예고 — Step 4 검증(Hook)

Skill은 에이전트가 무엇을 할지를 정의합니다. 하지만 그걸 잘못 실행하는 것을 막을 장치는 따로 필요하죠. 다음 편에서는 Dispatcher 패턴 기반의 Hook 설계, 그리고 파이프라인 상태 추적을 다룹니다.

한 줄 요약: "반복되는 시퀀스는 손이 아니라 SKILL.md로 기억시켜야 한다."

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.