Prompt Engineering is Dead — Skill을 설계하고 테스트하고 배포하는 법 (2편)

개요

1편에서는 프롬프트 엔지니어링이 왜 한계에 부딪혔는지, 그리고 Anthropic이 제안하는 Skill이 기존 접근법과 어떻게 다른지 살펴봤습니다.

2026.03.07 - [claude code] - Prompt Engineering is Dead — Anthropic가 제안하는 AI 활용의 새로운 패러다임 (1편)

 

2편에서는 실전으로 들어갑니다. Anthropic의 "The Complete Guide to Building Skills for Claude" 가이드가 제시하는 Skill 설계 원칙, 구현 방법, 테스트 전략, 배포 방식을 구체적으로 다룹니다.

---

Skill 설계의 핵심 원칙

원칙 1: 컨텍스트는 유한한 자원이다

Skill 설계에서 가장 중요한 전제는, 컨텍스트 윈도우를 무한한 메모장이 아닌 유한한 자원으로 취급하는 것입니다. 이것이 점진적 공개(Progressive Disclosure) 패턴의 핵심입니다.

모든 지시사항을 시스템 프롬프트에 한꺼번에 넣는 것은, 모든 책을 펼쳐놓고 동시에 읽으라고 하는 것과 같습니다. Anthropic 가이드는 이 문제를 세 단계 로딩으로 해결합니다.

• 1단계 (항상 로드): YAML 프론트매터 — 이름, 설명, 트리거 조건만
• 2단계 (조건부 로드): 마크다운 본문 — 스킬이 활성화될 때만
• 3단계 (필요시 로드): 참조 파일, 스크립트 — 실제 실행에 필요할 때만

원칙 2: 트리거 설계가 절반이다

스킬이 아무리 잘 만들어져도, 적절한 시점에 활성화되지 않으면 무용지물입니다. Anthropic 가이드는 description 필드의 설계를 스킬 성공의 핵심으로 꼽습니다.

좋은 description의 구조는 다음과 같습니다.

---
name: code-review
description: >
  PR 코드 리뷰를 수행합니다.
  사용자가 "코드 리뷰해줘", "PR 검토해줘", "이 코드 봐줘"라고
  요청할 때 사용하세요.
  코드 품질, 보안 취약점, 성능 이슈를 체크합니다.
---

 

핵심 요소 세 가지를 포함해야 합니다.

• 무엇을 하는지: 스킬의 기능 한 줄 설명
• 언제 사용하는지: 사용자가 실제로 말할 법한 트리거 문구
• 주요 역량: 스킬이 커버하는 구체적 영역

description이 너무 일반적이면 무관한 요청에도 스킬이 활성화되고, 너무 좁으면 관련 요청을 놓칩니다. 가이드는 "사용자가 실제로 말할 문구(trigger phrases)"를 넣으라고 강조합니다.

원칙 3: 관심사의 분리

하나의 거대한 프롬프트에 모든 로직을 넣는 대신, Skill은 관심사를 분리합니다.

• YAML: 스킬이 어떻게 실행되는지 (권한, 메타데이터)
• 마크다운 본문: 무엇을 해야 하는지 (지시사항)
• 스크립트: 어떤 도구를 쓰는지 (실행 코드)
• 참조 파일: 어떤 지식이 필요한지 (도메인 정보)

각 구성요소를 독립적으로 버전 관리하고 업데이트할 수 있습니다. 프롬프트에서 한 줄을 고치면 전체 동작이 바뀔 수 있지만, Skill에서는 해당 레이어만 수정하면 됩니다.

SKILL.md 작성 실전 가이드

최소 구조

동작하는 가장 간단한 스킬은 이것입니다.

---
name: daily-standup
description: >
  일일 스탠드업 미팅 노트를 작성합니다.
  사용자가 "스탠드업", "데일리 노트", "오늘 할 일 정리"를
  요청할 때 사용하세요.
