Skill description 설계 완전 가이드

트리거 정확도를 높이는 3원칙

description의 역할

description은 Claude가 사용자의 지시를 받았을 때, "이 Skill을 사용해야 하는가"를 판단하기 위한 정보입니다. Claude는 사용자의 입력과 description의 내용을 대조하여, 매칭되면 해당 Skill을 자동으로 실행합니다.

즉, description은 Claude에 대한 "트리거 조건의 설명"이며, 사람이 읽는 문서가 아니라 Claude가 읽는 판정 기준입니다.

� 한국 개발 환경의 경우
GitHub PR 기반의 코드 리뷰, Jira/Linear 이슈 연동, GitHub Actions CI/CD가 일반화된 현재, Claude Code Skill의 description을 정밀하게 작성하면 반복적인 리뷰·테스트·문서화 작업을 자동화할 수 있습니다.

좋은 descriptiopn의 3원칙

1. "언제 사용하는가"를 명기한다

Skill의 기능 설명이 아니라, "사용자가 어떤 요청을 했을 때" 이 Skill을 사용해야 하는지를 명확히 기술합니다.

# ❌ 오류: 기능 설명에 그치고 있다
description: "PR을 리뷰하여 리뷰 코멘트를 생성하는 Skill"

# ✅ 정상: 발화 조건이 명확하다
description: "PR의 리뷰나 코드 리뷰를 요청받았을 때, 변경 내용을 분석하여 리뷰 코멘트를 생성한다"

2. 다른 Skill과의 구별을 명확히 한다

여러 Skill이 존재하는 경우, description이 모호하면 Claude가 어떤 Skill을 사용해야 할지 판단을 못합니다.

# ❌ 오류: 모호하여 다른 Skill과 구별이 불가
description: "코드에 관한 작업을 할 때"

# ✅ 정상: 구체적이고 구별 가능
description: "PR의 리뷰나 코드 리뷰를 요청받았을 때"

3. 부정 조건(사용하지 않을 상황)도 명시한다

특정 상황에서 발화시키고 싶지 않은 경우, 부정 조건을 명시하면 정확도가 크게 향상됩니다.

description: "테스트 코드의 신규 작성을 요청받았을 때. 단, 기존 테스트의 수정이나 테스트 실행 요청에는 사용하지 않는다"

과잉 트리거·미작동 트리거·오작동 트리거 비교

따라하기

1단계: 현재 description으로 트리거 테스트

우선, 2장에서 설정한 description의 트리거 정확도를 확인합니다. 프로젝트 디렉토리에서 Claude Code를 시작합니다.

cd ~/dev-workflow-skills
claude

아래 프롬프트를 순서대로 시험해보고, 어떤 Skill이 트러거하는지(또는 트리거하지 않는지)를 기록합니다.

테스트 프롬프트 목록:

1. "이 PR 리뷰해줘"

2. "코드 리뷰 부탁드립니다"

3. "src/main.ts 테스트 코드 작성해줘"

4. "이 모듈 문서 만들어줘"

5. "코드 품질 개선해줘" ← 어떤 Skill도 발화하지 않아야 한다

6. "README 업데이트해줘" ← doc-gen이 발화해야 한다

7. "버그 수정해줘" ← 어떤 Skill도 발화하지 않아야 한다

8. "테스트 실행해줘" ← test-gen이 발화하지 않아야 한다

결과를 아래 표와 같이 만들어 기록해 봅시다.

동작 확인을 위한 샘플 파일을 아래와 같이 생성합니다.

src/main.ts

---

// 간단한 계산 유틸리티

export function add(a: number, b: number): number {

return a + b;

}