2026년 Claude Code Skills: 나만의 skills 라이브러리 만드는 방법

Ailoot 문서: API, 키, 설정.

Claude Code의 skill이란 무엇이며, 왜 단순히 “더 큰 프롬프트”가 아닐까요?#

Claude Code Skills는 Anthropic이 2025년 10월 Pro/Max/Team/Enterprise용으로 출시한 Claude Code의 기본 기능입니다. 이후 Anthropic은 Claude 외부에서도 사용할 수 있는 표준으로 Agent Skills 사양을 공개했습니다. 코드에서 skill은 그저 폴더 하나입니다.

.claude/skills/
├── deploy-to-prod/
│   ├── SKILL.md
│   └── scripts/
│       └── check-migrations.sh
├── weekly-content-plan/
│   └── SKILL.md
└── triage-support-tickets/
    └── SKILL.md

폴더 하나가 skill 하나입니다. SKILL.md 파일은 맨 위에 YAML frontmatter가 있고 그 아래에 일반 지침이 있는 Markdown 파일입니다. 사용자가 “프로덕션에 배포하자”라고 하면 Claude는 deploy-to-prod skill의 description을 확인하고 “프로덕션에 배포” 트리거를 인식해 SKILL.md 본문을 컨텍스트에 불러온 다음 단계를 따릅니다.

점진적 로딩의 세 단계

Anthropic은 필요에 따라 데이터가 계층별로 로드되는 점진적 로딩 방식을 skills에 적용했습니다. Anthropic Engineering 블로그에서 팀은 이를 “Agent Skills를 유연하고 확장 가능하게 만드는 핵심 설계 원칙”이라고 설명합니다 (Anthropic Engineering).

로딩 단계는 세 가지입니다.

1. 메타데이터(항상) - 세션이 시작되면 Claude는 각 skill의 name과 description만 확인합니다. 예산: skill당 약 100토큰.
2. 지침(트리거 발생 시) - 사용자가 관련 내용을 말하면 Claude가 SKILL.md 본문을 컨텍스트에 불러옵니다. 예산: 5000토큰 미만.
3. 리소스(요청 시) - 함께 제공된 파일(예시, 템플릿, 데이터세트)은 모델이 직접 찾아볼 때만 가져옵니다. 예산: 무제한.

이전에는 AI가 “기억해야” 할 모든 내용을 CLAUDE.md에 넣어야 했고, 규칙이 50개인 프로젝트는 컨텍스트 한도에 금세 도달했습니다. Skills를 사용하면 초기 컨텍스트에는 각 skill의 description만 들어가므로 프로젝트 하나에 수십 개를 쉽게 함께 둘 수 있습니다.

Skills가 있는 위치: 네 가지 수준

우선순위는 enterprise가 개인 설정을 덮어쓰고, 개인 설정이 프로젝트 설정을 덮어씁니다. 플러그인은 plugin-name:skill-name 네임스페이스를 사용하므로 충돌하지 않습니다. 일반적인 전문 skill은 ~/.claude/skills/에, 프로젝트 전용 skill은 저장소의 .claude/skills/에 두면 편리합니다.

SKILL.md에는 무엇이 들어 있나요?#

최소 예시는 다음과 같습니다. 스무 줄이면 skill을 쓸 준비가 됩니다.

---
name: weekly-content-plan
description: Prepares a weekly post plan for a Telegram channel and short-form videos. Triggers - "make a post plan", "what should I post this week", "a 7-day channel plan". Do not activate if the request is about a website or email newsletter.
---

# Weekly Content Plan

## Steps

1. Read `knowledge/audience.md` - who we're writing for
2. Read `knowledge/tone-of-voice.md` - how we write
3. Read the last 10 posts in the channel - what has already been covered
4. Come up with 7 topics for the week: 3 sales-focused, 2 expert, 2 personal
5. For each, provide one hook line and three bullets about the post
6. Output as a table: day of the week | type | hook | plan

이 정도면 충분합니다. 사용자가 “이번 주 게시물을 계획하자”라고 쓰면 Claude는 description에서 트리거를 찾고 SKILL.md를 불러와 지정된 파일을 읽은 뒤 표를 출력합니다.

알아둘 제한 사항

Claude API 공식 문서는 다음과 같은 엄격한 제한을 둡니다.