---

# Daily Standup Note Generator

## 수행 절차
1. 사용자에게 어제 완료한 작업을 질문
2. 오늘 계획한 작업을 질문
3. 블로커가 있는지 확인
4. 마크다운 형식으로 스탠드업 노트 생성

## 출력 형식
- **어제**: 완료 항목 bullet list
- **오늘**: 계획 항목 bullet list
- **블로커**: 있으면 기재, 없으면 "없음"

고급 설정 옵션

---
name: secure-deploy
description: >
  프로덕션 배포를 수행합니다.
  사용자가 "배포해줘", "프로덕션 릴리스", "deploy"를
  요청할 때 사용하세요.
disable-model-invocation: true
allowed-tools:
  - bash
  - str_replace_editor
metadata:
  category: devops
  complexity: advanced
  compatibility: Claude Code 1.0+
---

주요 옵션의 의미는 다음과 같습니다.

• disable-model-invocation: true — Claude가 자동으로 이 스킬을 호출하지 못하게 합니다. 배포처럼 사이드 이펙트가 있는 워크플로우에 적합합니다. 사용자가 명시적으로 호출해야만 실행됩니다.
• user-invocable: false — 반대로, 사용자가 직접 호출할 수 없고 Claude만 내부적으로 사용할 수 있습니다. 백그라운드 지식 스킬에 적합합니다.
• allowed-tools — 스킬이 사용할 수 있는 도구를 제한합니다.

파일 명명 규칙 (케이스 민감)

• 스킬 폴더: kebab-case 사용 (notion-project-setup)
• 파일 이름: 반드시 SKILL.md — 대소문자 정확히 일치
• 스킬 폴더 안에 README.md를 넣지 않기
• name 필드: 최대 64자, 소문자/숫자/하이픈만 허용
• description 필드: 최대 1,024자, 꺾쇠괄호(<, >) 사용 금지

---

테스트 전략 — 직감이 아닌 데이터로

Anthropic 가이드가 전통적 프롬프트 엔지니어링과 가장 크게 차별화되는 부분이 체계적인 테스트 방법론입니다.

3단계 테스트 프레임워크

1단계: 트리거 테스트

스킬이 올바른 시점에 활성화되는지 검증합니다.

• 명시적 요청에 트리거 되는지 ("코드 리뷰 해줘")
• 우회적 표현에도 트리거 되는지 ("이 PR 좀 봐줘")
• 무관한 요청에는 트리거 되지 않는지 ("날씨 알려줘")

2단계: 기능 테스트

스킬이 올바른 결과를 생성하는지 검증합니다.

• 출력 형식이 기대와 일치하는지
• API 호출이 성공하는지
• 에러 상황에서 적절히 처리하는지

3단계: 성능 비교 테스트

스킬 사용 전후를 비교합니다.

• 토큰 소비량 변화
• API 호출 횟수 변화
• 사용자 추가 입력 필요 횟수

베이스라인 설정의 중요성

가이드는 스킬 없이 Claude가 동일 작업을 수행하는 성능을 먼저 측정하라고 강조합니다. 이 베이스라인이 없으면 스킬의 가치를 입증할 수 없습니다.

흥미로운 점은, 가이드가 이런 시나리오도 언급한다는 것입니다: "기본 모델이 스킬 없이도 평가를 통과하기 시작하면, 해당 스킬의 기법이 모델의 기본 동작에 흡수되었다는 신호입니다." 즉, 스킬은 영구적이 아니라 모델 발전에 따라 진화해야 합니다.

실전 팁: 역방향 개발

가이드는 효과적인 스킬 개발 방식으로 역방향 접근법을 권장합니다.

1. 하나의 까다로운 작업을 골라서 Claude와 대화로 성공시킵니다
2. 성공한 패턴을 분석합니다
3. 그 패턴을 SKILL.md 형식으로 추출합니다
4. 다양한 변형으로 테스트합니다

