Claude 블로그 되짚어보기 #64 — Skill 만들기, 운영 자산으로 다루는 매뉴얼 (2025)

원문 정보

• 제목: How to create Skills: Key steps, limitations, and examples
• 링크: claude.com/blog/how-to-create-skills-key-steps-limitations-and-examples
• 발행: 2025년 11월
• 카테고리: Claude Apps

글의 요지

Skill을 만드는 방법 종합 가이드. YAML frontmatter 작성, progressive disclosure 활용, 거버넌스, 테스팅, API 업로드까지. "Teach once, use forever" 의 운영 자산.

Skill 구조 핵심

my-skill/
├── SKILL.md          # 필수, 메인 지시
├── references/       # 선택, 추가 컨텍스트
│   └── api-docs.md
├── scripts/          # 선택, 실행 가능 코드
│   └── validate.py
└── examples/         # 선택, 참고 예시

YAML Frontmatter — 가장 중요

---
name: payflow-onboarding
description: PayFlow 신규 고객 온보딩 워크플로 처리. 
  계정 생성, 결제 셋업, 구독 관리. 
  사용자가 "신규 고객 온보딩", "구독 셋업", 또는 
  "PayFlow 계정 생성" 말할 때 사용.
---

핵심 원칙:

• name + description이 시스템 프롬프트에 항상 로드
• 본문은 트리거 시에만
• description이 트리거 메커니즘 — "무엇을, 언제" 명시

"Pushy Description"의 발견

skill-creator 공식 SKILL.md 인용:

"Claude has a tendency to 'undertrigger' skills—to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit 'pushy'."

좋지 않은 description:

"How to build a simple fast dashboard to display internal Anthropic data."

좋은 description (pushy):

"How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"

단계별 작성 흐름

1) 사용 사례 식별 (2-3개 구체)

• 추상이 아닌 "User says X → Steps Y → Result Z"

2) Use case 예시:

Use Case: Project Sprint Planning
Trigger: "help me plan this sprint"
Steps:
  1. Linear에서 프로젝트 상태 가져옴 (MCP)
  2. 팀 속도·캐파시티 분석
  3. 작업 우선순위 제안
  4. Linear에 작업 생성
Result: 완전 계획된 스프린트

3) frontmatter 작성: name + pushy description

4) 본문 작성: imperative form, 500줄 이하

5) Reference 파일 분리: 본문이 길어지면

6) 스크립트 추가: 결정론적 작업에

7) 테스팅:

• Normal operations: 표준 사용 케이스
• Edge cases: 누락 데이터, 비표준 입력

8) API 업로드:

curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F "display_title=My Skill Name" \
  -F "files[]=@my-skill/SKILL.md;filename=my-skill/SKILL.md"

한계 (Limitations)

본문이 명시한 제약:

1) Surface별 분리:

• Claude.ai 업로드 → API에 자동 X
• API 업로드 → Claude.ai에 자동 X
• Claude Code → 파일시스템 별도

2) 공유 모델:

• Claude.ai: 개인만 (각 팀원이 별도 업로드)
• API: 조직 전체 공유
• Claude Code: filesystem 기반

3) ZDR 미적용:

• Skill 정의·실행 데이터는 표준 보존 정책
• ZDR 필요 시 별도 검토

거버넌스 (조직 차원)

소규모 팀:

• 템플릿 형식 (이름, 설명, 지시, 버전)
• 공유 문서 저장소

중·대규모 팀:

• Skill owner 도메인별 (재무, 법무, 마케팅)
• 중앙 위키 또는 공유 드라이브 = Skill 라이브러리
• 사용 예시 + 트러블슈팅 포함
• 버전 관리 + 변경 로그
• 분기별 리뷰 (업데이트·은퇴)

Anthropic의 brand-guidelines Skill (실제 예시)

본문이 보여준 회사 브랜드 가이드라인 Skill:

---
name: brand-guidelines
description: Applies Anthropic's official brand colors 
  and typography to any sort of artifact...
---

# Anthropic Brand Styling

## Colors
- Dark: #141413 (primary text, dark backgrounds)
- Light: #faf9f5
- Orange: #d97757 (primary accent)

## Typography
- Headings: Poppins (with Arial fallback)
- Body: Lora (with Georgia fallback)

이게 실제 production Skill의 예시 — 단순하고 명확.

---

2026년에 다시 읽으며 — 내가 본 것

1. "Pushy Description"의 운영적 발견

이 글의 가장 흥미로운 디테일 — "undertrigger" 문제.

Anthropic의 자체 발견:

• Claude가 자기 능력 과소평가
• "이거 직접 할 수 있을 것 같은데" → Skill 안 씀
• 결과: Skill이 있어도 활용 안 됨

해결: "Pushy" description:

• "이걸 사용하라" 명시적
• 트리거 키워드 다양하게
• "심지어 명시적으로 X 말 안 해도" 추가

이게 AI 다루기의 운영적 통찰이다. "AI가 알아서 잘 하겠지" 가정 X. 명시적 지시 + 약간 강요 필요.

비유 — 신입 직원:

• 좋은 매니저: "이 도구 자유롭게 쓰세요" (방치)
• 더 좋은 매니저: "이런 작업엔 반드시 이 도구 쓰세요" (명시)

AI도 같다. "자유" 보다 "가이드" 가 작동.

2. "Use Case First"의 디자인 원칙

본문이 강조 — "Before writing any code, identify 2-3 concrete use cases".