• name: 최대 64자이며 소문자, 숫자, 하이픈만 사용할 수 있고 XML 태그는 허용되지 않습니다. anthropic과 claude는 예약어입니다.
• description: API에서 최대 1024자이며 필수입니다. XML 태그는 허용되지 않습니다.
• 목록 예산: Claude Code에서는 모든 skill의 description을 합쳐 컨텍스트 창의 약 1%를 사용합니다. Skills가 많으면 description이 잘려 Claude가 매칭에 필요한 키워드가 사라질 수 있습니다.
• SKILL.md 본문: Anthropic은 본문을 500줄 이내로 유지하도록 권장합니다. 더 긴 내용은 references/, scripts/, examples/ 파일로 옮기고 지침에서 해당 파일을 불러오도록 합니다.

컨텍스트 압축(/compact) 후 Claude는 이전에 호출한 각 skill의 첫 5000토큰을 유지합니다. 다시 연결되는 모든 skill의 총예산은 25 000토큰입니다. skill이 들어갈 자리가 없으면 해당 동작은 “잊힙니다.”

전체 Frontmatter 스키마

최소한 name과 description을 사용합니다. 프로덕션용 skills에는 다른 필드도 들어갑니다.

disable-model-invocation: true 필드는 자동으로 실행되면 안 되는 모든 항목에 반드시 필요합니다. 예를 들어 이 플래그가 설정된 deploy-to-prod skill은 사용자가 /deploy-to-prod를 직접 입력한 경우에만 호출할 수 있습니다. 이 플래그가 없으면 “코드가 준비된 것 같아서” Claude가 배포할 수도 있습니다.

Description이 작업의 90%를 차지하는 이유와 작성 방법#

바이브 코딩에서 가장 흔한 실수는 “Helper for X”처럼 description을 쓰는 것입니다. 폴더에 skill 파일이 실제로 있어도 Claude는 호출하지 않습니다.

좋지 않은 Description

description: Build dashboards.

Claude는 다음을 구분할 수 없습니다. 사용자가 “이번 주 매출을 보여줘”라고 하면 대시보드에 관한 요청일까요? “매출 차트”라고 하면 대시보드일까요, 아니면 일반적인 차트일까요? “월간 보고서”는 대시보드와 무관한 게 확실할까요?

Anthropic의 skill-creator는 권고 사항을 직접 명시합니다.

좋은 Description을 위한 공식

세 부분입니다.

1. 무엇을 하는가 - 과정이 아니라 결과를 설명하는 한 문장입니다. “SQL을 생성한다”가 아니라 “Telegram 채널용 표로 매출을 내보낸다”처럼 씁니다.
2. 언제 트리거할 것인가 - 사용자가 실제로 말하는 문구 3-5개를 따옴표로 묶습니다. 추측하지 말고 채팅과 지원 기록을 살펴보세요.
3. 언제 트리거하면 안 되는가 - skill이 응답하지 않아야 하는 비슷한 작업에 관한 문구 1-2개를 넣습니다. 이 부분이 없으면 비슷한 두 skills가 계속 충돌합니다.

내 프로젝트에서 가져온 효과적인 description 예시입니다(단순화 및 익명화).

description: |
  편집 정책에 따라 블로그용 SEO 가이드를 작성하고 게시합니다.
  트리거: "X에 관한 가이드를 써 줘", "새 필라를 만들자",
  "Y에 관한 블로그 글", "Z에 관한 블로그 가이드를 만들어 줘".
  요청이 이메일 뉴스레터,
  Telegram 게시물 또는 팀 내부 지침에 관한 내용이면 활성화하지 마세요.
  그런 작업에는 다른 skills를 사용합니다.

여기서 효과적인 점은 다음과 같습니다.

• “도와준다” 대신 “작성하고 게시한다”라는 동사를 사용해 구체적인 결과를 명시합니다.
• 서로 다른 표현을 아우르는 트리거 문구 네 개를 따옴표로 묶었습니다.
• 영어 트리거도 포함했습니다. 사용자가 팀의 언어로 전환해도 skill이 작동합니다.
• 별도의 “활성화하지 않는 경우” 섹션을 두어 이메일 및 게시물 관련 skills와의 충돌을 막습니다.

Description 테스트 방법

Anthropic은 skill-creator에 trigger-evals 방법론을 넣었습니다. skill이 활성화되는지 확인하는 프롬프트 20개를 사용합니다. 10개는 활성화되어야 하고 10개는 활성화되지 않아야 합니다. 비슷한 표현을 사용하지만 실제 작업은 다른 거의 일치하는 사례도 포함합니다.