"프롬프트를 처음부터 완벽하게 쓰려는" 전통적 접근법과 정반대입니다.

배포와 공유

개인 사용

Claude.ai에서는 설정 > 기능(Capabilities) > Skills에서 업로드합니다. Claude Code에서는 .claude/skills/ 디렉토리에 폴더를 넣으면 됩니다.

팀 배포

2025년 12월부터 조직 단위 스킬 배포가 가능해졌습니다.

• 관리자가 스킬을 조직 전체에 배포
• 자동 업데이트로 중앙 관리
• 팀원은 최신 버전을 항상 사용

이것은 프롬프트 공유의 한계를 근본적으로 해결합니다. 프롬프트를 Notion에 모아두고 "이걸 복사해서 쓰세요"라고 하는 것과, 스킬이 자동으로 적용되는 것은 완전히 다른 수준의 일관성을 제공합니다.

오픈 표준과 커뮤니티

Anthropic은 Agent Skills를 오픈 표준으로 공개했습니다. agentskills.io에서 스펙을 확인할 수 있으며, Claude뿐 아니라 이 표준을 채택하는 다른 AI 플랫폼에서도 동작하도록 설계되었습니다. 공식 저장소 anthropics/skills에는 템플릿과 프로덕션 예제가 있습니다.

흔한 문제와 해결법

Anthropic 가이드가 제시하는 트러블슈팅 패턴입니다.

스킬이 업로드되지 않을 때

• SKILL.md 파일명의 대소문자를 정확히 확인하세요
• YAML 구분자 ---가 파일 최상단에 있는지 확인하세요
• name에 "claude", "anthropic" 같은 예약어가 없는지 확인하세요

스킬이 트리거되지 않을 때

• description이 너무 일반적일 수 있습니다
• 사용자가 실제로 말할 법한 트리거 문구를 추가하세요
• "사용자가 ~을 요청할 때 사용하세요" 형식을 포함하세요

스킬이 너무 자주 트리거될 때

• 네거티브 트리거를 추가하세요 ("날씨 질문에는 사용하지 마세요")
• 스킬의 범위를 더 구체적으로 좁히세요

지시사항이 제대로 따라지지 않을 때

• 지시사항을 간결하게 유지하세요
• 핵심 단계에 우선순위를 부여하세요
• 검증 스크립트를 번들링하는 것을 고려하세요

---

Skill Building이 보여주는 미래

Anthropic의 가이드를 관통하는 메시지는 명확합니다: 확장 가능한 AI 시스템은 더 나은 프롬프팅이 아니라, 아키텍처적 해법을 요구합니다.

프롬프트 엔지니어링이 완전히 사라지지는 않을 것입니다. 탐색적이고 창의적인 작업, 프로토타이핑 단계에서는 여전히 유용합니다. 하지만 반복 가능하고, 팀 단위로 공유되고, 측정 가능한 AI 활용을 원한다면, 프롬프트가 아닌 Skill을 설계해야 합니다.

2026년의 AI 경쟁력은 완벽한 프롬프트를 쓸 수 있는 사람이 아니라, AI가 불완전한 입력에서도 안정적으로 동작하는 시스템을 구축할 수 있는 사람에게 돌아갈 것입니다.

---

참고 자료

• The Complete Guide to Building Skills for Claude — Anthropic 공식 블로그
• The Complete Guide to Building Skills for Claude — PDF
• Skill Authoring Best Practices — Claude Docs
• Extend Claude with Skills — Claude Code Docs
• SKILL.md Format Specification — DeepWiki
• Anthropic Skills Guide: Structured Execution Design — Glen Rhodes
• Claude Skills and Subagents — Towards Data Science
• How to Create Custom Skills — Claude Help Center
• anthropics/skills — GitHub 공식 저장소

이 글은 Claude Code를 활용하여 작성되었습니다.