이게 소프트웨어 디자인의 일반 원칙과 같다:

• API 디자인: 사용 케이스 먼저
• 제품 디자인: 사용자 시나리오 먼저
• Skill 디자인: 트리거 시나리오 먼저

이 원칙이 흔히 무시됨:

• "Skill 만들자" → 먼저 코드 작성 → 안 작동 → 이유 모름
• "먼저 케이스" → 명확한 트리거 → 잘 작동

이 원칙을 지키는 Skill = 작동하는 Skill.

3. "Imperative Form"의 작성 디테일

skill-creator SKILL.md 인용:

"Always use imperative/infinitive form."

Skill 본문 작성 스타일:

• Imperative (좋음): "Validate the data before proceeding"
• Descriptive (나쁨): "You should validate..."
• Conditional (나쁨): "It's recommended to validate..."

이유:

• LLM은 명령문 더 잘 따름
• Hedge 표현 ("should", "recommended") = 모호
• 직접 명령 = 명확한 행동

이게 프롬프트 엔지니어링의 디테일이다. "무엇을 해야 하는가" 가 "~를 권장합니다" 보다 강력.

4. "Surface별 분리"의 실용적 부담

본문이 명시한 한계 — Skill이 surface 간 자동 동기화 X.

이게 진짜 운영 부담이다:

개발자 시나리오:

• Claude.ai에서 Skill 만듦
• API에서도 같은 Skill 필요 → 재업로드
• Claude Code에서도 → filesystem에 복사

이게 "세 번 같은 Skill 관리" 부담:

• 변경 시 3군데 수정
• 버전 관리 어려움
• 일관성 깨질 위험

이 한계가 2026년 이후 진화할 가능성. Anthropic이 "통합 Skill 시스템" 으로 갈 듯. 그러나 현재는 운영 부담 의식적 선택.

이유 (추정):

• 각 surface가 다른 보안 모델
• 다른 사용자 권한
• 다른 호스팅 환경
• 통합 = 복잡도 폭발

5. "33페이지 가이드"의 서비스 깊이

본문 외에 Anthropic이 33페이지 공식 Skill Construction Guide PDF 제공.

이게 "단순 마케팅" 이 아니라 진지한 운영 도구:

• Medium 인용: "At first, everything feels magical. Then subtle issues begin to surface."
• Skill이 "매직" 에서 "실용" 으로 진화하는 데 필요한 깊이

가이드 다루는 영역:

• Architecture patterns
• Reference density
• Hierarchy beats verbosity
• Deterministic scripting
• Eval 디자인

이게 enterprise 도입의 깊이 시그널. "초보자용" 이 아니라 "production 운영자용".

6. "MCP + Skills의 협업 비유"

본문 인용:

"MCP provides the professional kitchen: access to tools, ingredients, and equipment. Skills provide the recipes: step-by-step instructions on how to create something valuable."

이 비유가 정확하다:

MCP (주방)	Skills (레시피)
도구·데이터 접근	절차·전문성
"무엇을 쓸 수 있나"	"어떻게 사용하나"
GitHub, Slack, Postgres	sprint-planning, code-review
인프라	콘텐츠

이 분리가 시스템 디자인의 일반 원칙과 같다 — "capability vs procedure".

같은 capability (주방)로 다른 procedure (레시피) 가능. 도구 추상화의 핵심.

7. "Quarterly Review"의 enterprise 디테일

거버넌스 권장 사항 중:

• "Schedule quarterly reviews to update or retire outdated skills"

이게 enterprise grade 디테일이다:

대부분의 Skill 사용자 (개인):

• 만들고 잊음
• 안 작동하면 삭제
• 가벼운 관리

Enterprise 사용자:

• 분기별 리뷰
• Skill owner 책임
• 변경 로그
• 버전 관리

이 차이가 AI 도구가 인프라가 됐을 때의 변화다. "실험" 이 아니라 "운영 자산". SaaS, DB, 모니터링 도구처럼 라이프사이클 관리.

이런 운영 깊이가 "AI가 진짜 enterprise 도구" 의 시그널이다.

---

마무리

이 글은 "Skill 만드는 법" 같지만, 실제로는 Skill을 운영 자산으로 다루는 매뉴얼이다.

• YAML frontmatter: 트리거 메커니즘
• Pushy description: undertrigger 방지
• Use case first: 디자인 원칙
• Imperative form: 명령문 우위
• Progressive disclosure: 토큰 효율
• Surface별 분리: 운영 부담 인정
• 33-page guide: enterprise 깊이
• MCP + Skills 협업: capability vs procedure
• Quarterly review: 운영 자산 라이프사이클

2025년 11월 시점은 "Skill = 흥미로운 실험" 에서 "Skill = 회사 운영 자산" 으로 진화 시기다. Anthropic이 그 진화를 가이드라인·거버넌스·운영 디테일로 지원.

흥미로운 건 "Pushy" 같은 진솔한 운영 통찰을 공유한다는 점이다. "우리 모델 완벽함" 마케팅 대신 "이런 한계 있으니 이렇게 다루세요" 가이드. 이 솔직함이 enterprise CIO에게 결정적이다.

이 글의 메시지가 분명하다 — AI 도구는 마법이 아니라 운영 자산. 잘 디자인하고, 테스트하고, 거버넌스 만들고, 정기 리뷰해야 작동. 이 운영 의식이 "AI가 회사 인프라로 진입" 의 진짜 의미다.