바이브 코딩 방식으로 설명하면 이렇습니다. description을 쓴 뒤 빈 채팅을 열고 실제로 자주 쓰는 문구 5개와 비슷하지만 의미는 다른 문구 3개를 입력해 봅니다. 활성화되어야 할 때 활성화되지 않거나, 활성화되면 안 될 때 활성화되면 description을 수정합니다. 지침 본문은 그다음에 작성합니다.

먼저 설치할 Skills 5개는 무엇일까요?#

처음 2주를 직접 skills를 작성하는 데 쓰는 건 좋은 전략이 아닙니다. 먼저 이미 만들어진 skills를 설치하고 구성을 살펴본 다음 같은 방식으로 직접 추가하세요. 모든 것을 처음부터 만드는 것보다 검증된 컬렉션을 가져와 자신의 필요에 맞게 수정하는 편이 비용이 적게 듭니다. 먼저 시작할 만한 컬렉션 다섯 가지를 소개합니다.

1. anthropics/skills - skill-creator가 포함된 공식 컬렉션

저장소: github.com/anthropics/skills. GitHub stars 138,000개. Anthropic 팀의 공식 skills가 들어 있습니다. 다른 skills를 작성하는 메타 skill인 skill-creator, API 통합을 돕는 claude-api, PowerPoint, Excel, Word, PDF용 문서 skill을 제공합니다.

Claude Code에서 설치하기:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

가장 큰 가치는 skill-creator입니다. description을 바탕으로 SKILL.md를 작성한 뒤 trigger-evals 20개를 실행하고, skill이 적절한 상황에서 활성화될 때까지 description을 수정합니다. 말하자면 “skills를 만드는 skill”입니다.

2. mattpocock/skills - TypeScript 전문가의 바이럴 컬렉션

활성 skills 12개가 들어 있으며, 그중 일부는 다음과 같습니다.

• tdd - red-green-refactor를 적용합니다. 먼저 실패하는 테스트를 작성하고, 최소한으로 수정한 다음 리팩터링합니다.
• to-issues - 계획을 수직으로 나눈 GitHub 이슈로 변환합니다(전체 스택을 포함하며 독립적으로 배포 가능).

설치:

npx skills@latest add mattpocock/skills
/setup-matt-pocock-skills

3. coreyhaines31/marketingskills - 마케터를 위한 컬렉션

온라인 프로그램을 운영하거나 프리랜서 마케터로 일하거나 에이전시를 운영한다면, 직접 skills를 쓰는 데 6개월을 쓸 필요가 없습니다. 작업의 절반은 이미 패키지로 제공됩니다.

4. vercel-labs/agent-skills - AI처럼 보이지 않는 디자인

저장소: github.com/vercel-labs/agent-skills. web-design-guidelines는 접근성, 성능, 사용성 규칙 100개 이상을 기준으로 UI 코드를 감사합니다.

여기에 주간 설치 횟수가 110,000회를 넘는 Anthropic frontend-design도 있습니다. 이 skill은 코드를 쓰기 전에 AI가 스타일을 선택하도록 합니다. 이 skill이 없으면 Claude가 생성하는 모든 페이지에 Inter 글꼴, 보라색 그라디언트, 그리드 카드가 들어갑니다. 결과가 누구에게나 똑같아집니다.

5. obra/superpowers - 멀티 에이전트 워크플로

전체적으로 이 목록의 앞 세 컬렉션인 anthropics/skills, mattpocock/skills, coreyhaines31/marketingskills를 설치하면 첫 달부터 기업가가 하는 대부분의 작업을 처리할 수 있는 바로 쓰는 skills 수십 개를 Claude Code에서 사용할 수 있습니다.

어떤 반복 작업을 skill로 만들어야 할까요?#

고객 업무와 다른 사람들의 프로젝트에서 이런 패턴을 수십 번 봤습니다. 누군가에게는 “매번 처음부터 하는 그 일”이 있습니다. 매주 월요일마다 비슷한 보고서를 씁니다. 새 고객이 들어올 때마다 같은 절차를 밟습니다. 게시물마다 같은 템플릿을 따릅니다. 매번 단계를 떠올리고, 올바른 파일을 열고, Claude 프롬프트를 다시 작성해야 해서 30-90분이 걸립니다.

