[AI] Skill 잘 쓰는법

1. Skill이란?

• 반복적으로 설명해야 하는 절차·규칙·컨텍스트를 한 번 문서화해서 재사용하는 것이 핵심. 매번 프롬프트에 장황하게 다시 설명할 필요 없음.

 

❌ Bad

매 대화마다 사용자가 직접 반복 입력:

"우리 커밋 메시지는 티켓 번호 접두사 붙이고, 제목은 72자 이내, 본문은 한글로, 브랜치명은 정해진 형식으로 써야 해..."

 

✅ Good

SKILL.md 파일 하나로 규칙 고정:

---
name: commit-writer
description: 커밋 메시지 작성 시 사용. 티켓 번호 접두사 + 컨벤션 자동 적용
---

1. 변경된 파일 확인
2. 브랜치명에서 티켓 번호 추출
3. <티켓번호> [플랫폼] <72자 이내 제목> 형식으로 작성

한 번 만들어두면 이후 대화에서는 "커밋해줘"만 입력해도 규칙이 자동 적용됨.

2. 짧고 명확하게, 한 가지 목적만

하나의 Skill = 하나의 명확한 작업/도메인. 여러 목적을 억지로 합치면 모델이 어떤 상황에 써야 할지 혼란을 겪음.

❌ Bad

• name: dev-helper
• description: 개발 관련 작업 전반을 도와줌
• (내용: 커밋 작성 + 코드 리뷰 + 빌드 에러 수정 + PR 생성 + 배포 체크리스트 전부 포함)

✅ Good

• name: commit-writer → 커밋 메시지 작성만
• name: build-fixer → 빌드 에러 수정만
• name: pr-description-writer → PR 본문 작성만

하나로 뭉쳐두면 "빌드 에러 고쳐줘"라는 요청에도 모델이 커밋 규칙까지 불필요하게 끌고 와 혼란 가중. 목적별로 쪼개어 필요한 Skill만 정확히 매칭.

3. 필요할 때만 로드되게(지연 로딩) 설계

Skill 본문 전체를 항상 컨텍스트에 넣는 것이 아니라, 이름과 설명(description)만 먼저 노출하고 실제로 필요할 때 본문을 불러오는 구조. 검색과 매칭의 유일한 단서인 description 작성이 매우 중요.

❌ Bad

• description: "개발 관련 작업을 도와줍니다"
• 이 한 줄만으로는 모델이 현재 요청에 적합한지 판단 불가. 결국 호출되지 않거나 엉뚱한 상황에서 잘못 실행됨.

✅ Good

• description: "화면을 present/dismiss하는 화면 전환 코드를 작성하거나 '뒤로가기를 눌렀는데 화면이 두 개 이상 닫힌다' 같은 네비게이션 버그를 진단·수정할 때 사용."
• 다루는 상황이 구체적이어서 모듈을 모르는 개발자의 요청이라도 상황만 맞으면 정확히 매칭되고, 유사하지만 무관한 요청과는 명확히 구분됨.

4. 실행 가능한 지침 위주로 작성

모호한 배경 설명보다는 "이 상황에서 이렇게 해라"는 절차적 지시, 체크리스트, 예시 명령을 우선 배치. 모델이 즉시 따라 할 수 있는 형태가 필수.

❌ Bad

"커밋 메시지는 프로젝트마다 컨벤션이 다르고, 리뷰어들이 히스토리를 읽기 편하도록 신경 써서 작성하는 것이 매우 중요합니다. 좋은 커밋 메시지는 협업에 도움이 되며..."

(배경 설명만 길고 실제 수행할 절차가 없음)

✅ Good

1. 변경 파일 확인
2. 변경 내용 확인
3. 브랜치명에서 티켓 번호 추출
4. 아래 형식으로 커밋: <티켓번호> [플랫폼] <요약>
5. 커밋 실행
6. (순서대로 따라가며 바로 실행 가능한 형태)

5. 구체적인 예시(example) 포함

추상적인 규칙보다 구체적인 입력/출력 예시가 모델의 정확도를 크게 향상시킴.

❌ Bad

"적절한 형식으로 커밋 메시지를 작성하세요."

✅ Good

• 예시 입력: 화면 전환 시 뒤로가기 누르면 두 화면이 같이 닫히는 버그 수정
• 예시 출력: TICKET-1234 [iOS] 뒤로가기 시 이전 화면까지 같이 닫히는 문제 수정
• 대상을 지정하지 않고 dismiss를 호출하면 의도한 화면이 아니라 그 화면을 띄운 상위 화면이 닫히는 문제를 수정.

실제 입력과 출력 사례를 제공하여 형식, 톤, 수준을 그대로 재현하도록 유도.

6. 스크립트·도구를 함께 묶기

Skill 폴더에 실제로 실행할 수 있는 스크립트나 템플릿 파일을 함께 배치하면, 모델이 설명만 읽고 추측하는 대신 검증된 코드를 그대로 실행 가능.

❌ Bad

• SKILL.md 내부 서술: "빌드 산출물은 체크섬으로 검증한 뒤 사용하세요."
• (모델이 매번 체크섬 검증 명령을 즉석에서 재구성하므로 실수 유발 가능성 높음)

✅ Good

skills/verify-artifact/
├── SKILL.md    ("아래 스크립트를 실행해 검증하라")
└── verify.sh   (검증 절차를 고정해 둔 스크립트)

모델은 준비된 스크립트를 그대로 실행하기만 하면 되므로 매번 동일한 결과 재현 가능.

7. 팀/리포지토리 단위로 버전 관리

Skill 파일 자체를 코드처럼 리포지토리에 커밋하여 팀원 모두가 동일한 지침을 공유하고, PR(Pull Request)을 통해 개선.

❌ Bad

• 각자 로컬 개인 환경에만 개별적으로 Skill을 생성하여 사용.
• 팀원 A는 규칙이 있고 팀원 B는 없어 결과물이 제각각이 됨.

✅ Good

• 프로젝트 저장소에 Skill 파일을 커밋.
• git log에 이력이 남고 PR을 통한 리뷰 및 개선이 가능하며 팀 전체가 동일한 버전을 공유.

8. 너무 많은 Skill을 한꺼번에 로드하지 않기

Skill 개수가 지나치게 많아지면 매칭 정확도가 떨어지고 토큰 비용이 증가. 범위를 좁게 나누고 이름과 설명을 서로 겹치지 않게 관리.

❌ Bad

• name: helper-1, description: "개발 관련 작업"
• name: helper-2, description: "개발 관련 작업 지원"
• name: tool, description: "작업을 도와줍니다"
• (설명이 서로 비슷해 모델이 혼란을 겪고 후보가 늘어날수록 매칭 정확도 하락 및 로드 비용 증가)

✅ Good

• name: commit-writer, description: "커밋 메시지 작성 시"
• name: build-fixer, description: "빌드 에러 수정 시"
• name: migration-helper, description: "특정 마이그레이션 빌드/이슈 해결 시"
• (이름과 설명이 명확히 구분되어 각 요청에 정확히 하나의 Skill만 매칭됨)