해결책은 그 절차를 한 번 skill로 묶는 것입니다. 그다음에는 한 문장만 말하면 Claude가 방법론을 불러오고 필요한 자료를 읽어 결과를 만듭니다. 서로 다른 분야의 예시 세 가지를 살펴보겠습니다.

예시 1. 프리랜서 마케터 - weekly-content-plan skill

직접 하는 일: 매주 월요일 세 고객의 Telegram 게시물을 일주일치 준비합니다. 고객의 브랜드 보이스 가이드를 열고, 최근 게시물을 검토하고, 제품 일정에 따라 주제를 생각한 다음, 훅과 글머리표가 있는 표를 작성합니다.

이를 skill로 만들면 다섯 단계 지침이 됩니다. 고객의 톤앤보이스 파일을 읽고, 제품 일정을 읽고, 반복을 피하기 위해 최근 게시물 10개를 확인하고, 판매 중심·전문가·개인 주제로 나눠 일곱 가지 주제를 생각하고, 표로 출력합니다.

“고객 X의 이번 주 게시물을 계획하자”라는 명령으로 한 시간 준비 작업이 3분의 대기 시간으로 줄어듭니다. 마케터는 결과를 확인하고 필요한 부분만 수정해 고객에게 보냅니다.

예시 2. 외주 회계사 - monthly-receipts-close skill (저자 사례)

직접 하는 일: 매달 포트폴리오에 있는 각 고객의 은행 거래 내역을 내보내고, 회계 시스템의 결제 내역과 대조하고, 분류되지 않은 결제를 표시하고, 잠정 수입 보고서를 작성한 뒤, 수입 구성을 이전 달과 비교합니다.

이 skill은 여섯 단계 지침과 은행 거래 내역을 분석하는 scripts/ 폴더의 셸 스크립트 몇 개로 구성됩니다. “고객 X의 5월 마감을 해 줘”라는 트리거를 입력하면 Claude는 4-5분 안에 이상 항목을 표시한 보고서를 만듭니다.

예시 3. 온라인 프로그램 운영자 - welcome-letter-new-participant skill

직접 하는 일: 새 참가자가 결제하면 환영 이메일을 써야 합니다. 좋은 환영 이메일은 개인화되어야 합니다. 참가자가 어디서 왔는지, 어떤 제품을 구매했는지, 어떤 기수에 속하는지, 어떤 자료를 보내야 하는지 고려해야 합니다. “안녕하세요, 반갑습니다”라는 템플릿으로는 부족합니다.

이 skill은 Claude에게 knowledge/audience.md(이 사람들이 누구인지), knowledge/products/<product>.md(무엇을 받는지), 최근 환영 이메일 세 개(반복 방지)를 읽은 뒤 다음 구조로 이메일을 쓰도록 지시합니다. 도입부 - 제품별 상세 내용 - 처음 세 단계 - 맺음말.

직접 하는 것보다 훨씬 빠릅니다. 사람이 급할 때는 자료 하나를 건너뛰곤 하지만 Claude는 세 자료를 확인하므로 품질도 더 일관적입니다.

Skill로 만들면 안 되는 작업

• 일회성 작업. 세금 신고를 위해 1년에 한 번 하는 일이라면 채팅에서 Claude에게 설명하면 됩니다. skill은 3회 이상 반복한 뒤에야 효과가 있습니다.
• 너무 일반적인 작업. “마케팅 도와줘”는 skill이 아니라 마케팅 전체를 뜻합니다. skill은 “주간 콘텐츠 계획”처럼 구체적인 결과를 내는 구체적인 작업입니다.
• 반복 가능한 단계가 없는 작업. 절차가 매번 달라진다면 skill이 아니라 일회성 작업입니다.

Skill Creator는 어떻게 skills를 작성해 주나요?#

문제는 처음부터 좋은 skill을 작성하기 어렵다는 점입니다. description이 너무 좁거나 넓게 만들어지고, 사용자가 실제로 쓰는 표현을 놓치거나 인접한 skill과 충돌하는 경우가 많습니다. Anthropic은 다른 skills를 만들 수 있는 메타 skill인 skill-creator를 공개해 이 문제를 해결했습니다.

anthropics/skills를 설치한 다음 Claude에게 /skill-creator라고 입력하거나 “주간 보고서를 위한 skill을 만들자”라고 말하고, 다음 여섯 단계의 워크플로를 따릅니다.

1. 초안 - skill-creator가 skill의 기능, 사용할 트리거 문구, 읽을 자료, 따를 단계를 질문합니다. 결과는 SKILL.md의 첫 버전입니다.
2. 테스트 - skill-creator가 테스트 프롬프트 20개를 생성합니다. 10개는 skill을 활성화해야 하고, 10개는 트리거처럼 들리지만 활성화하면 안 되는 근접 사례입니다.
3. 평가 - 각 프롬프트를 새 채팅에서 실행해 skill이 활성화됐는지 확인합니다. 활성화되면 안 되는 상황에서 활성화되거나, 활성화되어야 하는데 활성화되지 않으면 결과에 표시합니다.
4. 반복 개선 - 실패 결과를 바탕으로 description을 다시 쓰고 테스트를 반복합니다.
5. 최적화 - 마지막으로 다듬습니다. 1024자 제한을 넘지 않는지, 프로젝트에 있는 skills와 충돌하지 않는지 확인합니다.
6. 패키징 - 최종 SKILL.md와 참조 파일을 올바른 구조로 묶습니다.

실제로는 Claude와 15-20분 동안 대화하며 확인 질문 7-8개에 답하고, 마지막에 적절한 트리거로 활성화되는 테스트 완료 skill을 받게 됩니다.

또 다른 장점은 skill-creator가 SKILL.md를 작성하는 모범적인 스타일을 보여준다는 점입니다. 자체 파일을 열어 형식, 어조, 단계 구성을 살펴볼 수 있습니다. 도구가 스스로를 보여주는 사례입니다. 파일을 읽으며 자신만의 skill 작성법을 배울 수 있습니다.

Skills, CLAUDE.md, Subagents, MCP, Hooks: 무엇을 사용해야 할까요?#

제가 검토한 프로젝트에서 가장 흔한 문제는 CLAUDE.md에 프로젝트 규칙, 단계별 게시 지침, 커밋 템플릿, 데이터베이스 설명을 한꺼번에 넣는 것입니다. 컨텍스트가 과부하될 뿐 아니라 실제로도 제대로 작동하지 않습니다. 모델은 CLAUDE.md 전체를 명시적인 트리거가 없는 일반 컨텍스트로 취급하기 때문에 사용자가 게시를 요청할 때라는 지침을 실행하지 않습니다.

해결책은 각 항목에 알맞은 기본 요소를 할당하는 것입니다.

Skills와 MCP가 대부분의 워크플로를 처리하고, Hooks는 코드 검사, 테스트, 보호 장치 같은 반복 작업을 자동화합니다. 컨텍스트가 무거워질 때는 Subagents가 필요합니다. 가장 흔한 실수는 skill이 필요한 곳에 subagent를 만드는 것입니다.

의사결정 트리

“Claude가 X를 하게 하고 싶다”고 생각할 때:

1. 항상 필요한 지식인가요? 예: “프로젝트에서 특정 언어를 사용한다” 또는 “em-dash를 사용하지 않는다.” → CLAUDE.md에 넣습니다.
2. 지금 직접 하고 있는, 트리거로 시작되는 절차인가요? 예: “매주 월요일 보고서를 쓴다.” → skill을 만듭니다.
3. 외부 시스템에 접근해야 하나요? 예: Stripe API나 CRM. → MCP 서버를 연결합니다.
4. Claude Code가 이벤트에 자동으로 반응해야 하나요? 예: Edit마다 linter를 실행. → hook을 작성합니다.
5. 작업이 무겁고 컨텍스트를 전부 사용하며 동시에 다른 일도 해야 하나요? → subagent에서 실행합니다.

기업가이자 바이브 코더가 하는 작업의 90%는 1-3번 범주에 속합니다. Hooks와 subagents는 “한 번에 작업 하나”를 넘어선 다음 단계의 도구입니다.

Slash Commands와 Skills는 같은 것입니다

Claude Code에서 중요한 변화가 있었습니다. 이전의 slash-command 시스템(.claude/commands/)과 skills가 사실상 통합됐습니다. .claude/commands/deploy.md 파일과 .claude/skills/deploy/SKILL.md 파일은 모두 /deploy 명령을 만듭니다. 이름이 같으면 skill이 우선합니다. 아직 예전 slash-command 형식을 사용한다면 skills로 옮기세요. 문법이 더 명확하고 기능도 더 많습니다.

Skill이 작동하지 않게 하는 실수 7가지#

1. 트리거가 없는 Description: Skill이 활성화되지 않음

증상: skill을 작성하고 구조를 확인했으며 모든 것이 유효하지만, Claude가 사용자의 요청에 skill을 호출하지 않습니다. 원인은 거의 항상 같습니다. “Helper for content writing” 같은 description입니다. Claude는 어떤 표현에 반응해야 할지 모릅니다. 해결 방법: 실제 사용자가 쓰는 문구 3-5개를 따옴표로 묶어 description에 직접 넣습니다.

2. 500줄을 넘는 SKILL.md: 집중력이 흐트러짐

Anthropic은 명시적으로 권장합니다. 파일 본문을 500줄 이내로 유지하세요. 지침이 2,000줄이면 Claude는 집중력을 잃고 단계를 부분적으로만 따르거나 순서를 혼동합니다. 해결 방법: 긴 섹션을 examples/, references/, scripts/ 같은 가까운 파일로 옮기고 SKILL.md에서 해당 파일을 참조합니다.

3. 작은 skill 세 개 대신 “콘텐츠에 관한 모든 것”을 하나의 skill에 담기

매력적으로 보이는 구성은 Telegram 게시물, 랜딩 페이지, 이메일을 모두 담은 큰 content skill 하나입니다. 하지만 작동하지 않습니다. 엉뚱한 요청에 활성화되고, 방법론이 뒤섞이며, 평균적인 결과를 냅니다. 해결 방법: skill 하나에 반복 가능한 작업 하나를 담습니다. “콘텐츠” 관련 루틴이 세 가지라면 telegram-post, landing-section, email-broadcast라는 세 skills를 만듭니다.

4. “사용하면 안 되는 경우”가 없는 Skill: 충돌 발생

증상: 프로젝트에 비슷한 skills가 두 개 있고 Claude가 잘못된 것을 호출합니다. 예를 들어 하나는 이메일 뉴스레터에 관한 것이고, 다른 하나는 프로그램 참가자를 위한 환영 이메일 전용입니다. “일반 메일링 리스트 요청이면 활성화하지 말 것”이라는 명시적 조항이 없으면 환영 이메일 skill이 “이메일”이라는 말이 나올 때마다 활성화됩니다. 해결 방법: description에 부정 사례를 분명히 적습니다.

5. 프로젝트에 Skills가 50개: Description이 잘림

Claude Code 문서에 따르면:

마켓플레이스에서 skills 컬렉션 50개를 다운로드했다면 일부 description이 잘릴 것입니다. 믿었던 키워드가 사라질 수도 있습니다. 해결 방법: 활성 프로젝트에는 가장 유용한 skills 10-15개만 둡니다. 나머지는 자신의 자료에 둔 별도 skill-archive/처럼 검색 대상 스킬 디렉터리 밖의 비활성 보관소에 두세요. 필요한 스킬만 프로젝트나 개인 범위에 설치하세요. ~/.claude/skills/는 여러 프로젝트에 보이는 설치된 개인 라이브러리이므로 그곳으로 옮겨도 검색 대상에서 사라지지 않습니다.

6. 검증되지 않은 출처의 Skills: 보안 위험

Anthropic은 공식 문서에서 이에 대해 경고합니다.

무작위 GitHub 저장소에 첫 호출 때 API 키를 유출하는 skill이 들어 있을 수도 있습니다. 해결 방법: 설치 전에 SKILL.md를 직접 열어 읽습니다. 중요한 프로젝트에서 낯선 작성자의 skills를 실행하지 마세요.

7. 지식 폴더가 없는 Skill은 “평범한 ChatGPT” 결과를 냄

가장 미묘하면서도 흔한 안티패턴입니다. skill은 방법론이지만 맥락이 없다면 방법론만으로는 의미가 없습니다. “환영 이메일 작성” skill을 만들었지만 프로젝트에 대상 독자를 설명하는 파일이나 브랜드 보이스 파일이 없다면, Claude는 누구나 쓸 법한 평범한 ChatGPT 이메일을 작성합니다.

skill은 프로젝트의 Second Brain을 CLAUDE.md 가이드의 원칙에 따라 이미 구축했을 때 가장 잘 작동합니다. 먼저 지식 구조를 만들고, 그 지식에 의존하는 skills를 만드세요. 순서를 반대로 하면 자신의 스타일을 반영한 작업이 아니라 일상적이고 평범한 품질의 결과를 얻게 됩니다.

30분 만에 첫 skill 만들기#

내 프로젝트에서 첫 skills를 만들 때 사용한 구체적인 계획은 다음과 같습니다.

1단계. 반복 작업 하나 선택하기

지난달 달력을 엽니다. 최소 4-5회 반복했고 매번 30-60분이 걸린 작업을 찾습니다. 포괄적인 “마케팅”이 아니라 “월요일 매출 보고서”, “신규 고객 온보딩”, “프로모션 가격표 업데이트”처럼 구체적인 작업이어야 합니다.

표현이 구체적일수록 skill은 단순해지고 트리거는 명확해집니다.

2단계. 절차를 직접 적기

별도 파일이나 Claude와의 채팅에서(아직 skill이 아니라 초안으로) 따르는 단계를 적습니다.

1. 고객 데이터베이스를 엽니다
2. 상태를 "환영 이메일 대기 중"으로 필터링합니다
3. 고객이 어느 채널을 통해 왔는지 확인합니다
4. "templates" 폴더에서 해당 채널의 이메일 템플릿을 가져옵니다
5. 이름, 제품, 시작 날짜를 입력합니다
6. 전송합니다

아직 skill은 아니고 메모입니다. 하지만 이 메모가 없으면 SKILL.md를 쓰기 시작하자마자 혼란스러워집니다.

3단계. 폴더 구조 만들기

mkdir -p .claude/skills/welcome-email-new-client
touch .claude/skills/welcome-email-new-client/SKILL.md

또는 모든 프로젝트에서 skill을 사용하고 싶다면 ~/.claude/skills/에 둡니다.

4단계. 템플릿에 따라 SKILL.md 작성하기

뼈대:

---
name: welcome-email-new-client
description: |
  Prepares a welcome email for a new client using the template for their acquisition channel.
  Triggers: "write a welcome email for new client X",
  "onboard new participant Y", "welcome email for client from channel Z".
  Do not activate if the request is about a general mailing list
  or an email campaign—those are other skills.
---

# Welcome Email for a New Client

## Steps

1. Read `knowledge/audience/segments.md` - what client segments we have
2. Read `knowledge/templates/welcome/` - templates by channel
3. Identify the client's channel from the request context
4. Insert the client's name, product name, and start date
5. Check the length—it should be no more than 800 characters
6. Output the final email text in a copy-ready format

## Important

- “친애하는 친구”나 “안녕하세요”를 쓰지 말고 자연스러운 말투를 사용합니다
- 한 문단에 하나의 생각을 담습니다
- 행동 유도 문구는 하나만 넣고, 두 개 넣지 않습니다

5단계. 프롬프트 5-8개로 테스트하기

이 프로젝트의 Claude Code에서 빈 채팅을 엽니다. 실제로 사용하는 문구 5개와 skill이 활성화되면 안 되는 비슷한 문구 3개를 입력해 봅니다.

활성화되어야 하는 경우:

• “신규 고객 Ivanov를 위한 환영 이메일을 써 줘”
• “프로그램 X를 구매한 신규 참가자를 온보딩해 줘”
• “Instagram을 통해 온 고객을 위한 환영 이메일”

활성화되면 안 되는 경우:

• “전체 목록에 프로모션 이메일을 보내 줘”
• “새해 연휴 이메일 캠페인”
• “결제하지 않은 고객에게 후속 이메일을 써 줘”

각 문구에서 skill이 활성화됐는지 확인합니다. 잘못된 경우에 활성화되면 description을 좁힙니다. 활성화되어야 할 때 작동하지 않으면 트리거 문구를 넓힙니다.

6단계. Description 반복 개선하기

테스트가 실패할 때마다 지침 본문은 건드리지 말고 description만 수정합니다. 2-3회 반복하면 skill이 안정적으로 활성화되기 시작합니다. 저장하고 commit한 다음 매일 사용합니다.

마지막 조언입니다. 첫 skill을 완벽하게 만들려고 하지 마세요. 우선 작동하게 만드세요. 다섯 번째나 열 번째 skill을 만들고 표현 방식과 Claude의 응답에서 패턴이 보이기 시작하면 다듬으면 됩니다.

이번 주 달력에서 반복 작업 하나를 고르고, 30분을 비워 위의 여섯 단계를 따라 해 보세요. 그러면 Claude가 추측하지 않고 당신의 방법론에 따라 일하게 됩니다.

Ailoot를 통해 AI 모델에 접근해야 한다면 Ailoot을 확인해 보세요.