skill 학습

1단계: 개념과 배경 이해

1-1. Skill이란 무엇인가

Skill은 AI 에이전트에게 특정 작업을 수행하는 방법을 가르치는 지침 폴더입니다. 핵심 파일인 SKILL.md 하나와 선택적 보조 파일들로 구성됩니다. Anthropic의 공식 가이드는 이것을 "신입 사원에게 건네는 업무 인수인계서"에 비유합니다. 한 번 작성해두면 세션이 바뀌어도, 팀원이 프로젝트를 클론해도 동일한 작업 품질이 유지됩니다.

Skill이 없을 때는 매 대화마다 "우리 프로젝트는 Next.js 15를 쓰고, ESLint 설정은 이렇고…"라고 반복 설명해야 합니다. Skill이 있으면 에이전트가 해당 매뉴얼을 자동으로 읽고 정해진 절차와 스타일대로 작업합니다.

1-2. Skill이 등장한 배경 — 바이브 코딩의 품질 문제

2025년 2월 Andrej Karpathy가 "바이브 코딩"이라는 용어를 만들었습니다. AI에게 자연어로 지시하고 생성된 코드를 그대로 수용하는 방식인데, 이 방식이 확산되면서 코드 품질 문제가 데이터로 드러났습니다.

학습해야 할 핵심 연구 결과는 다음과 같습니다.

GitClear 보고서 (2025): 211백만 줄의 코드를 분석한 결과, AI 도입 이후 코드 중복이 4배 증가했고, 역사상 처음으로 복사/붙여넣기 코드가 리팩토링 코드를 초과했습니다.

Carnegie Mellon 연구: 807개 GitHub 저장소에서 Cursor 도입 이후 정적 분석 경고가 30% 증가하고 코드 복잡도가 41% 증가했습니다. 속도 향상은 일시적이었지만 품질 문제는 누적되었습니다.

Google DORA 보고서 (2025): AI 도입과 소프트웨어 전달 안정성 사이에 부정적 상관관계가 있었습니다. 핵심 결론은 "AI는 팀을 고치지 않는다. 이미 있는 것을 증폭시킨다"는 것이었습니다.

Anthropic Agentic Coding Trends: 개발자가 업무의 약 60%에 AI를 사용하지만, 완전히 위임할 수 있는 작업은 0~20%에 불과합니다. 나머지는 "사려 깊은 설정, 적극적인 감독, 인간의 판단"이 필요합니다.

이 "설정"과 "감독"을 코드화한 것이 바로 Skill입니다. AI가 빠르게 생산하는 코드에 품질 가드레일을 씌우는 역할을 합니다.

1-3. AI가 반복하는 전형적인 코드 문제 패턴

Skill이 해결하려는 구체적인 문제 유형을 이해해야 왜 특정 방식으로 Skill을 작성해야 하는지 알 수 있습니다.

네이밍과 일관성 문제: 같은 프로젝트 안에서 변수명이 camelCase와 snake_case가 혼용되거나, data, tmp, proc 같은 모호한 이름이 사용됩니다.

코드 중복: 공통 로직을 추출하지 않고 복사/붙여넣기합니다. 같은 계산이 여러 곳에 나타납니다.

안전 검사 누락: 입력 경계 검증 없음, 데이터 구조에 대한 가정, None/null 체크 누락이 발생합니다.

가독성 문제: 매직 넘버(예: 86400가 "하루의 초"라는 설명 없이 사용), 미사용 변수, 여러 추상화 수준이 섞인 함수가 등장합니다.

이 패턴들은 Robert C. Martin의 Clean Code 17장에서 정의한 66개 코드 스멜과 정확히 일치합니다. AI가 새로운 종류의 문제를 만드는 것이 아니라, 인간이 수십 년간 피하려 노력한 문제를 더 빠르고 대규모로 재생산하는 것입니다.

1-4. Rules vs Skills vs MCP — 세 개념의 차이

이 세 가지는 에이전트 생태계에서 서로 다른 역할을 하며 혼동하기 쉽습니다.

Rules (예: .cursorrules, CLAUDE.md의 규칙 섹션)는 항상 켜져 있는 수동적 가드레일입니다. 에이전트가 매 대화마다 자동으로 읽습니다. "코드에 항상 타입 힌트를 붙여라", "커밋 메시지는 Conventional Commits 형식을 따라라" 같은 전역 규칙에 적합합니다.

Skills는 에이전트가 필요할 때만 활성화하는 능동적 지침입니다. 사용자의 요청을 보고 description 필드와 의미적으로 매칭하여 관련 Skill만 로드합니다. "블로그 포스트를 작성해줘"라고 하면 블로그 작성 Skill이 활성화되지만, "이 버그를 고쳐줘"라고 하면 활성화되지 않습니다.

**MCP (Model Context Protocol)**는 에이전트가 외부 도구(GitHub, Notion, Slack, 데이터베이스 등)에 연결하는 통로입니다.

Anthropic의 공식 가이드는 이를 주방에 비유합니다. MCP는 재료와 도구가 갖춰진 전문 주방이고, Skills는 레시피입니다. MCP가 "무엇을 할 수 있는가(what Claude can do)"를 제공하고, Skills가 "어떻게 해야 하는가(how Claude should do it)"를 제공합니다.

1-5. Progressive Disclosure — Skill의 핵심 설계 원리

Skill의 아키텍처를 관통하는 가장 중요한 원리입니다. 모든 지침을 에이전트의 컨텍스트에 한꺼번에 넣으면 "Context Saturation"이 발생하여 성능이 저하됩니다. 대신 3단계로 나누어 필요한 만큼만 로드합니다.

Level 1 — Discovery (항상 로드, ~100 토큰): 에이전트가 시작할 때 모든 Skill의 name과 description 프론트매터만 읽습니다. 이것만으로 "지금 이 요청에 어떤 Skill이 필요한가"를 판단합니다.

Level 2 — Activation (트리거 시 로드, <5000 토큰 권장): 사용자의 요청이 특정 Skill의 description과 매칭되면, 그 Skill의 SKILL.md 본문 전체를 읽습니다. 핵심 지침, 단계별 절차, 예시가 여기에 있습니다.

Level 3 — Execution (필요 시만 로드): scripts/, references/, assets/ 폴더의 파일은 본문에서 참조할 때만 읽습니다. 상세 API 가이드, 검증 스크립트, 템플릿 등이 여기에 해당합니다.

이 구조 덕분에 수십 개의 Skill을 설치해도 에이전트가 느려지지 않습니다. React 컴포넌트를 작성할 때 데이터베이스 마이그레이션 Skill까지 읽을 필요가 없기 때문입니다.

1-6. Agent Skills Open Standard — 도구 간 호환성

Agent Skills는 Claude Code에서 시작했지만 이제 오픈 표준(https://agentskills.io)으로 공개되었습니다. 동일한 SKILL.md 파일이 Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenCode 등 여러 에이전트에서 작동합니다.

Vercel이 만든 skills.sh (https://skills.sh)는 이 표준을 기반으로 한 공개 마켓플레이스이며, npx skills add 명령 하나로 여러 에이전트에 동시 설치할 수 있습니다. 이것은 Skill을 "특정 도구에 종속된 설정"이 아니라 "팀의 지식 자산"으로 만드는 핵심 특성입니다.

1-7. Skill의 세 가지 유스케이스 카테고리

Anthropic이 관찰한 Skill 활용의 세 가지 패턴입니다.

카테고리 1 — 문서/자산 생성: 일관된 고품질 결과물(문서, 프레젠테이션, UI, 코드 등)을 만드는 Skill. 외부 도구 없이 AI의 내장 기능만 사용합니다. 예: frontend-design Skill, 블로그 포스팅 스타일 Skill.

카테고리 2 — 워크플로우 자동화: 일관된 방법론이 필요한 다단계 프로세스를 위한 Skill. 예: skill-creator Skill (Skill 작성 과정 자체를 자동화), 코드 리뷰 워크플로우 Skill.

카테고리 3 — MCP 강화: MCP가 제공하는 도구 접근에 워크플로우 지식을 더하는 Skill. MCP가 Linear에 연결해주면, Skill이 "스프린트 플래닝은 이 순서로 이렇게 해라"를 가르칩니다. 예: sentry-code-review Skill.

1단계 학습 자료

| 자료 | 내용 | 형식 | |------|------|------| | Anthropic 32페이지 가이드 PDF (https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) | 1단계와 2단계의 거의 모든 내용을 포함하는 공식 자료. 가장 먼저 읽을 것 | PDF | | Dev.to — "Skills, Not Vibes" (https://dev.to/gde/skills-not-vibes-teaching-ai-agents-to-write-clean-code-3l9e) | 품질 문제의 데이터, Clean Code와의 연결 | 영문 글 | | Creative Tim 가이드 (https://www.creative-tim.com/blog/ai-agent/what-are-ai-agent-skills-a-practical-guide-to-skillmd) | skills.sh 생태계 전체 조감도 | 영문 글 | | YouTube — "AI 에이전트 전용 Skills.md 훈련 가이드" (https://www.youtube.com/watch?v=g04eOqTdmz8) | 한국어로 전체 흐름 파악 | 한국어 영상 | | YouTube — "클로드 스킬로 바이브 코딩 더 쉽게 하는 방법" (https://www.youtube.com/watch?v=rNtpNY41h5o) | 한국어 실습 중심 | 한국어 영상 |

2단계: 공식 스펙과 Best Practice 정독

2-1. 디렉토리 구조

Skill은 최소 SKILL.md 파일 하나를 포함하는 폴더입니다.

skill-name/
├── SKILL.md              ← 필수. 유일하게 반드시 있어야 하는 파일
├── scripts/              ← 선택. 에이전트가 실행할 수 있는 코드
│   ├── validate.py
│   └── check.sh
├── references/           ← 선택. 필요 시 읽는 추가 문서
│   ├── REFERENCE.md
│   └── api-guide.md
└── assets/               ← 선택. 템플릿, 이미지, 데이터 파일
    └── report-template.md

폴더 이름 규칙: 반드시 kebab-case를 사용합니다. notion-project-setup은 맞고, Notion Project Setup(공백), notion_project_setup(언더스코어), NotionProjectSetup(대문자)은 모두 틀립니다. 그리고 폴더 이름은 SKILL.md 안의 name 필드와 정확히 일치해야 합니다.

README.md를 넣지 않습니다: Skill 폴더 안에는 README.md를 두지 않습니다. 모든 문서는 SKILL.md 또는 references/에 넣습니다. (GitHub 저장소의 최상위에 사람을 위한 README는 별도로 둡니다.)

2-2. SKILL.md 파일의 두 부분

SKILL.md는 YAML 프론트매터와 마크다운 본문으로 구성됩니다.

---
name: code-review-guide
description: Pull Request 코드 리뷰 자동화. PR, 코드 리뷰, 검토 요청 시 코드 품질, 보안, 스타일 검사 수행.
---

# 코드 리뷰 가이드

여기에 실제 지침이 들어갑니다...

프론트매터는 반드시 파일 최상단에 ---로 열고 닫아야 합니다. 이 구분자가 없거나 따옴표가 닫히지 않으면 업로드 자체가 실패합니다.

2-3. 프론트매터 필드 상세 규칙

`name` (필수)

| 규칙 | 설명 | |------|------| | 글자 수 | 1~64자 | | 허용 문자 | 유니코드 소문자 알파벳, 숫자, 하이픈(a-z, 0-9, -)만 | | 시작/끝 | 하이픈으로 시작하거나 끝날 수 없음 | | 연속 하이픈 | -- 불가 | | 폴더명 일치 | 부모 폴더 이름과 정확히 같아야 함 |

# 올바른 예시
name: pdf-processing
name: data-analysis
name: code-review

# 잘못된 예시
name: PDF-Processing      # 대문자 불가
name: -pdf                # 하이픈으로 시작 불가
name: pdf--processing     # 연속 하이픈 불가
name: my_cool_skill       # 언더스코어 불가

추가로, "claude"나 "anthropic"이 포함된 이름은 예약어로 사용할 수 없습니다.

`description` (필수)

이 필드가 Skill 작성에서 가장 중요한 부분입니다. 에이전트는 description만 보고 100개가 넘는 Skill 중에서 지금 사용할 것을 선택합니다. description이 모호하면 Skill이 아예 활성화되지 않습니다.

| 규칙 | 설명 | |------|------| | 글자 수 | 1~1024자 | | 필수 내용 | "무엇을 하는가" + "언제 사용하는가" 둘 다 포함 | | 금지 문자 | XML 꺾쇠괄호(<, >) 사용 금지 (보안상 이유 — 프론트매터가 시스템 프롬프트에 나타나므로) |

description 작성 공식: [기능 설명] + [트리거 상황] + [핵심 키워드]

# 좋은 예시 — 구체적이고 트리거 키워드 포함
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

description: Pull Request 코드 리뷰 자동화. PR, 코드 리뷰, 검토, 피드백 요청 시 코드 품질, 보안, 성능, 스타일 자동 검사.

description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

# 나쁜 예시 — 모호함
description: Helps with projects.
description: 코드 리뷰를 돕습니다.
description: Creates sophisticated multi-page documentation systems.

description 자기 검증법: 작성 후 에이전트에게 "When would you use the [skill name] skill?"이라고 물어봅니다. 에이전트가 description을 인용해서 답하므로, 그 답이 기대한 트리거 상황을 커버하는지 확인합니다.

오버트리거링 방지 팁: Skill이 관련 없는 요청에도 활성화되면, 부정 트리거를 추가합니다.

description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).

`license` (선택)

license: MIT
license: Apache-2.0
license: Proprietary. LICENSE.txt has complete terms

`compatibility` (선택, 1~500자)

환경 요구사항이 있을 때만 사용합니다.

compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet

`metadata` (선택)

임의의 키-값 쌍을 넣을 수 있는 확장 필드입니다.

metadata:
  author: my-team
  version: "1.0.0"
  mcp-server: linear
  category: productivity
  tags: [project-management, automation]

`allowed-tools` (선택, 실험적)

에이전트가 이 Skill 실행 중 사전 승인된 도구 목록입니다.

allowed-tools: Bash(git:*) Bash(jq:*) Read

2-4. 마크다운 본문 작성법

프론트매터 아래의 본문이 실제 작업 지침입니다. 특별한 구문 제한은 없으며, 에이전트가 작업을 효과적으로 수행하는 데 도움이 되는 것이면 무엇이든 씁니다.

Anthropic 권장 본문 구조 템플릿:

---
name: your-skill
description: [...]
---

# Skill 이름

## Instructions

### Step 1: [첫 번째 주요 단계]
구체적인 설명.

예시:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID

기대 결과: [성공이 어떤 모습인지 설명]

Step 2: [두 번째 주요 단계]

...

Examples

Example 1: [흔한 시나리오]

사용자가 말하는 것: "새 마케팅 캠페인을 설정해줘" 수행 절차:

MCP를 통해 기존 캠페인 조회
제공된 파라미터로 새 캠페인 생성 결과: 확인 링크와 함께 캠페인 생성 완료

Troubleshooting

Error: [흔한 에러 메시지]

원인: [왜 발생하는지] 해결: [어떻게 고치는지]

본문 작성의 핵심 원칙들:

구체적이고 실행 가능하게 쓸 것: "데이터를 검증하세요"가 아니라 "python scripts/validate.py --input {filename}을 실행해서 데이터 포맷을 검사하세요. 실패하면 흔한 문제로는 필수 필드 누락(CSV에 추가), 날짜 형식 오류(YYYY-MM-DD 사용)가 있습니다"라고 씁니다.

중요한 지침은 맨 위에: 에이전트가 본문을 위에서 아래로 읽으므로, 핵심 규칙일수록 앞에 놓습니다. ## Important 또는 ## Critical 헤더를 사용하고, 정말 중요한 내용은 반복해도 됩니다.

애매한 표현 금지: "적절하게 처리하세요"가 아니라, "CRITICAL: create_project를 호출하기 전에 반드시 확인할 것 — 프로젝트 이름이 비어있지 않을 것, 팀 멤버가 최소 1명 배정되어 있을 것, 시작일이 과거가 아닐 것"으로 씁니다.

나쁜 예와 좋은 예를 함께 보여줄 것: 에이전트는 대조적인 예시에서 규칙을 가장 잘 학습합니다.

# Bad - 매직 넘버 사용
if elapsed_time > 86400:
    ...

# Good - 명명된 상수 사용
SECONDS_PER_DAY = 86400
if elapsed_time > SECONDS_PER_DAY:
    ...

선택지를 줄이고 명확한 권장을 할 것: "pypdf, pdfplumber, PyMuPDF 중 하나를 사용할 수 있습니다"가 아니라 "텍스트 추출은 pdfplumber를 사용하세요. 스캔된 PDF에 OCR이 필요하면 pdf2image + pytesseract를 사용하세요"로 결정을 내려줍니다.

검증 로직은 코드를 이용할 것: 정말 중요한 검증은 언어 지침 대신 scripts/ 안의 스크립트로 처리합니다. 자연어 해석은 확률적이지만 코드는 결정적입니다.

2-5. 본문 크기 관리와 파일 분리

| 항목 | 권장치 | |------|--------| | SKILL.md 본문 | 500줄 이하, 5,000토큰 이하 | | 개별 참조 파일 | 각 파일을 집중적으로 유지 (작을수록 좋음) | | 파일 참조 깊이 | SKILL.md에서 1단계 깊이만 |

본문이 길어지면 Progressive Disclosure 원칙에 따라 분리합니다.

# SKILL.md 안에서 참조하는 방법

## SEO 최적화
상세한 SEO 가이드는 `references/seo-guide.md`를 참고하세요.

## 데이터 검증
검증이 필요하면 `scripts/validate.py`를 실행하세요.

파일 참조 시 주의사항: 스킬 루트로부터의 상대 경로를 사용합니다. ./reference.md(현재 디렉토리 표기)나 C:\docs\guide.md(윈도우 절대경로) 대신 references/guide.md(Unix 스타일 상대경로)를 씁니다. 깊은 중첩 참조 체인(A가 B를 참조하고 B가 C를 참조)은 피합니다.

2-6. scripts/ 디렉토리 작성 규칙

스크립트는 에이전트가 직접 실행할 수 있는 코드입니다. Python, Bash, JavaScript가 흔히 사용됩니다.

작성 시 지켜야 할 세 가지: 자체 완결적이거나 의존성을 명확히 문서화할 것, 유용한 에러 메시지를 포함할 것, 엣지 케이스를 우아하게 처리할 것.

2-7. references/ 디렉토리 작성 규칙

에이전트가 필요할 때만 읽는 추가 문서입니다. REFERENCE.md(상세 기술 레퍼런스), FORMS.md(폼 템플릿), 도메인별 파일(finance.md, legal.md 등)을 넣을 수 있습니다. 각 파일은 하나의 주제에 집중하여 작게 유지합니다. 에이전트가 온디맨드로 로드하므로 파일이 작을수록 컨텍스트 소비가 적습니다.

2-8. 하나의 Skill = 하나의 명확한 역할

틀린 예: 하나의 Skill 안에 블로그 작성 + 코드 리뷰 + API 설계를 모두 넣기.

맞는 예: blog-posting/, code-review/, api-design/으로 분리하기.

범위가 넓은 Skill은 description이 모호해지고, 오버트리거링이 발생하며, 불필요한 지침이 컨텍스트를 낭비합니다.

2-9. 흔한 실수와 트러블슈팅

Skill이 업로드 안 됨 — "Could not find SKILL.md": 파일 이름이 정확히 SKILL.md(대소문자 구분)여야 합니다. SKILL.MD, skill.md, Skill.md 모두 안 됩니다.

Skill이 업로드 안 됨 — "Invalid frontmatter": YAML 구분자 ---가 빠졌거나, 따옴표가 닫히지 않았거나, 들여쓰기가 잘못된 경우입니다.

# 틀림 — 구분자 없음
name: my-skill
description: Does things

# 틀림 — 따옴표 미닫힘
---
name: my-skill
description: "Does things
---

# 맞음
---
name: my-skill
description: Does things
---

Skill이 트리거 안 됨: description이 너무 일반적이거나 트리거 키워드가 부족한 경우입니다. "프로젝트를 돕습니다"를 "Next.js 프로젝트 초기 설정 자동화. 프로젝트 생성, 초기 설정, scaffolding 요청 시 사용"으로 바꿉니다.

Skill이 너무 자주 트리거됨: description에 부정 트리거를 추가하거나 범위를 좁힙니다. "문서를 처리합니다"를 "PDF 법률 문서를 계약 검토용으로 처리합니다"로 구체화합니다.

Skill이 로드됐지만 지침을 안 따름: 지침이 너무 장황하거나(핵심이 묻힘), 표현이 애매하거나(구체적 행동 대신 추상적 표현), 중요한 내용이 본문 아래쪽에 묻혀 있는 경우입니다.

컨텍스트 과부하로 응답이 느림: SKILL.md가 너무 크거나, 동시에 활성화된 Skill이 너무 많은 경우입니다. 본문을 5,000 토큰 이내로 유지하고, 상세 내용을 references/로 분리합니다. 동시에 20~50개 이상의 Skill이 활성화되어 있다면 선택적으로 줄입니다.

2-10. Skill 검증

작성 후 공식 검증 도구로 스펙 준수 여부를 확인합니다.

skills-ref validate ./my-skill

이 명령은 프론트매터가 유효한지, 네이밍 규칙을 따르는지 등을 검사합니다.

2-11. 성공 기준 정의 방법

Skill을 만들기 전에 "잘 작동한다"의 기준을 먼저 세워야 합니다.

정량적 기준 (대략적 벤치마크):

관련 쿼리 10~20개를 테스트하여 90% 이상에서 Skill이 자동 트리거되는가
Skill 없이 작업할 때 대비 도구 호출 횟수와 토큰 소비가 줄어드는가
워크플로우 중 API 호출 실패가 0건인가

정성적 기준:

사용자가 다음 단계를 직접 프롬프트하지 않아도 에이전트가 진행하는가
사용자의 수정 없이 워크플로우가 완료되는가
동일 요청을 3~5회 반복해도 구조적으로 일관된 결과가 나오는가

2단계 학습 자료

| 자료 | 내용 | 우선순위 | |------|------|----------| | Agent Skills Specification (https://agentskills.io/specification) | 포맷의 절대적 기준. 모든 필드 규칙, 디렉토리 구조, Progressive Disclosure 정의 | 최우선 | | Anthropic 32페이지 PDF (https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) | Planning & Design, Testing & Iteration, Patterns & Troubleshooting 챕터 포함 | 최우선 | | Anthropic Best Practices (https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) | Progressive Disclosure 패턴, description 작성법, 본문 구조화 | 높음 | | 한국어 완벽 가이드 (https://jeremyrecord.tistory.com/425) | 위 내용의 한국어 정리 + 실전 예시 | 높음 | | Velog — Claude Agent Skills 사용방법 (https://velog.io/@yonghyuk/Claude-Agent-Skills-사용방법) | 3단계 로딩, 필드별 요구사항, 작성 팁 한국어 정리 | 보통 |

2단계 완료 후 자기 점검 체크리스트

2단계를 마쳤을 때 아래 질문에 모두 답할 수 있어야 합니다.

SKILL.md의 두 부분(프론트매터 / 본문)의 역할 차이를 설명할 수 있는가
name 필드의 5가지 제약 조건을 기억하는가 (길이, 허용 문자, 시작/끝, 연속 하이픈, 폴더명 일치)
description에 반드시 포함해야 하는 두 가지 요소("무엇을 하는가" + "언제 사용하는가")를 알고 있는가
좋은 description과 나쁜 description의 차이를 3개 이상 예시로 들 수 있는가
Progressive Disclosure의 3단계(메타데이터 → 본문 → 리소스 파일)를 그림으로 그릴 수 있는가
scripts/, references/, assets/의 용도와 로딩 시점의 차이를 설명할 수 있는가
SKILL.md 본문의 권장 크기 제한(500줄, 5000토큰)을 알고, 초과 시 어떻게 분리하는지 아는가
description이 너무 모호할 때(언더트리거링)와 너무 넓을 때(오버트리거링)의 증상과 해결법을 아는가
Skill 폴더 안에 README.md를 넣으면 안 되는 이유를 아는가
프론트매터에서 XML 꺾쇠괄호(<, >)가 금지된 보안상 이유를 이해하는가

3단계: SKILL.md 실전 작성 실습 가이드

이 가이드는 학생이 처음부터 끝까지 직접 따라할 수 있도록, 명령어 한 줄까지 구체적으로 안내합니다. 대상 에이전트는 Claude Code, OpenCode, GitHub Copilot (VS Code) 세 가지입니다.

사전 준비: 실습 환경 구성

실습을 시작하기 전에 세 가지 에이전트의 Skill 저장 경로를 정확히 이해해야 합니다. 동일한 SKILL.md 파일이 경로만 다를 뿐 세 도구 모두에서 작동합니다.

에이전트별 Skill 저장 경로

Claude Code는 프로젝트 수준에서 .claude/skills/<skill-name>/SKILL.md를, 개인 전역 수준에서 ~/.claude/skills/<skill-name>/SKILL.md를 탐색합니다. Claude Code는 .claude/skills/ 경로가 기본입니다. Skill이 설치되면 /skill-name 형태의 슬래시 명령으로 직접 호출할 수도 있고, description이 매칭되면 자동으로 활성화되기도 합니다.

OpenCode는 여러 경로를 동시에 탐색합니다. .opencode/skills/<name>/SKILL.md가 고유 경로이고, .claude/skills/<name>/SKILL.md와 .agents/skills/<name>/SKILL.md도 호환 경로로 인식합니다. 전역 경로는 ~/.config/opencode/skills/<name>/SKILL.md, ~/.claude/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md입니다. OpenCode는 에이전트가 skill({ name: "skill-name" }) 도구 호출로 Skill을 로드합니다.

**GitHub Copilot (VS Code)**는 프로젝트 수준에서 .github/skills/<name>/SKILL.md를, 개인 수준에서 ~/.copilot/skills/<name>/SKILL.md를 탐색합니다. .claude/skills/와 .agents/skills/도 호환 경로로 인식합니다. VS Code 채팅창에서 /skill-name으로 슬래시 명령 호출이 가능합니다.

실습 프로젝트 생성

터미널에서 실습용 빈 프로젝트를 하나 만듭니다.

mkdir skill-lab && cd skill-lab
git init
mkdir -p .claude/skills
mkdir -p .opencode/skills
mkdir -p .github/skills

.claude/skills/에 Skill을 만들면 Claude Code와 OpenCode가 모두 인식합니다. GitHub Copilot을 위해서는 .github/skills/에도 같은 Skill을 복사하거나, npx skills CLI를 이용합니다.

실습 3-1: 기존 우수 Skill 분석

직접 Skill을 만들기 전에, 잘 만들어진 Skill을 읽고 분석하는 것이 먼저입니다. "좋은 코드를 읽어야 좋은 코드를 쓴다"는 원리가 Skill에도 그대로 적용됩니다.

과제 A: anthropics/skills 저장소 클론 및 분석

git clone https://github.com/anthropics/skills.git ~/study/anthropics-skills
cd ~/study/anthropics-skills

이 저장소에서 두 가지 Skill을 집중 분석합니다.

분석 대상 1: skill-creator

이것은 "Skill을 만드는 방법을 가르치는 Skill"입니다. SKILL.md를 열고 다음 항목을 노트에 기록하세요.

cat skill-creator/SKILL.md

기록할 것: (1) description 필드에 어떤 트리거 키워드가 포함되어 있는가. (2) 본문이 몇 줄인가, 500줄 이내인가. (3) 본문의 섹션 구조는 어떤가 (헤더 계층이 어떻게 구성되었는가). (4) references/ 또는 scripts/ 폴더가 있는가, 있다면 SKILL.md에서 어떻게 참조하는가. (5) 예시(좋은 예/나쁜 예)가 포함되어 있는가.

분석 대상 2: frontend-design

cat frontend-design/SKILL.md

같은 항목을 기록하되, 추가로: (6) 이 Skill의 scope(담당 범위)는 어디까지인가, 코드 작성까지 포함하는가 아니면 디자인 원칙만 다루는가. (7) description이 카테고리 1(문서/자산 생성) 유형에 어떻게 맞춰져 있는가.

과제 B: skills.sh 인기 Skill 비교 분석

브라우저에서 https://skills.sh 에 접속하여 All Time 탭에서 상위 5개 Skill을 확인합니다.

각 Skill에 대해 다음 비교표를 작성하세요.

| Skill 이름 | description 길이 (대략) | 트리거 키워드 개수 | "무엇을" / "언제" 구분 여부 | 폴더 구조 (단일파일 vs 멀티파일) | 본문 내 예시 포함 여부 | |---|---|---|---|---|---| | (이름) | | | | | |

이 비교표를 통해 "잘 쓰인 description의 공통 패턴"을 발견하는 것이 목표입니다.

과제 C: Clean Code Skills 분석

git clone https://github.com/ertugrul-dmr/clean-code-skills.git ~/study/clean-code-skills
cd ~/study/clean-code-skills

이 저장소에는 clean-comments, clean-functions, clean-general 등 여러 Skill이 있습니다. 하나의 큰 주제(Clean Code)를 여러 Skill로 분리한 방식에 주목하세요.

기록할 것: (1) 각 Skill의 scope가 어떻게 나뉘어 있는가. (2) 한 Skill 안에서 "규칙 → 나쁜 예시 코드 → 좋은 예시 코드" 패턴이 어떻게 반복되는가. (3) boy-scout이라는 오케스트레이터 Skill이 다른 Skill들과 어떤 관계인가.

과제 D: 분석 보고서 작성

위 A~C의 분석 결과를 종합하여, 자신만의 "좋은 SKILL.md 작성 체크리스트"를 10개 항목으로 정리합니다. 예를 들어: "description에는 반드시 동사로 시작하는 기능 설명 + 'Use when' 트리거 문장을 포함한다" 등. 이 체크리스트는 이후 모든 실습에서 자기 검증 도구로 사용합니다.

실습 3-2: 직접 작성 — 난이도별 5단계

연습 1 (입문): Git 커밋 메시지 규칙 Skill

목표: 가장 단순한 단일 파일 Skill을 만들고, 세 에이전트 모두에서 작동하는지 확인합니다.

Step 1 — 폴더 생성

cd ~/skill-lab
mkdir -p .claude/skills/commit-message

Step 2 — SKILL.md 작성

nano .claude/skills/commit-message/SKILL.md (또는 VS Code로 파일 생성)

아래 내용을 직접 타이핑합니다 (복사/붙여넣기 대신 직접 치면서 구조를 체득합니다).

---
name: commit-message
description: Generate conventional commit messages following the Conventional Commits spec. Use when committing code, writing commit messages, or when user mentions "commit", "커밋", or "git commit".
---

# Conventional Commit Messages

## Format

Every commit message follows this structure:

[optional body]

[optional footer]


## Types

- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Formatting, missing semi-colons, etc (no code change)
- refactor: Code change that neither fixes a bug nor adds a feature
- test: Adding or correcting tests
- chore: Changes to build process or auxiliary tools

## Rules

1. Subject line must not exceed 50 characters
2. Use imperative mood ("add" not "added" or "adds")
3. Do not end the subject line with a period
4. Separate subject from body with a blank line
5. Body should explain WHAT and WHY, not HOW

## Examples

### Good

feat(auth): add OAuth2 login with Google

Implements Google OAuth2 flow to reduce signup friction. Closes #142


### Bad

updated stuff

Fixed the bug in login page and also changed some CSS and updated the readme.

Step 3 — 세 에이전트에 배포

Claude Code와 OpenCode는 .claude/skills/ 경로를 자동 인식하므로 추가 작업이 필요 없습니다. GitHub Copilot을 위해 복사합니다.

mkdir -p .github/skills/commit-message
cp .claude/skills/commit-message/SKILL.md .github/skills/commit-message/SKILL.md

또는 npx skills CLI로 한 번에 설치하는 방법을 연습하려면, 이 Skill을 GitHub 저장소에 push한 뒤 아래 명령을 사용합니다.

npx skills add <your-github-id>/skill-lab --skill commit-message -a claude-code -a opencode -a github-copilot

Step 4 — 테스트

각 에이전트에서 다음 프롬프트를 입력하고, Skill이 트리거되는지 확인합니다.

# Claude Code에서 (터미널)
claude
> 이 변경사항에 대한 커밋 메시지를 만들어줘

# 또는 슬래시 명령으로 직접 호출
> /commit-message 로그인 기능 추가

# OpenCode에서 (터미널)
opencode
> 커밋 메시지를 작성해줘

# VS Code에서 (Copilot 채팅창)
> /commit-message feat 타입으로 커밋 메시지 만들어줘

검증 체크리스트: (1) 세 에이전트 모두에서 Conventional Commits 형식이 적용되었는가. (2) "커밋" 키워드 없이 "이 변경사항을 정리해줘"라고 했을 때도 트리거되는가 (안 되면 description에 키워드 추가). (3) 슬래시 명령 /commit-message가 작동하는가.

연습 2 (초급): 코드 리뷰 Skill

목표: 좀 더 복잡한 지침과 체크리스트를 포함하는 Skill을 만듭니다.

Step 1 — 폴더 생성 및 SKILL.md 작성

mkdir -p .claude/skills/code-review

.claude/skills/code-review/SKILL.md를 작성합니다.

---
name: code-review
description: Perform structured code review on files or pull requests. Use when user asks for "code review", "리뷰", "PR review", "코드 검토", or wants feedback on code quality, security, and performance.
---

# Structured Code Review

## Process

### Step 1: Understand Context
Read the changed files and understand the purpose of the changes.

### Step 2: Check Code Quality
Review against these criteria:
- **Single Responsibility**: Each function does one thing
- **Naming**: Variables and functions have descriptive names
- **Duplication**: No copy-pasted code blocks
- **Complexity**: No deeply nested conditionals (max 3 levels)

### Step 3: Check Security
- No hardcoded API keys or secrets
- User input is validated and sanitized
- SQL queries use parameterized statements
- No sensitive data in logs

### Step 4: Check Performance
- No unnecessary loops or redundant calculations
- Database queries are optimized (no N+1 problems)
- Large data sets use pagination

### Step 5: Provide Feedback

Format your review as:

Summary

[1-2 sentence overview]

Strengths

[specific positive observation]

Issues Found

[Critical/Warning/Suggestion] — [file:line]

Problem: [what's wrong] Why it matters: [impact] Suggested fix: [code snippet]


## What NOT to Review
- Personal style preferences not in the project style guide
- Whitespace-only changes
- Auto-generated files

Step 2 — 배포 및 테스트

mkdir -p .github/skills/code-review
cp .claude/skills/code-review/SKILL.md .github/skills/code-review/SKILL.md

테스트 프롬프트 예시:

이 파일을 리뷰해줘: src/auth/login.py

PR #42의 변경사항을 코드 리뷰해줘

/code-review src/utils/helpers.js

실습 과제: 리뷰 결과의 형식이 SKILL.md에서 정의한 포맷(Summary → Strengths → Issues Found)을 따르는지 확인합니다. 만약 에이전트가 형식을 따르지 않으면, 본문의 지침을 더 강하게 ("CRITICAL: Always use the exact format below") 수정하고 다시 테스트합니다.

연습 3 (중급): 폴더 구조를 갖춘 API 설계 Skill

목표: references/와 scripts/ 폴더를 활용하는 Progressive Disclosure 패턴을 연습합니다.

Step 1 — 전체 폴더 구조 생성

mkdir -p .claude/skills/api-design/{references,scripts}

Step 2 — SKILL.md 작성 (핵심 지침만)

.claude/skills/api-design/SKILL.md:

---
name: api-design
description: Design RESTful APIs following project conventions. Use when creating new API endpoints, designing API contracts, or when user mentions "API", "endpoint", "REST", or "route design".
---

# RESTful API Design Guide

## Core Principles

1. Use nouns for resources, not verbs: `/users` not `/getUsers`
2. Use HTTP methods correctly: GET (read), POST (create), PUT (full update), PATCH (partial update), DELETE (remove)
3. Use plural nouns: `/users` not `/user`
4. Nest resources for relationships: `/users/{id}/orders`
5. Maximum nesting depth: 2 levels

## Response Format

All responses follow a consistent envelope:

```json
{
  "data": {},
  "meta": { "page": 1, "total": 100 },
  "errors": []
}

Error Handling

Use standard HTTP status codes:

400: Bad Request (validation errors)
401: Unauthorized
403: Forbidden
404: Not Found
409: Conflict
500: Internal Server Error

For detailed naming conventions and advanced patterns, see references/naming-conventions.md.

To validate an OpenAPI spec, run the validation script: scripts/validate-spec.sh


**Step 3 — references/naming-conventions.md 작성 (상세 참고 문서)**

```markdown
# API Naming Conventions — Detailed Reference

## URL Naming Rules

### Query Parameters
- Use camelCase: `sortBy`, `pageSize`, `startDate`
- Use `snake_case` only if the project convention requires it
- Boolean filters: `isActive=true`, not `active=1`

### Path Parameters
- Use kebab-case for multi-word resources: `/user-profiles`
- Use singular for single-resource actions: `/users/{id}`

### Versioning
- Prefix with version: `/v1/users`, `/v2/users`
- Never break existing versions; deprecate and migrate

### Pagination
- Use `page` and `pageSize` query parameters
- Default page size: 20, maximum: 100
- Always return `meta.total` in response

### Filtering
- Simple: `?status=active`
- Multiple values: `?status=active,pending`
- Range: `?createdAfter=2025-01-01&createdBefore=2025-12-31`

### Sorting
- Single field: `?sortBy=createdAt&order=desc`
- Multiple fields: `?sortBy=createdAt:desc,name:asc`

Step 4 — scripts/validate-spec.sh 작성 (검증 스크립트)

#!/bin/bash
# Validates an OpenAPI spec file
# Usage: ./validate-spec.sh <path-to-spec.yaml>

SPEC_FILE="${1:?Usage: validate-spec.sh <spec-file>}"

if [ ! -f "$SPEC_FILE" ]; then
  echo "ERROR: File not found: $SPEC_FILE"
  exit 1
fi

echo "Validating: $SPEC_FILE"

# Check required fields
for field in openapi info paths; do
  if ! grep -q "^${field}:" "$SPEC_FILE" 2>/dev/null && \
     ! grep -q "\"${field}\":" "$SPEC_FILE" 2>/dev/null; then
    echo "WARNING: Missing required field: $field"
  fi
done

# Check for common issues
if grep -qE '(password|secret|api_key)' "$SPEC_FILE"; then
  echo "SECURITY WARNING: Possible sensitive data in spec file"
fi

echo "Validation complete."

chmod +x .claude/skills/api-design/scripts/validate-spec.sh

Step 5 — 세 에이전트에 배포

# GitHub Copilot용
cp -r .claude/skills/api-design .github/skills/api-design

# OpenCode는 .claude/skills/를 자동 인식하므로 추가 작업 불필요

Step 6 — 테스트 시나리오

시나리오 1 — 기본 트리거: 사용자 관리 API를 설계해줘라고 요청합니다. SKILL.md의 Core Principles가 적용되어 /users, /users/{id} 형태의 엔드포인트가 나오는지 확인합니다.

시나리오 2 — 참조 파일 로드: API의 쿼리 파라미터 네이밍 규칙은 어때야 하지?라고 요청합니다. 에이전트가 references/naming-conventions.md를 읽어서 camelCase 규칙, pagination 기본값 등을 답하는지 확인합니다.

시나리오 3 — 스크립트 실행: /api-design spec.yaml 파일을 검증해줘라고 요청합니다. 에이전트가 scripts/validate-spec.sh를 실행하는지 확인합니다.

실습 과제: 만약 시나리오 2에서 에이전트가 참조 파일을 읽지 않고 SKILL.md 본문만으로 답한다면, 본문의 참조 문구를 더 명시적으로 수정합니다. 예: "상세 네이밍 규칙은 반드시 references/naming-conventions.md를 읽은 후 답하세요."

연습 4 (심화): 프로젝트 전용 Skill 세트 — 3개 Skill의 역할 분리

목표: 하나의 프로젝트에서 여러 Skill이 scope 충돌 없이 각자의 역할을 수행하도록 설계합니다.

가상 프로젝트 설정: Next.js + TypeScript + Tailwind CSS로 만드는 웹 애플리케이션을 가정합니다.

Skill 세트 설계

| Skill 이름 | 담당 범위 | 트리거 상황 | |---|---|---| | nextjs-component | React 컴포넌트 작성 규칙 | 새 컴포넌트 생성, UI 개발 | | nextjs-api-route | API Route 작성 규칙 | 서버 엔드포인트 개발 | | nextjs-testing | 테스트 코드 작성 규칙 | 테스트 작성, TDD |

핵심은 description이 서로 겹치지 않도록 설계하는 것입니다.

Skill 1: .claude/skills/nextjs-component/SKILL.md

---
name: nextjs-component
description: Create React components for Next.js with TypeScript and Tailwind CSS. Use when building UI components, pages, or layouts. Triggers on "component", "컴포넌트", "page", "layout", "UI".
---

# Next.js Component Guide

## File Structure
- Components go in `src/components/`
- Pages go in `src/app/`
- Use PascalCase for component files: `UserProfile.tsx`

## Component Template

```tsx
interface Props {
  // Always define explicit props interface
}

export function ComponentName({ prop1, prop2 }: Props) {
  return (
    <div className="...">
      {/* Tailwind classes only, no inline styles */}
    </div>
  );
}

Rules

Always use named exports, not default exports
Props interface must be defined above the component
Use Tailwind CSS classes exclusively — no CSS modules, no inline styles
Server Components by default; add "use client" only when needed
Keep components under 150 lines; extract sub-components if longer


**Skill 2: `.claude/skills/nextjs-api-route/SKILL.md`**

```markdown
---
name: nextjs-api-route
description: Create Next.js API route handlers with proper validation and error handling. Use when building server endpoints, API routes, or backend logic. Triggers on "API route", "endpoint", "서버", "handler", "route handler".
---

# Next.js API Route Guide

## File Structure
- API routes go in `src/app/api/`
- Use route.ts naming convention

## Route Handler Template

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const requestSchema = z.object({
  // Always validate input with zod
});

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validated = requestSchema.parse(body);
    // ... business logic
    return NextResponse.json({ data: result });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json({ errors: error.issues }, { status: 400 });
    }
    return NextResponse.json({ errors: ['Internal server error'] }, { status: 500 });
  }
}

Rules

Always validate input with zod schemas
Use try/catch with specific error types
Return consistent response envelope: { data, errors }
Never expose internal error messages to clients


**Skill 3: `.claude/skills/nextjs-testing/SKILL.md`**

```markdown
---
name: nextjs-testing
description: Write tests for Next.js applications using Vitest and Testing Library. Use when creating tests, writing test cases, or debugging test failures. Triggers on "test", "테스트", "TDD", "vitest", "testing".
---

# Next.js Testing Guide

## Framework
- Unit tests: Vitest
- Component tests: @testing-library/react
- E2E tests: Playwright

## Test File Convention
- Co-locate test files: `ComponentName.test.tsx`
- Test directory for integration: `__tests__/`

## Component Test Template

```tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { ComponentName } from './ComponentName';

describe('ComponentName', () => {
  it('renders correctly with required props', () => {
    render(<ComponentName title="Test" />);
    expect(screen.getByText('Test')).toBeInTheDocument();
  });

  it('handles user interaction', async () => {
    const user = userEvent.setup();
    const onClickMock = vi.fn();
    render(<ComponentName onClick={onClickMock} />);
    await user.click(screen.getByRole('button'));
    expect(onClickMock).toHaveBeenCalledOnce();
  });
});

Rules

Test behavior, not implementation details
Use screen.getByRole over getByTestId when possible
Each test should be independent — no shared mutable state
Name tests as sentences: "it renders correctly when..."


**배포**

```bash
# 세 Skill 모두 GitHub Copilot 경로에도 복사
for skill in nextjs-component nextjs-api-route nextjs-testing; do
  mkdir -p .github/skills/$skill
  cp .claude/skills/$skill/SKILL.md .github/skills/$skill/SKILL.md
done

테스트 — Scope 분리 검증

이것이 이 연습의 핵심입니다. 각 프롬프트가 정확히 하나의 Skill만 트리거하는지 확인합니다.

| 테스트 프롬프트 | 기대 트리거 Skill | 트리거 안 되어야 할 Skill | |---|---|---| | "UserProfile 컴포넌트를 만들어줘" | nextjs-component | nextjs-api-route, nextjs-testing | | "/api/users POST 엔드포인트를 만들어줘" | nextjs-api-route | nextjs-component, nextjs-testing | | "UserProfile 컴포넌트의 테스트를 작성해줘" | nextjs-testing | nextjs-component, nextjs-api-route | | "로그인 페이지를 만들어줘" | nextjs-component | 나머지 | | "이 API의 입력 검증을 추가해줘" | nextjs-api-route | 나머지 |

만약 "로그인 페이지를 만들어줘"에서 nextjs-api-route도 함께 트리거된다면, 해당 Skill의 description에서 "page"라는 키워드를 제거하고 더 구체적인 트리거 ("API route", "endpoint", "route handler")만 남깁니다.

실습 과제: Claude Code에서 What skills are available?이라고 물어보면 현재 로드된 모든 Skill의 description을 보여줍니다. 이를 통해 세 Skill이 모두 인식되는지, description이 서로 구분 가능한지 확인합니다.

연습 5 (심화+): Subagent 실행과 동적 컨텍스트 주입 (Claude Code 전용)

목표: Claude Code의 고급 기능인 context: fork와 !backtick 명령`을 활용하는 Skill을 만듭니다. 이 기능은 Claude Code에만 있는 확장이므로 OpenCode/Copilot에서는 fork 기능 없이 일반 Skill로 동작합니다.

mkdir -p .claude/skills/pr-summary

.claude/skills/pr-summary/SKILL.md:

---
name: pr-summary
description: Summarize a GitHub pull request with diff analysis. Use when reviewing PRs or when user asks for "PR summary", "PR 요약", or "pull request review".
context: fork
agent: Explore
allowed-tools: Bash(gh *)
disable-model-invocation: true
---

## Pull Request Context

- PR diff: !`gh pr diff $ARGUMENTS`
- PR description: !`gh pr view $ARGUMENTS`
- Changed files: !`gh pr diff $ARGUMENTS --name-only`

## Your Task

Based on the PR context above:

1. **Summary**: Describe the overall purpose in 2-3 sentences
2. **Key Changes**: List the most important modifications by file
3. **Risk Assessment**: Identify potential issues (breaking changes, missing tests, security concerns)
4. **Review Recommendation**: Approve, Request Changes, or Comment — with reasoning

테스트

# Claude Code에서
claude
> /pr-summary 42

이 Skill은 !backtick구문으로gh pr diff 42등의 명령을 먼저 실행하고, 그 출력을 Claude에게 전달합니다.context: fork`이므로 별도의 서브에이전트 컨텍스트에서 실행되어, 현재 대화를 방해하지 않습니다.

disable-model-invocation: true이므로 Claude가 자동으로 이 Skill을 사용하지 않고, 반드시 /pr-summary 슬래시 명령으로 직접 호출해야 합니다.

추가 실습 과제 (심화 학습)

추가 실습 A: 기존 Skill을 npx skills로 설치하고 구조 분석

커뮤니티에서 만든 Skill을 실제로 설치해보고, 설치된 파일 구조를 분석합니다.

cd ~/skill-lab

# Vercel의 React best practices Skill 설치 (세 에이전트 동시)
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -a claude-code -a opencode -a github-copilot

# Anthropic의 frontend-design Skill 설치
npx skills add anthropics/skills --skill frontend-design -a claude-code -a opencode -a github-copilot

설치 후 각 경로에 파일이 어떻게 배치되었는지 확인합니다.

find .claude/skills -name "SKILL.md" -exec echo "=== {} ===" \; -exec head -10 {} \;
find .github/skills -name "SKILL.md" -exec echo "=== {} ===" \; -exec head -10 {} \;
find .opencode/skills -name "SKILL.md" -exec echo "=== {} ===" \; -exec head -10 {} \;

실습 과제: 설치된 Skill의 SKILL.md를 열어서, 자신이 연습 1~4에서 작성한 Skill과 비교합니다. description의 구체성, 본문의 구조, 예시의 양에서 어떤 차이가 있는지 기록합니다.

추가 실습 B: skill-creator 메타 Skill을 이용한 Skill 생성

Claude에게 Skill 작성을 맡겨보고, 그 결과물을 직접 검토하고 개선합니다.

Step 1 — skill-creator 설치

npx skills add anthropics/skills --skill skill-creator -a claude-code

Step 2 — Claude에게 Skill 생성 요청

/skill-creator 우리 프로젝트는 Python FastAPI 백엔드인데, 
새로운 API 엔드포인트를 만들 때마다 같은 패턴을 반복해. 
Pydantic 모델 정의, 라우터 함수 작성, 에러 핸들링, 
그리고 pytest 테스트까지 일관된 방식으로 만드는 Skill을 생성해줘.

Step 3 — Claude가 생성한 SKILL.md 검토

자신이 3-1에서 작성한 "좋은 SKILL.md 작성 체크리스트" 10개 항목으로 Claude가 만든 Skill을 평가합니다. 부족한 부분을 직접 수정합니다.

Step 4 — 수정한 Skill을 세 에이전트에 설치하고 테스트

# Claude가 생성한 Skill 폴더를 적절한 경로에 배치
cp -r <generated-skill-folder> .claude/skills/fastapi-endpoint
cp -r <generated-skill-folder> .github/skills/fastapi-endpoint

추가 실습 C: 에이전트별 동작 차이 비교 실험

동일한 Skill을 세 에이전트에 넣고, 같은 프롬프트를 던져서 결과가 어떻게 다른지 비교합니다.

실험 설계

연습 2에서 만든 code-review Skill을 사용합니다. 임의의 Python 파일 하나를 준비합니다.

# test_target.py — 일부러 문제를 포함한 코드
import os
import sys
import json  # unused import

API_KEY = "sk-abc123xyz789"  # hardcoded secret

def proc(d, f=False):
    x = []
    for i in d:
        if f:
            if i['type'] == 'A':
                x.append(i['val'] * 1.0825)
            elif i['type'] == 'B':
                x.append(i['val'] * 1.05)
        else:
            x.append(i['val'])
    return x

세 에이전트에서 동일 프롬프트 실행

이 파일을 코드 리뷰해줘: test_target.py

비교 기록표 작성

| 비교 항목 | Claude Code | OpenCode | GitHub Copilot | |---|---|---|---| | Skill 자동 트리거 여부 | | | | | 리뷰 결과 포맷이 SKILL.md 지침을 따르는가 | | | | | 보안 이슈(하드코딩된 API_KEY) 발견 여부 | | | | | 미사용 import 감지 여부 | | | | | 네이밍 문제(proc, d, f, x, i) 지적 여부 | | | | | 매직 넘버(1.0825, 1.05) 지적 여부 | | | |

이 비교를 통해 각 에이전트가 Skill의 지침을 얼마나 충실히 따르는지 차이를 체감할 수 있고, description이나 본문을 에이전트별로 미세 조정해야 할 수도 있다는 점을 배웁니다.

추가 실습 D: OpenCode 권한 제어 실습

OpenCode에만 있는 Skill 권한 제어 기능을 실습합니다. 프로젝트 루트에 opencode.json을 만들어서 특정 Skill의 접근을 제어합니다.

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-summary": "ask",
      "nextjs-*": "allow"
    }
  }
}

이 설정에서 pr-summary Skill은 에이전트가 로드하려 할 때 사용자 승인을 요청하고, nextjs-로 시작하는 Skill은 자동 허용됩니다.

테스트: OpenCode에서 PR 요약을 요청했을 때 승인 프롬프트가 나타나는지, Next.js 관련 요청에서는 즉시 Skill이 로드되는지 확인합니다.

추가 실습 E: GitHub Copilot 고유 기능 — user-invokable / disable-model-invocation 조합 실험

GitHub Copilot(VS Code)에서는 Skill의 호출 방식을 세밀하게 제어할 수 있습니다. 네 가지 조합을 직접 만들어 차이를 체험합니다.

.github/skills/ 아래에 4개의 테스트 Skill을 만듭니다.

test-both-default (기본: 슬래시 명령 + 자동 트리거 모두 가능)

---
name: test-both-default
description: Test skill with default invocation settings. Use when user asks about "invocation test default".
---
This is the default behavior skill. Both slash command and auto-trigger work.

test-manual-only (수동 호출만 가능, 자동 트리거 안 됨)

---
name: test-manual-only
description: Test skill that only triggers manually. Use when user asks about "invocation test manual".
disable-model-invocation: true
---
This skill only responds to /test-manual-only slash command.

test-auto-only (자동 트리거만, 슬래시 메뉴에 안 보임)

---
name: test-auto-only
description: Test skill that auto-triggers but is hidden from menu. Use when user asks about "invocation test auto".
user-invokable: false
---
This skill loads automatically when relevant but is not in the / menu.

test-disabled (둘 다 비활성)

---
name: test-disabled
description: Test skill that is fully disabled.
disable-model-invocation: true
user-invokable: false
---
This skill should never activate.

실험: VS Code Copilot 채팅에서 /를 입력하여 슬래시 메뉴에 어떤 Skill이 나타나는지 확인합니다. 그리고 "invocation test default에 대해 알려줘"처럼 각 description의 키워드를 포함한 프롬프트를 던져 자동 트리거 여부를 확인합니다.

실습 3-3: 테스트 및 피드백 루프 — 체계적 방법

모든 연습이 끝난 후, 아래의 표준 테스트 프로세스를 모든 Skill에 적용합니다.

트리거 테스트

각 Skill마다 "트리거 되어야 할 프롬프트" 5개와 "트리거 되면 안 되는 프롬프트" 5개를 작성합니다.

# commit-message Skill
## Should trigger:
1. "커밋 메시지 만들어줘"
2. "이 변경사항을 커밋하고 싶어"
3. "git commit message for this change"
4. "컨벤셔널 커밋 형식으로 정리해줘"
5. "/commit-message 로그인 기능 추가"

## Should NOT trigger:
1. "이 코드를 리뷰해줘"
2. "새 컴포넌트를 만들어줘"
3. "API 엔드포인트를 설계해줘"
4. "테스트를 작성해줘"
5. "프로젝트 구조를 설명해줘"

세 에이전트 모두에서 10개 프롬프트를 실행하고 결과를 기록합니다. 90% 이상 정확하면 합격, 미달이면 description을 수정하고 재테스트합니다.

기능 테스트

Skill이 트리거된 후 출력이 지침을 따르는지 확인합니다. SKILL.md에서 정의한 형식, 규칙, 체크리스트가 결과물에 반영되었는지 3회 반복 실행하여 일관성을 봅니다.

스펙 검증

# Agent Skills 공식 검증 도구 사용
npx skills-ref validate .claude/skills/commit-message
npx skills-ref validate .claude/skills/code-review
npx skills-ref validate .claude/skills/api-design

피드백 반영 사이클

테스트 결과를 바탕으로 SKILL.md를 수정합니다. 수정 → 테스트 → 수정 → 테스트를 최소 3회 반복합니다. 이 반복 과정에서 "description의 키워드 한 단어 차이가 트리거 여부를 결정한다"는 감각이 생깁니다.

전체 실습 요약 및 체크리스트

| 실습 | 난이도 | 핵심 학습 포인트 | 완료 기준 | |---|---|---|---| | 3-1 과제 A~D | 분석 | 좋은 Skill의 패턴 인식 | 10개 항목 체크리스트 작성 완료 | | 연습 1: commit-message | 입문 | 프론트매터 규칙, 3개 에이전트 배포 | 3개 에이전트 모두에서 트리거 확인 | | 연습 2: code-review | 초급 | 지침 구체화, 출력 형식 제어 | 출력이 정의한 리뷰 포맷을 따름 | | 연습 3: api-design | 중급 | references/scripts 활용, Progressive Disclosure | 참조파일 로드와 스크립트 실행 확인 | | 연습 4: Skill 세트 3개 | 심화 | Scope 분리, 오버트리거링 방지 | 프롬프트별 정확히 1개 Skill만 트리거 | | 연습 5: pr-summary | 심화+ | context:fork, 동적 컨텍스트 주입 | Claude Code에서 서브에이전트 실행 확인 | | 추가 A: npx skills 설치 | 도구 | CLI 활용, 설치 구조 이해 | 커뮤니티 Skill 설치 및 구조 분석 완료 | | 추가 B: skill-creator | 도구 | AI에게 Skill 초안 생성 위임 | 생성된 Skill 검토 및 수정 완료 | | 추가 C: 에이전트별 비교 | 비교 | 동일 Skill의 에이전트별 동작 차이 | 비교 기록표 작성 완료 | | 추가 D: OpenCode 권한 | OpenCode 특화 | 권한 제어 (allow/deny/ask) | opencode.json 설정 및 승인 프롬프트 확인 | | 추가 E: Copilot 호출 제어 | Copilot 특화 | user-invokable, disable-model-invocation | 4가지 조합의 동작 차이 기록 |

연습 1부터 순서대로 진행하되, 각 연습을 완료할 때마다 3-3의 테스트 루프를 반드시 실행합니다. "만들고 끝"이 아니라 "만들고 → 테스트하고 → 고치고 → 다시 테스트"하는 사이클을 반복하는 것이 이 단계의 핵심입니다.

4단계: 생태계 활용과 지속 개선 — 실습 가이드

3단계에서 Skill을 만들고 테스트하는 법을 익혔다면, 4단계에서는 그 Skill을 공유하고, 커뮤니티에서 가져다 쓰고, 팀 단위로 관리하고, 계속 발전시키는 법을 배웁니다. 이 단계부터 Skill은 "개인의 메모"에서 "팀의 지식 자산"으로 성격이 바뀝니다.

실습 4-1: npx skills CLI 완전 정복

npx skills는 Vercel이 만든 오픈소스 CLI 도구로, Skill을 검색, 설치, 업데이트, 삭제하는 모든 작업을 하나의 명령 체계로 처리합니다. 40개 이상의 에이전트를 지원하며, 한 번의 명령으로 여러 에이전트에 동시 설치할 수 있습니다.

실습 A: 기본 명령어 7종 체험

실습용 프로젝트 디렉토리에서 각 명령을 직접 실행하고, 결과를 관찰합니다.

명령 1 — 저장소의 Skill 목록 조회 (설치하지 않고 보기만)

cd ~/skill-lab
npx skills add vercel-labs/agent-skills --list

이 명령은 해당 저장소에 있는 모든 Skill의 이름과 description을 보여줍니다. 어떤 Skill이 있는지 미리 파악할 때 사용합니다. 출력에서 각 Skill의 description이 어떤 패턴으로 작성되었는지 관찰하세요.

명령 2 — 특정 Skill을 세 에이전트에 동시 설치

npx skills add vercel-labs/agent-skills \
  --skill frontend-design \
  -a claude-code -a opencode -a github-copilot

설치 후 각 경로에 파일이 생성되었는지 확인합니다.

ls -la .claude/skills/frontend-design/SKILL.md
ls -la .agents/skills/frontend-design/SKILL.md  # opencode, github-copilot 공용

npx skills는 OpenCode와 GitHub Copilot의 경우 .agents/skills/ 경로를 사용합니다. 이 경로는 두 에이전트 모두 호환 경로로 인식합니다.

명령 3 — 설치된 Skill 목록 확인

npx skills list

에이전트별로 분류된 설치 목록이 출력됩니다. 전역 Skill과 프로젝트 Skill이 별도로 표시되는 점을 확인하세요.

# 전역 Skill만 보기
npx skills ls -g

# 특정 에이전트의 Skill만 보기
npx skills ls -a claude-code

명령 4 — 키워드로 Skill 검색

npx skills find typescript
npx skills find react
npx skills find python

키워드 없이 실행하면 대화형(fzf 스타일) 검색 인터페이스가 열립니다.

npx skills find

검색 결과에서 관심 있는 Skill을 바로 설치할 수 있습니다. 검색 결과의 Skill들을 살펴보면서 다양한 커뮤니티 Skill의 주제와 범위를 파악하세요.

명령 5 — Skill 업데이트 확인 및 실행

# 업데이트 가능한 Skill이 있는지 확인
npx skills check

# 모든 Skill을 최신 버전으로 업데이트
npx skills update

Skill은 원본 GitHub 저장소가 업데이트되면 새 버전을 받을 수 있습니다. 이 기능이 왜 중요한지 생각해보세요 — Skill도 코드처럼 지속적으로 개선됩니다.

명령 6 — Skill 삭제

# 대화형으로 삭제할 Skill 선택
npx skills remove

# 특정 Skill을 특정 에이전트에서만 삭제
npx skills remove frontend-design --agent claude-code

# 모든 에이전트에서 특정 Skill 삭제
npx skills remove frontend-design --agent '*'

명령 7 — 새 Skill 템플릿 생성

# 현재 디렉토리에 SKILL.md 템플릿 생성
npx skills init my-new-skill

이 명령은 기본 프론트매터와 본문 구조가 포함된 SKILL.md 파일을 자동 생성합니다. 새 Skill을 만들 때 빈 파일에서 시작하지 않고 이 템플릿에서 시작하면 규칙을 놓칠 확률이 줄어듭니다.

실습 B: 전역(Global) vs 프로젝트(Project) 설치 차이 체험

같은 Skill을 전역과 프로젝트 두 곳에 설치하고, 어떤 차이가 있는지 직접 확인합니다.

# 프로젝트 수준 설치 (기본값)
npx skills add anthropics/skills --skill skill-creator -a claude-code

# 전역 수준 설치
npx skills add anthropics/skills --skill skill-creator -a claude-code -g

# 프로젝트 수준 확인
ls .claude/skills/skill-creator/SKILL.md

# 전역 수준 확인
ls ~/.claude/skills/skill-creator/SKILL.md

프로젝트 수준 Skill은 해당 프로젝트 디렉토리에서만 작동하고, Git에 커밋하면 팀원도 사용할 수 있습니다. 전역 Skill은 어떤 프로젝트에서든 항상 사용 가능합니다. 이 차이를 실제로 다른 디렉토리로 이동하여 에이전트에서 Skill 목록을 확인해보면서 체감하세요.

# skill-lab 안에서
cd ~/skill-lab
claude
> What skills are available?
# → 프로젝트 Skill + 전역 Skill 모두 표시

# 다른 프로젝트에서
cd ~/other-project
claude
> What skills are available?
# → 전역 Skill만 표시

실습 C: Symlink vs Copy 설치 방식 이해

npx skills add를 대화형으로 실행하면 "Symlink" 또는 "Copy" 방식을 선택할 수 있습니다.

npx skills add vercel-labs/agent-skills --skill web-design-guidelines

Symlink(권장): 하나의 원본 파일을 여러 에이전트 경로에서 심볼릭 링크로 참조합니다. 원본을 수정하면 모든 에이전트에 즉시 반영됩니다. npx skills update가 이 방식에서 가장 잘 작동합니다.

Copy: 각 에이전트 경로에 독립적인 사본을 만듭니다. 심볼릭 링크가 지원되지 않는 환경(일부 Windows 설정)에서 사용합니다.

설치 후 확인합니다.

# symlink인지 확인
ls -la .claude/skills/web-design-guidelines/SKILL.md
# lrwxr-xr-x ... -> ../../.skills-cache/web-design-guidelines/SKILL.md 형태면 symlink

실습 4-2: 자신의 Skill을 GitHub에 공개하고 skills.sh에 등록하기

커뮤니티에서 Skill을 가져다 쓰기만 하는 것이 아니라, 자신이 만든 Skill을 공개하여 다른 사람이 npx skills add로 설치할 수 있게 합니다.

실습 D: Skill 공개 저장소 만들기

Step 1 — 저장소 구조 설계

3단계에서 만든 Skill 중 범용적인 것을 골라 공개 저장소를 만듭니다. 예를 들어 commit-message와 code-review Skill을 공개한다고 가정합니다.

mkdir ~/my-agent-skills && cd ~/my-agent-skills
git init

저장소 구조를 npx skills가 인식하는 표준 형식으로 구성합니다.

my-agent-skills/
├── README.md                          ← 사람을 위한 저장소 소개 (Skill 폴더 안이 아닌 최상위)
├── skills/
│   ├── commit-message/
│   │   └── SKILL.md
│   └── code-review/
│       └── SKILL.md

npx skills CLI는 skills/ 디렉토리를 자동으로 탐색하므로 이 구조를 따르면 별도 설정 없이 발견됩니다.

Step 2 — README.md 작성

저장소 최상위 README.md는 사람이 읽는 문서입니다. Skill 폴더 안에는 README.md를 넣지 않는다는 규칙을 기억하세요.

# My Agent Skills

Reusable AI agent skills for code quality and workflow automation.

## Available Skills

| Skill | Description |
|---|---|
| `commit-message` | Generate conventional commit messages |
| `code-review` | Structured code review with security and performance checks |

## Installation

```bash
# Install all skills to Claude Code, OpenCode, and GitHub Copilot
npx skills add <your-github-id>/my-agent-skills \
  -a claude-code -a opencode -a github-copilot

# Install a specific skill
npx skills add <your-github-id>/my-agent-skills --skill commit-message

License

MIT


**Step 3 — Skill 파일 복사 및 정리**

```bash
mkdir -p skills/commit-message skills/code-review

# 3단계에서 만든 파일 복사
cp ~/skill-lab/.claude/skills/commit-message/SKILL.md skills/commit-message/SKILL.md
cp ~/skill-lab/.claude/skills/code-review/SKILL.md skills/code-review/SKILL.md

Step 4 — 스펙 검증

npx skills-ref validate skills/commit-message
npx skills-ref validate skills/code-review

Step 5 — GitHub에 push

git add .
git commit -m "feat: initial release of commit-message and code-review skills"
git remote add origin https://github.com/<your-github-id>/my-agent-skills.git
git push -u origin main

Step 6 — 자신의 저장소에서 설치 테스트

cd ~/skill-lab

# 자기 저장소에서 설치 테스트
npx skills add <your-github-id>/my-agent-skills --list
npx skills add <your-github-id>/my-agent-skills --skill commit-message -a claude-code

이것이 작동하면, 전 세계 누구든 같은 명령으로 여러분의 Skill을 설치할 수 있습니다.

Step 7 — skills.sh 인덱싱

skills.sh는 공개 GitHub 저장소에 있는 Skill을 자동으로 인덱싱합니다. 저장소가 public이고 SKILL.md가 표준 형식을 따르면, 시간이 지나면서 skills.sh 검색 결과에 나타나게 됩니다. npx skills find 검색에도 발견됩니다. 저장소 설명(About)에 "agent-skills"라는 태그를 추가하면 발견 가능성이 높아집니다.

실습 4-3: 커뮤니티 리소스 탐색 루틴 만들기

실습 E: 주간 Skill 탐색 루틴

매주 한 번, 약 30분 동안 다음 순서로 새로운 Skill과 패턴을 탐색하는 루틴을 만듭니다.

Step 1 — skills.sh 트렌딩 확인 (10분)

브라우저에서 https://skills.sh 에 접속합니다. Trending (24h) 탭과 Hot 탭을 확인합니다. 지난주에 없던 새로운 Skill이 있는지, 어떤 주제가 부상하고 있는지 파악합니다.

관찰 노트를 작성하세요.

## 2026-02-20 주간 Skill 탐색

### 트렌딩 관찰
- [Skill 이름]: [한줄 설명] — [내 프로젝트에 적용 가능 여부]
- [Skill 이름]: [한줄 설명] — [description 작성에서 배울 점]

### 새로 발견한 패턴
- [예: scripts/ 안에 Python 린터를 넣는 패턴이 늘고 있음]

Step 2 — 관심 Skill 설치 및 SKILL.md 분석 (10분)

트렌딩에서 관심 있는 Skill 1~2개를 골라 설치하고 내용을 읽습니다.

npx skills add <owner>/<repo> --skill <skill-name> -a claude-code -a opencode -a github-copilot

# 설치된 SKILL.md 내용 확인
cat .claude/skills/<skill-name>/SKILL.md

3단계에서 만든 자기 체크리스트로 이 Skill을 평가합니다. 특히 자신의 Skill에 없는 좋은 패턴이 있으면 메모합니다.

Step 3 — Reddit/GitHub 커뮤니티 확인 (10분)

다음 경로를 확인합니다.

https://www.reddit.com/r/ClaudeCode — "skill" 키워드로 검색
https://www.reddit.com/r/vibecoding — Skill 관련 토론
https://github.com/heilcheng/awesome-agent-skills — 새로 추가된 Skill 확인

유용한 토론이나 팁을 발견하면 자기 Skill 개선에 반영합니다.

실습 F: awesome-agent-skills 저장소 활용

git clone https://github.com/heilcheng/awesome-agent-skills.git ~/study/awesome-agent-skills
cd ~/study/awesome-agent-skills

이 저장소는 카테고리별로 정리된 Skill 큐레이션입니다. README를 읽으며 현재 생태계에 어떤 종류의 Skill이 있는지 전체 지도를 그립니다. 자신의 전문 분야에서 아직 Skill이 없는 빈 영역을 발견하면, 그것이 자신이 만들어서 기여할 Skill의 후보가 됩니다.

실습 4-4: Skill의 버전 관리와 팀 공유

Skill도 코드와 마찬가지로 버전 관리, 코드 리뷰, 점진적 개선이 필요합니다.

실습 G: Git 기반 Skill 버전 관리

Step 1 — metadata에 version 추가

3단계에서 만든 모든 Skill의 프론트매터에 metadata.version을 추가합니다.

---
name: code-review
description: ...
metadata:
  author: your-name
  version: "1.0.0"
---

Step 2 — 변경 이력을 커밋 메시지로 추적

Skill을 수정할 때마다 의미 있는 커밋 메시지를 남깁니다.

# description 키워드 추가
git add .claude/skills/code-review/SKILL.md
git commit -m "fix(code-review): add Korean trigger keywords to description"

# 새 검사 항목 추가
git commit -m "feat(code-review): add accessibility check section"

# version bump
git commit -m "chore(code-review): bump version to 1.1.0"

Step 3 — 변경 기록 확인

git log --oneline -- .claude/skills/code-review/SKILL.md

이 이력을 통해 "왜 description을 이렇게 바꿨는지", "어떤 트리거 키워드를 추가했는지" 등을 추적할 수 있습니다.

실습 H: 팀 공유 워크플로우 시뮬레이션

혼자 실습하더라도 "팀원이 있다고 가정"하고 다음 과정을 진행합니다.

Step 1 — Skill을 프로젝트에 커밋

cd ~/skill-lab
git add .claude/skills/ .github/skills/
git commit -m "feat: add project skills for code-review and commit-message"
git push

프로젝트 수준의 .claude/skills/와 .github/skills/를 Git에 커밋하면, 저장소를 clone하는 모든 팀원이 동일한 Skill을 자동으로 사용합니다.

Step 2 — Pull Request로 Skill 변경 리뷰

Skill을 수정할 때 직접 main 브랜치에 푸시하지 않고, PR을 만듭니다.

git checkout -b improve/code-review-skill

# SKILL.md 수정
nano .claude/skills/code-review/SKILL.md

git add .
git commit -m "feat(code-review): add memory leak detection checklist"
git push origin improve/code-review-skill
# → GitHub에서 PR 생성

PR 설명에 "이 Skill 변경의 이유"와 "테스트 결과"를 기록합니다. 코드 리뷰처럼 Skill 리뷰를 받는 습관을 만듭니다.

Step 3 — 팀 Skill 가이드라인 문서 작성

프로젝트 루트에 SKILLS-GUIDE.md를 만들어 팀의 Skill 관리 규칙을 정합니다.

# Team Skills Guide

## Our Skills

| Skill | Owner | Version | Last Updated |
|---|---|---|---|
| commit-message | @your-name | 1.0.0 | 2026-02-15 |
| code-review | @your-name | 1.1.0 | 2026-02-20 |
| nextjs-component | @teammate | 1.0.0 | 2026-02-18 |

## Rules
1. Every Skill change goes through PR review
2. description 변경 시 반드시 트리거 테스트 결과를 PR에 첨부
3. version은 Semantic Versioning을 따름
   - 트리거 키워드 추가/수정: patch (1.0.1)
   - 새 섹션 추가: minor (1.1.0)
   - 구조적 변경: major (2.0.0)
4. 하나의 Skill이 200줄을 넘으면 분리를 검토

실습 4-5: Skill 지속 개선 — 반복 실험

실습 I: description A/B 테스트

하나의 Skill에 대해 description을 두 가지 버전으로 만들어 어떤 것이 더 정확하게 트리거되는지 비교합니다.

버전 A (간결형)

description: Code review for pull requests. Use when reviewing code or PRs.

버전 B (키워드 풍부형)

description: Perform structured code review on files or pull requests. Checks code quality, security vulnerabilities, performance issues, and naming conventions. Use when user asks for "code review", "리뷰", "PR review", "코드 검토", "피드백", or wants feedback on code changes.

각 버전으로 다음 10개 프롬프트를 세 에이전트에서 테스트하고 트리거 성공률을 기록합니다.

1. "이 코드를 리뷰해줘"
2. "PR을 검토해줘"
3. "이 변경사항에 대한 피드백 줘"
4. "코드 품질을 확인해줘"
5. "보안 문제가 있는지 봐줘"
6. "이 함수 괜찮아 보여?"
7. "Code review please"
8. "Review this PR"
9. "이 파일 개선할 점이 있어?"
10. "커밋하기 전에 확인해줘"

| 프롬프트 | 버전 A (Claude Code) | 버전 A (OpenCode) | 버전 A (Copilot) | 버전 B (Claude Code) | 버전 B (OpenCode) | 버전 B (Copilot) | |---|---|---|---|---|---|---| | 1 | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ | | ... | | | | | | |

이 실험을 통해 description의 구체성이 트리거 정확도에 얼마나 영향을 미치는지 정량적으로 확인할 수 있습니다.

실습 J: Skill 분리 리팩토링

3단계 연습 4에서 만든 nextjs-component Skill이 시간이 지나면서 점점 커졌다고 가정합니다. 150줄이 넘어가면 분리를 검토해야 합니다.

Before: 하나의 비대한 Skill

nextjs-component/
└── SKILL.md  (200줄 — 컴포넌트 작성 + 스타일링 + 접근성 + 상태관리 규칙이 모두 포함)

After: 역할별 분리

nextjs-component/
└── SKILL.md  (80줄 — 컴포넌트 작성 핵심 규칙만)

nextjs-styling/
└── SKILL.md  (60줄 — Tailwind CSS 스타일링 규칙)

nextjs-a11y/
└── SKILL.md  (50줄 — 접근성 체크리스트)

분리 후 각 Skill의 description이 겹치지 않는지 테스트하고, 기존에 트리거되던 프롬프트가 여전히 올바른 Skill에 매칭되는지 확인합니다.

실습 K: 에이전트에게 Skill 개선 요청하기

Anthropic의 Best Practice 중 "Claude는 자기 자신의 지침을 개선하는 데 뛰어나다"라는 점을 활용합니다.

# Claude Code에서
claude

> 현재 code-review Skill을 읽고, 아래 관점에서 개선점을 제안해줘:
> 1. description이 트리거 키워드를 충분히 포함하는가
> 2. 본문의 지침이 모호하지 않은가
> 3. 예시가 충분한가
> 4. Progressive Disclosure 원칙에 맞게 분리되어 있는가
>
> 현재 Skill 파일: .claude/skills/code-review/SKILL.md

Claude의 제안을 검토한 뒤, 타당한 부분만 반영합니다. 모든 제안을 무비판적으로 수용하지 말고, 자신의 체크리스트와 대조하여 판단합니다.

동일한 요청을 OpenCode와 VS Code Copilot에서도 해보면, 각 에이전트가 Skill을 어떤 관점에서 평가하는지 비교할 수 있습니다.

추가 실습 과제

추가 실습 L: 도메인 특화 Skill 팩 만들기

자신의 전문 분야에 맞는 Skill 3~5개를 하나의 저장소로 묶어 "Skill 팩"을 만듭니다.

예를 들어 "Python 백엔드 Skill 팩":

python-backend-skills/
├── README.md
├── skills/
│   ├── fastapi-endpoint/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   └── pydantic-patterns.md
│   │   └── scripts/
│   │       └── generate-openapi.sh
│   ├── sqlalchemy-model/
│   │   └── SKILL.md
│   ├── pytest-testing/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── fixture-patterns.md
│   ├── docker-deploy/
│   │   └── SKILL.md
│   └── python-logging/
│       └── SKILL.md

각 Skill을 작성한 뒤, 다음 시나리오로 "팩 전체의 통합 테스트"를 합니다.

# 시나리오: 새 기능 개발 전체 흐름
1. "User 모델을 만들어줘" → sqlalchemy-model 트리거
2. "User CRUD API를 만들어줘" → fastapi-endpoint 트리거
3. "API 테스트를 작성해줘" → pytest-testing 트리거
4. "Docker로 배포 설정해줘" → docker-deploy 트리거
5. "로깅을 추가해줘" → python-logging 트리거

하나의 개발 흐름에서 다섯 개 Skill이 순차적으로 각자의 역할에만 트리거되는지 확인합니다.

추가 실습 M: 다른 사람의 Skill에 기여하기 (Open Source Contribution)

커뮤니티 Skill 저장소에 직접 기여하는 연습을 합니다.

Step 1 — 기여할 저장소 선택

skills.sh에서 자주 사용하는 Skill 중 개선할 점이 있는 것을 골라 Fork합니다.

# 예: clean-code-skills에 기여
gh repo fork ertugrul-dmr/clean-code-skills
cd clean-code-skills

Step 2 — 개선 작업

예를 들어 기존 Skill에 한국어 트리거 키워드를 추가하거나, 누락된 예시를 보충하거나, 새로운 카테고리의 Skill을 추가합니다.

git checkout -b feat/add-korean-triggers
# SKILL.md 수정
git commit -m "feat: add Korean trigger keywords to clean-comments skill"
git push origin feat/add-korean-triggers
# → GitHub에서 원본 저장소로 PR 생성

Step 3 — PR 설명 작성

## What changed
Added Korean trigger keywords to the `clean-comments` skill description.

## Why
Korean-speaking developers should be able to trigger this skill with natural Korean phrases like "주석", "코멘트", "문서화".

## Testing
Tested with Claude Code, OpenCode, and GitHub Copilot.
- "주석 정리해줘" → ✅ triggers clean-comments
- "불필요한 코멘트 삭제해줘" → ✅ triggers clean-comments

추가 실습 N: OpenCode 고급 설정 — 에이전트별 Skill 권한 분리

OpenCode에서는 에이전트(plan, code 등)마다 다른 Skill 접근 권한을 설정할 수 있습니다. 이를 활용해 "계획 단계에서는 읽기 전용 Skill만, 구현 단계에서는 모든 Skill 허용"하는 워크플로우를 만듭니다.

프로젝트 루트에 opencode.json을 작성합니다.

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "code-review": "allow",
          "api-design": "allow",
          "commit-message": "deny",
          "docker-deploy": "deny"
        }
      }
    },
    "code": {
      "permission": {
        "skill": {
          "*": "allow"
        }
      }
    }
  }
}

이 설정에서 plan 에이전트는 코드 리뷰와 API 설계 Skill은 사용할 수 있지만, 커밋이나 배포 같은 실행 Skill은 차단됩니다. code 에이전트는 모든 Skill을 사용할 수 있습니다.

테스트: OpenCode에서 plan 모드와 code 모드를 전환하며 각 Skill의 접근 가능 여부가 달라지는지 확인합니다.

추가 실습 O: GitHub Copilot 전용 — VS Code Extension에서 Skill 배포

GitHub Copilot은 VS Code Extension을 통해 Skill을 배포할 수 있습니다. Extension의 package.json에 chatSkills를 등록하면 됩니다.

Step 1 — 간단한 Extension 프로젝트 생성

mkdir my-skill-extension && cd my-skill-extension
npm init -y
mkdir -p skills/commit-message
cp ~/skill-lab/.claude/skills/commit-message/SKILL.md skills/commit-message/SKILL.md

Step 2 — package.json에 chatSkills 등록

{
  "name": "my-skill-extension",
  "version": "1.0.0",
  "contributes": {
    "chatSkills": [
      {
        "path": "./skills/commit-message"
      }
    ]
  }
}

Step 3 — VS Code에서 로컬 Extension 테스트

VS Code Extension 개발 환경에서 F5를 눌러 디버그 모드로 실행하면, Copilot 채팅에서 해당 Skill이 나타나는지 확인할 수 있습니다.

이 패턴은 팀 전체에 Skill을 배포할 때 유용합니다. Extension을 VS Code Marketplace에 게시하면 팀원이 Extension 설치만으로 모든 Skill을 받을 수 있습니다.

추가 실습 P: Skill 성과 측정 대시보드 만들기

Skill이 실제로 얼마나 도움이 되는지 측정하는 간단한 기록 시스템을 만듭니다.

SKILLS-METRICS.md 파일을 프로젝트에 만들고 매주 업데이트합니다.

# Skills Performance Metrics

## Week of 2026-02-17

### commit-message
- Times triggered: 23
- Times manually invoked: 5
- Times auto-triggered correctly: 18
- False triggers: 0
- User corrections needed: 2
- Satisfaction: 9/10

### code-review
- Times triggered: 12
- Times manually invoked: 3
- Times auto-triggered correctly: 8
- False triggers: 1 (triggered on "이 코드 설명해줘" — should not have)
- User corrections needed: 4
- Satisfaction: 7/10
- Action: description에서 "코드" 단독 키워드를 제거하고 "코드 리뷰", "코드 검토"로 구체화

### Improvements Made This Week
- code-review: description에 부정 트리거 추가 ("Do NOT use for code explanation")
- commit-message: body 섹션에 Breaking Change footer 예시 추가

이 기록을 4주간 누적하면, 어떤 Skill이 잘 작동하고 어떤 Skill이 개선이 필요한지, description 수정이 트리거 정확도에 어떤 영향을 미쳤는지 데이터로 확인할 수 있습니다.

전체 실습 요약

| 실습 | 핵심 학습 포인트 | 완료 기준 | |---|---|---| | A: CLI 기본 명령 7종 | add, list, find, check, update, remove, init | 모든 명령을 한 번씩 실행하고 결과 확인 | | B: 전역 vs 프로젝트 | 설치 범위의 차이, 다른 디렉토리에서의 동작 | 다른 프로젝트에서 전역 Skill만 보이는 것 확인 | | C: Symlink vs Copy | 설치 방식의 차이, 업데이트 동작 | symlink 확인 명령 실행 | | D: Skill 공개 저장소 | 저장소 구조, README 작성, npx skills 호환성 | 자기 저장소에서 npx skills add 성공 | | E: 주간 탐색 루틴 | 트렌딩 파악, 커뮤니티 동향 추적 | 첫 주간 탐색 노트 작성 | | F: awesome-agent-skills | 생태계 전체 지도 파악, 기여 후보 발굴 | 빈 영역 1개 이상 식별 | | G: Git 버전 관리 | metadata version, 의미 있는 커밋 메시지 | 3회 이상 Skill 수정 커밋 이력 | | H: 팀 공유 워크플로우 | PR 기반 Skill 리뷰, SKILLS-GUIDE.md | 가이드 문서 작성 완료 | | I: description A/B 테스트 | 구체성이 트리거 정확도에 미치는 영향 | 두 버전의 비교 결과표 작성 | | J: Skill 분리 리팩토링 | 비대해진 Skill의 분리 기준과 방법 | 분리 후 트리거 정확도 유지 확인 | | K: 에이전트에게 개선 요청 | AI를 활용한 Skill 메타 개선 | 3개 에이전트의 개선 제안 비교 | | L: 도메인 Skill 팩 | 여러 Skill의 통합 설계와 scope 관리 | 연속 시나리오에서 5개 Skill 순차 트리거 성공 | | M: 오픈소스 기여 | 커뮤니티 PR 작성, 테스트 결과 첨부 | PR 1개 이상 제출 | | N: OpenCode 에이전트별 권한 | plan/code 모드별 Skill 접근 분리 | opencode.json 설정 후 모드별 동작 확인 | | O: Copilot Extension 배포 | chatSkills 기반 Skill 배포 | 로컬 Extension에서 Skill 표시 확인 | | P: 성과 측정 | 트리거 정확도, 유저 수정 횟수 추적 | 4주간 SKILLS-METRICS.md 누적 |

4단계는 "한 번 하고 끝"이 아니라 지속적으로 반복하는 단계입니다. 실습 E의 주간 탐색 루틴과 실습 P의 성과 측정을 매주 습관으로 유지하면, Skill 작성 능력이 매주 조금씩 향상됩니다. 특히 description A/B 테스트(실습 I)를 반복하면서 "이 키워드 하나가 트리거를 결정한다"는 감각이 쌓이는 것이 이 단계의 가장 중요한 성과입니다.

사례: 스킬 크리에이터 (Skill Creator)

새로운 스킬을 만들고 반복적으로 개선하기 위한 스킬입니다.

스킬 생성 과정을 대략적으로 설명하면 다음과 같습니다:

스킬이 무엇을 해야 하는지, 어떻게 동작해야 하는지 결정하기
스킬 초안 작성하기
몇 가지 테스트 프롬프트를 만들고, '스킬이 탑재된 Claude'로 실행해보기
사용자가 결과를 정성적·정량적으로 평가할 수 있도록 돕기
- 실행이 백그라운드에서 진행되는 동안, 정량적 평가(evals)가 없다면 초안을 작성합니다(이미 있다면 그대로 사용하거나, 변경이 필요하다면 수정). 그런 다음 사용자에게 설명합니다(이미 존재하는 경우 기존 항목들을 설명).
- eval-viewer/generate_review.py 스크립트를 사용하여 사용자가 결과를 확인하고 정량적 지표도 살펴볼 수 있도록 합니다.
사용자의 평가 결과 피드백을 바탕으로 스킬을 재작성합니다(정량적 벤치마크에서 명백한 결함이 발견된 경우도 포함).
만족할 때까지 반복합니다.
테스트 세트를 확장하고 더 큰 규모로 다시 시도합니다.

이 스킬을 사용할 때 여러분의 역할은 사용자가 이 과정의 어느 단계에 있는지 파악하고, 단계를 진행할 수 있도록 도와주는 것입니다. 예를 들어 사용자가 "X를 위한 스킬을 만들고 싶어요"라고 하면, 무슨 의미인지 좁혀나가고, 초안을 작성하고, 테스트 케이스를 작성하고, 어떻게 평가할지 결정하고, 모든 프롬프트를 실행하고, 반복하는 것을 도울 수 있습니다.

반대로 사용자가 이미 스킬 초안을 가지고 있다면, 바로 평가/반복 루프 단계로 넘어갈 수 있습니다.

물론 항상 유연하게 대응해야 하며, 사용자가 "많은 평가는 필요 없어요, 그냥 같이 느낌으로 해봐요"라고 하면 그렇게 해도 됩니다.

스킬이 완성된 이후(순서는 유연하게 조정 가능), 스킬 설명 개선기(skill description improver)를 실행하여 스킬 트리거링을 최적화할 수도 있습니다. 이를 위한 별도 스크립트가 있습니다.

좋죠? 좋습니다.

사용자와의 소통:

스킬 크리에이터는 코딩 용어에 대한 친숙도가 매우 다양한 사람들이 사용할 수 있습니다. 최근 Claude의 강력함에 영감을 받아 배관공이 터미널을 열고, 부모님과 조부모님들이 "npm 설치 방법"을 검색하는 추세가 생겼습니다. 반면 대부분의 사용자는 꽤 컴퓨터에 익숙한 편입니다.

따라서 맥락 단서에 주의를 기울여 소통 방식을 조절해 주세요! 기본적인 기준을 예시로 들면:

"평가(evaluation)"와 "벤치마크(benchmark)"는 경계선에 있지만 사용 가능합니다.
"JSON"과 "assertion"은 사용자가 이를 알고 있다는 명확한 단서가 보일 때만 설명 없이 사용하세요.

확신이 없을 때는 용어를 간략히 설명해도 됩니다. 사용자가 이해할지 모르겠다면 짧은 정의와 함께 용어를 사용하세요.

스킬 만들기:

의도 파악:

사용자의 의도를 먼저 이해합니다. 현재 대화에 이미 사용자가 캡처하고 싶은 워크플로우가 포함되어 있을 수 있습니다(예: "이걸 스킬로 만들어줘"). 그렇다면 먼저 대화 히스토리에서 사용된 도구, 단계 순서, 사용자가 한 수정, 입출력 형식 등을 추출합니다. 사용자가 빠진 부분을 채워야 할 수도 있으며, 다음 단계로 넘어가기 전에 확인을 받아야 합니다.

이 스킬이 Claude가 무엇을 할 수 있게 해야 하는가?
이 스킬은 언제 트리거되어야 하는가? (어떤 사용자 표현/맥락에서)
예상 출력 형식은 무엇인가?
스킬이 잘 동작하는지 확인하기 위한 테스트 케이스를 설정해야 하는가? 객관적으로 검증 가능한 출력(파일 변환, 데이터 추출, 코드 생성, 고정 워크플로우)을 가진 스킬은 테스트 케이스가 도움이 됩니다. 주관적 출력(글쓰기 스타일, 예술)을 가진 스킬은 보통 테스트 케이스가 필요 없습니다. 스킬 유형에 맞는 기본값을 제안하되 사용자가 결정하도록 합니다.

인터뷰 및 리서치:

엣지 케이스, 입출력 형식, 예시 파일, 성공 기준, 의존성에 대해 사전에 적극적으로 질문합니다. 이 부분이 정리될 때까지 테스트 프롬프트 작성을 미룹니다.

사용 가능한 MCP를 확인합니다. 리서치에 유용하다면(문서 검색, 유사 스킬 찾기, 모범 사례 조회), 서브에이전트를 통해 병렬로 리서치하거나(가능한 경우), 아니면 인라인으로 진행합니다. 사용자의 부담을 줄이기 위해 충분한 맥락을 갖추고 준비합니다.

SKILL.md 작성:

사용자 인터뷰를 바탕으로 다음 구성 요소를 채웁니다:

name: 스킬 식별자
description: 트리거 시점과 기능. 이것이 주요 트리거 메커니즘입니다. 스킬이 무엇을 하는지와 언제 사용하는지의 구체적인 맥락을 모두 포함합니다. "언제 사용할지"에 관한 모든 정보는 본문이 아닌 여기에 넣습니다. 참고: 현재 Claude는 스킬을 "과소 트리거"하는 경향이 있습니다. 즉, 유용할 때도 사용하지 않는 경향이 있습니다. 이를 방지하기 위해 스킬 설명을 약간 "적극적(pushy)"으로 작성하세요. 예를 들어 "내부 Anthropic 데이터를 표시하기 위한 간단하고 빠른 대시보드 만드는 방법" 대신 "내부 Anthropic 데이터를 표시하기 위한 간단하고 빠른 대시보드 만드는 방법. 사용자가 대시보드, 데이터 시각화, 내부 지표, 또는 어떤 형태의 회사 데이터 표시를 언급할 때마다 이 스킬을 사용하세요. 명시적으로 '대시보드'를 요청하지 않더라도 마찬가지입니다."라고 작성합니다.
compatibility: 필요한 도구, 의존성 (선택 사항, 거의 필요 없음)
스킬의 나머지 내용 :)

스킬 작성 가이드:

스킬의 구조:

skill-name/
├── SKILL.md (필수)
│   ├── YAML 프론트매터 (name, description 필수)
│   └── 마크다운 지침
└── 번들 리소스 (선택)
    ├── scripts/    - 결정론적/반복적 작업을 위한 실행 코드
    ├── references/ - 필요에 따라 컨텍스트에 로드되는 문서
    └── assets/     - 출력에 사용되는 파일 (템플릿, 아이콘, 폰트)

점진적 공개 (Progressive Disclosure):

스킬은 세 단계 로딩 시스템을 사용합니다:

메타데이터 (name + description) — 항상 컨텍스트에 있음 (~100 단어)
SKILL.md 본문 — 스킬이 트리거될 때마다 컨텍스트에 있음 (이상적으로는 500줄 미만)
번들 리소스 — 필요에 따라 (무제한, 스크립트는 로드 없이 실행 가능)

이 단어 수는 근사치이며, 필요하다면 더 길게 작성해도 됩니다.

주요 패턴:

SKILL.md를 500줄 미만으로 유지합니다. 이 한계에 가까워지면 추가적인 계층 구조를 추가하고, 스킬을 사용하는 모델이 다음에 어디로 가야 하는지 명확한 포인터를 제공합니다.
SKILL.md에서 파일을 명확하게 참조하고, 언제 읽어야 하는지 안내합니다.
대형 참조 파일(300줄 초과)의 경우 목차를 포함합니다.

도메인 구성: 스킬이 여러 도메인/프레임워크를 지원하는 경우, 변형별로 구성합니다:

cloud-deploy/
├── SKILL.md (워크플로우 + 선택)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude는 관련 참조 파일만 읽습니다.

놀람 없음의 원칙 (Principle of Lack of Surprise):

당연한 말이지만, 스킬에는 맬웨어, 익스플로잇 코드, 시스템 보안을 침해할 수 있는 어떤 내용도 포함되어서는 안 됩니다. 스킬의 내용은 설명되었을 때 사용자를 의도적으로 놀라게 해서는 안 됩니다. 오해를 유발하는 스킬이나 무단 접근, 데이터 유출 또는 기타 악의적 활동을 조장하는 스킬 생성 요청에 응해서는 안 됩니다. 단, "XYZ로 롤플레이" 같은 것들은 괜찮습니다.

작성 패턴:

지침에서는 명령형을 사용하는 것을 권장합니다.

출력 형식 정의 — 예시:

## 보고서 구조
항상 이 정확한 템플릿을 사용하세요:
# [제목]
## 요약
## 주요 발견사항
## 권고사항

예시 패턴 — 예시를 포함하는 것이 유용합니다. 다음과 같이 형식을 지정할 수 있습니다("입력"과 "출력"이 예시에 포함된 경우 약간 변형할 수 있습니다):

## 커밋 메시지 형식
**예시 1:**
입력: JWT 토큰으로 사용자 인증 추가
출력: feat(auth): implement JWT-based authentication

작성 스타일:

모델에게 요청하는 것들의 이유를 가능하면 설명하려고 노력합니다. ALWAYS나 NEVER를 대문자로 쓰거나 매우 경직된 구조를 사용하는 것은 노란 신호입니다. 가능하면 논리를 재구성하고 이유를 설명하여 모델이 왜 그 행동이 중요한지 이해하도록 합니다. 이것이 더 인간적이고 강력하며 효과적인 접근입니다.

테스트 케이스:

스킬 초안을 작성한 후, 실제 사용자가 실제로 입력할 만한 현실적인 테스트 프롬프트 2~3개를 만듭니다. 사용자와 공유합니다: [정확히 이 표현을 쓸 필요는 없음] "시도해보고 싶은 테스트 케이스 몇 개입니다. 맞아 보이나요, 아니면 추가하고 싶은 게 있나요?" 그런 다음 실행합니다.

테스트 케이스는 evals/evals.json에 저장합니다. 아직 assertion을 작성하지 마세요 — 프롬프트만 저장합니다. assertion은 다음 단계에서 실행이 진행되는 동안 작성할 것입니다.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "사용자의 태스크 프롬프트",
      "expected_output": "예상 결과에 대한 설명",
      "files": []
    }
  ]
}

전체 스키마(나중에 추가할 assertions 필드 포함)는 references/schemas.md를 참조하세요.

테스트 케이스 실행 및 평가:

이 섹션은 하나의 연속적인 시퀀스입니다 — 중간에 멈추지 마세요. /skill-test 또는 다른 테스트 스킬을 사용하지 마세요.

결과는 스킬 디렉토리와 나란히 <skill-name>-workspace/에 저장합니다. 워크스페이스 내에서는 반복(iteration)별로 결과를 구성하고(iteration-1/, iteration-2/ 등), 그 안에서 각 테스트 케이스는 별도 디렉토리를 갖습니다(eval-0/, eval-1/ 등). 모두 미리 만들지 말고, 진행하면서 디렉토리를 생성합니다.

1단계: 같은 턴에 모든 실행 생성 (스킬 포함 AND 베이스라인)

각 테스트 케이스마다 같은 턴에 두 개의 서브에이전트를 생성합니다 — 하나는 스킬 포함, 하나는 포함 없이. 중요한 점: 스킬 포함 실행을 먼저 생성하고 나중에 베이스라인을 추가하지 마세요. 모든 것이 비슷한 시간에 완료되도록 한 번에 실행하세요.

스킬 포함 실행:

이 작업을 실행합니다:
- 스킬 경로: <path-to-skill>
- 작업: <eval prompt>
- 입력 파일: <eval files if any, or "none">
- 출력 저장 경로: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- 저장할 출력물: <사용자가 원하는 것 — 예: ".docx 파일", "최종 CSV">

베이스라인 실행 (같은 프롬프트, 단 베이스라인은 맥락에 따라 다름):

새 스킬 생성 시: 스킬 없음. 같은 프롬프트, 스킬 경로 없음, without_skill/outputs/에 저장.
기존 스킬 개선 시: 이전 버전 사용. 편집 전에 스킬 스냅샷(cp -r <skill-path> <workspace>/skill-snapshot/)을 찍고, 베이스라인 서브에이전트가 스냅샷을 참조하도록 합니다. old_skill/outputs/에 저장.

각 테스트 케이스에 대해 eval_metadata.json을 작성합니다(assertion은 지금은 비워도 됩니다). 각 eval에는 무엇을 테스트하는지 설명하는 이름을 부여합니다 — "eval-0"과 같은 이름은 피합니다. 이 이름을 디렉토리 이름으로도 사용합니다. 이번 반복에 새로운 또는 수정된 eval 프롬프트가 사용된다면, 새 eval 디렉토리마다 이 파일을 생성합니다.

{
  "eval_id": 0,
  "eval_name": "여기에 설명적인 이름",
  "prompt": "사용자의 태스크 프롬프트",
  "assertions": []
}

2단계: 실행 중에 assertion 초안 작성

실행이 완료될 때까지 그냥 기다리지 마세요 — 이 시간을 생산적으로 활용할 수 있습니다. 각 테스트 케이스에 대한 정량적 assertion을 초안 작성하고 사용자에게 설명합니다. evals/evals.json에 이미 assertion이 있다면 검토하고 무엇을 확인하는지 설명합니다.

좋은 assertion은 객관적으로 검증 가능하고 설명적인 이름을 가집니다. 벤치마크 뷰어에서 한눈에 읽어도 각 항목이 무엇을 확인하는지 바로 이해할 수 있어야 합니다. 주관적인 스킬(글쓰기 스타일, 디자인 품질)은 정성적 평가가 더 적합합니다 — 사람의 판단이 필요한 것에 assertion을 억지로 붙이지 마세요.

초안이 완료되면 eval_metadata.json 파일과 evals/evals.json을 assertion으로 업데이트합니다. 정성적 출력과 정량적 벤치마크 모두 뷰어에서 어떻게 보일지 사용자에게 설명합니다.

3단계: 실행이 완료되면 타이밍 데이터 저장

각 서브에이전트 작업이 완료되면 total_tokens와 duration_ms를 포함하는 알림을 받습니다. 이 데이터를 즉시 실행 디렉토리의 timing.json에 저장합니다:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

이 데이터를 저장할 수 있는 유일한 기회입니다 — 작업 알림을 통해 전달되며 다른 곳에는 저장되지 않습니다. 일괄 처리하려 하지 말고 각 알림이 도착하는 즉시 처리합니다.

4단계: 채점, 집계, 뷰어 실행

모든 실행이 완료되면:

각 실행 채점 — 채점 서브에이전트를 생성하거나 인라인으로 채점합니다. agents/grader.md를 읽고 각 assertion을 출력물에 대해 평가합니다. 결과를 각 실행 디렉토리의 grading.json에 저장합니다. grading.json의 expectations 배열은 반드시 text, passed, evidence 필드를 사용해야 합니다(name/met/details 또는 다른 변형이 아님) — 뷰어는 이 정확한 필드 이름에 의존합니다. 프로그래밍 방식으로 확인할 수 있는 assertion은 눈으로 확인하지 말고 스크립트를 작성해 실행하세요 — 스크립트가 더 빠르고 신뢰할 수 있으며 반복 사용 가능합니다.
벤치마크로 집계 — skill-creator 디렉토리에서 집계 스크립트를 실행합니다:
```
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
```
이를 통해 각 구성의 통과율, 시간, 토큰 정보와 평균 ± 표준편차 및 델타가 포함된 benchmark.json과 benchmark.md가 생성됩니다. benchmark.json을 수동으로 생성하는 경우 뷰어가 기대하는 정확한 스키마는 references/schemas.md를 참조하세요. 각 with_skill 버전을 베이스라인 앞에 배치합니다.
분석가 패스 수행 — 벤치마크 데이터를 읽고 집계 통계가 숨길 수 있는 패턴을 발견합니다. agents/analyzer.md(「벤치마크 결과 분석」 섹션)에서 찾아봐야 할 것들 — 스킬 유무에 관계없이 항상 통과하는 assertion(비변별적), 분산이 높은 eval(불안정할 수 있음), 시간/토큰 트레이드오프 등을 확인합니다.
정성적 출력과 정량적 데이터로 뷰어를 실행합니다:
```
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
  <workspace>/iteration-N \
  --skill-name "my-skill" \
  --benchmark <workspace>/iteration-N/benchmark.json \
  > /dev/null 2>&1 &
VIEWER_PID=$!
```
반복 2 이상부터는 --previous-workspace <workspace>/iteration-<N-1>도 전달합니다.

Cowork / 헤드리스 환경: webbrowser.open()을 사용할 수 없거나 디스플레이가 없는 환경이라면 --static <output_path>를 사용하여 서버를 시작하는 대신 독립형 HTML 파일을 작성합니다. 사용자가 "모든 리뷰 제출"을 클릭하면 피드백이 feedback.json 파일로 다운로드됩니다. 다운로드 후, 다음 반복이 사용할 수 있도록 feedback.json을 워크스페이스 디렉토리에 복사합니다.

참고: 사용자 정의 HTML을 작성하지 말고 generate_review.py를 사용하여 뷰어를 생성하세요.
사용자에게 다음과 같이 알립니다: "브라우저에서 결과를 열었습니다. 탭이 두 개입니다 — '출력물(Outputs)'에서 각 테스트 케이스를 클릭하고 피드백을 남길 수 있고, '벤치마크(Benchmark)'에는 정량적 비교가 표시됩니다. 완료되면 여기로 돌아와 알려주세요."

뷰어에서 사용자가 보는 것:

"출력물(Outputs)" 탭은 한 번에 하나의 테스트 케이스를 표시합니다:

프롬프트: 주어진 작업
출력물: 스킬이 생성한 파일, 가능한 경우 인라인으로 렌더링
이전 출력물 (반복 2 이상): 마지막 반복의 출력물을 접힌 섹션으로 표시
공식 채점 (채점이 실행된 경우): assertion 통과/실패를 접힌 섹션으로 표시
피드백: 입력하는 대로 자동 저장되는 텍스트박스
이전 피드백 (반복 2 이상): 마지막 번의 의견을 텍스트박스 아래에 표시

"벤치마크(Benchmark)" 탭은 통계 요약을 표시합니다: 각 구성의 통과율, 타이밍, 토큰 사용량, eval별 분석과 분석가 관찰 사항.

이전/다음 버튼이나 화살표 키로 탐색합니다. 완료되면 "모든 리뷰 제출"을 클릭하면 모든 피드백이 feedback.json에 저장됩니다.

5단계: 피드백 읽기

사용자가 완료했다고 알리면 feedback.json을 읽습니다:

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "차트에 축 레이블이 없음", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "완벽해요, 정말 마음에 들어요", "timestamp": "..."}
  ],
  "status": "complete"
}

빈 피드백은 사용자가 괜찮다고 생각한 것입니다. 사용자가 구체적인 불만을 제기한 테스트 케이스에 집중하여 개선합니다.

완료 후 뷰어 서버를 종료합니다:

kill $VIEWER_PID 2>/dev/null

스킬 개선:

이것이 루프의 핵심입니다. 테스트 케이스를 실행하고, 사용자가 결과를 검토했으며, 이제 피드백을 바탕으로 스킬을 더 좋게 만들어야 합니다.

개선에 대한 사고 방법:

피드백을 일반화하세요. 여기서 일어나고 있는 큰 그림은, 우리가 수백만 번(어쩌면 문자 그대로, 아니면 그 이상) 다양한 프롬프트에서 사용될 수 있는 스킬을 만들려 한다는 것입니다. 여기서 여러분과 사용자는 속도를 높이기 위해 몇 가지 예시를 반복해서 실행하고 있습니다. 사용자는 이 예시들을 속속들이 알고 있고 새 출력물을 빠르게 평가할 수 있습니다. 하지만 공동으로 개발하는 스킬이 그 예시들에만 작동한다면 쓸모가 없습니다. 사소하고 과적합된 변경이나 지나치게 구속적인 MUST를 넣는 것보다, 고질적인 문제가 있다면 다른 은유나 다른 작업 패턴을 시도해보세요. 시도해보는 비용이 상대적으로 낮고 훌륭한 결과를 얻을 수도 있습니다.
프롬프트를 간결하게 유지하세요. 효과 없는 것은 제거합니다. 최종 출력물뿐만 아니라 트랜스크립트를 꼭 읽어보세요 — 스킬이 비생산적인 작업에 많은 시간을 낭비하게 만든다면, 그 원인이 되는 스킬 부분을 제거하고 어떻게 되는지 확인해봅니다.
이유를 설명하세요. 모델에게 요청하는 모든 것의 이유를 설명하려고 최대한 노력합니다. 오늘날의 LLM은 똑똑합니다. 좋은 프레임워크를 갖추면 단순한 지시를 넘어 이론적 사고력을 발휘하여 정말로 일을 성사시킬 수 있습니다. 사용자의 피드백이 간결하거나 좌절스러워도, 작업을 실제로 이해하고 사용자가 왜 그것을 작성했는지, 실제로 무엇을 원하는지 이해한 다음 그 이해를 지침에 담아냅니다. ALWAYS나 NEVER를 대문자로 쓰거나 매우 경직된 구조를 사용하는 것은 노란 신호입니다 — 가능하다면 논리를 재구성하고 이유를 설명하여 모델이 왜 그것이 중요한지 이해하도록 합니다. 이것이 더 인간적이고 강력하며 효과적인 접근입니다.
테스트 케이스 전반에서 반복적인 작업을 찾으세요. 테스트 실행의 트랜스크립트를 읽고 서브에이전트들이 모두 비슷한 헬퍼 스크립트를 독립적으로 작성하거나 같은 다단계 접근법을 취했는지 살펴봅니다. 3개의 테스트 케이스 모두에서 서브에이전트가 create_docx.py나 build_chart.py를 작성했다면, 스킬이 그 스크립트를 번들로 포함해야 한다는 강력한 신호입니다. 한 번 작성하여 scripts/에 넣고 스킬이 이를 사용하도록 지시합니다. 이를 통해 미래의 모든 실행이 같은 작업을 반복 발명하는 것을 방지합니다.

이 작업은 꽤 중요합니다(우리는 여기서 연간 수십억 달러의 경제적 가치를 창출하려 하고 있습니다!) 그리고 여러분의 사고 시간이 병목이 아니므로, 충분한 시간을 갖고 깊이 생각해보세요. 수정 초안을 작성한 다음 새 눈으로 다시 보고 개선하는 것을 권장합니다. 사용자의 머릿속에 들어가 정말 원하고 필요한 것이 무엇인지 이해하는 데 최선을 다하세요.

반복 루프:

스킬 개선 후:

스킬에 개선 사항 적용
모든 테스트 케이스를 새 iteration-<N+1>/ 디렉토리에서 다시 실행합니다. 베이스라인 실행도 포함합니다. 새 스킬을 만드는 경우 베이스라인은 항상 without_skill(스킬 없음)입니다 — 반복 전체에서 동일하게 유지됩니다. 기존 스킬을 개선하는 경우 베이스라인으로 무엇이 적합한지 판단합니다: 사용자가 처음 가져온 원래 버전, 또는 이전 반복.
이전 반복 워크스페이스를 --previous-workspace로 가리켜 리뷰어를 실행합니다
사용자가 검토하고 완료했다고 알릴 때까지 기다립니다
새 피드백을 읽고 다시 개선하고 반복합니다

다음 경우까지 계속합니다:

사용자가 만족한다고 말함
피드백이 모두 비어 있음 (모든 것이 좋아 보임)
의미 있는 진전이 없음

고급: 블라인드 비교

두 버전의 스킬 간 더 엄격한 비교를 원하는 경우(예: 사용자가 "새 버전이 실제로 더 나은가요?"라고 묻는 경우), 블라인드 비교 시스템이 있습니다. 자세한 내용은 agents/comparator.md와 agents/analyzer.md를 읽어보세요. 기본 아이디어는: 어느 것이 어느 것인지 알려주지 않고 독립적인 에이전트에게 두 출력물을 제공하여 품질을 판단하게 합니다. 그런 다음 왜 승자가 이겼는지 분석합니다.

이것은 선택 사항이며, 서브에이전트가 필요하고, 대부분의 사용자에게는 필요하지 않습니다. 사람의 검토 루프로도 보통 충분합니다.

설명 최적화:

SKILL.md 프론트매터의 description 필드는 Claude가 스킬을 호출할지 결정하는 주요 메커니즘입니다. 스킬을 만들거나 개선한 후, 더 나은 트리거링 정확도를 위한 설명 최적화를 제안합니다.

1단계: 트리거 평가 쿼리 생성

트리거해야 하는 것과 트리거하지 않아야 하는 것이 혼합된 20개의 평가 쿼리를 만듭니다. JSON으로 저장합니다:

[
  {"query": "사용자 프롬프트", "should_trigger": true},
  {"query": "다른 프롬프트", "should_trigger": false}
]

쿼리는 현실적이어야 하며, Claude Code 또는 Claude.ai 사용자가 실제로 입력할 내용이어야 합니다. 추상적인 요청이 아니라 구체적이고 상세한 요청이어야 합니다. 예를 들어, 파일 경로, 직업이나 상황에 대한 개인적인 맥락, 열 이름과 값, 회사 이름, URL, 약간의 배경 이야기가 포함될 수 있습니다. 일부는 소문자이거나 약어, 오타, 구어체가 포함될 수 있습니다. 다양한 길이를 사용하고, 명백한 것보다 엣지 케이스에 집중합니다(사용자가 검토할 기회가 있습니다).

나쁜 예: "이 데이터를 형식화해줘", "PDF에서 텍스트 추출해줘", "차트 만들어줘"

좋은 예: "그러니까 제 상사가 방금 이 xlsx 파일을 보냈는데요 (다운로드 폴더에 있고, 이름이 'Q4 sales final FINAL v2.xlsx' 같은 것 같아요), 수익 마진을 퍼센트로 보여주는 열을 추가하길 원해요. 수익은 C 열에 있고 비용은 D 열에 있는 것 같아요"

should-trigger 쿼리(8~10개)의 경우, 커버리지를 생각합니다. 같은 의도를 다양한 방식으로 표현합니다 — 일부는 공식적으로, 일부는 비공식적으로. 사용자가 스킬 이름이나 파일 유형을 명시적으로 언급하지 않지만 명확히 필요로 하는 경우도 포함합니다. 드문 사용 사례와 이 스킬이 다른 스킬과 경쟁하지만 이겨야 하는 경우도 포함합니다.

should-not-trigger 쿼리(8~10개)의 경우, 가장 가치 있는 것은 근접 오류(near-miss)입니다 — 스킬과 키워드나 개념을 공유하지만 실제로는 다른 것이 필요한 쿼리입니다. 인접 도메인, 단순 키워드 매칭이라면 트리거되지만 실제로는 그래서는 안 되는 애매한 표현, 그리고 쿼리가 스킬이 하는 것에 관련되지만 다른 도구가 더 적합한 맥락의 경우를 생각해봅니다.

피해야 할 핵심 사항: should-not-trigger 쿼리를 명백히 무관하게 만들지 마세요. PDF 스킬의 부정적 테스트로 "피보나치 함수 작성해줘"는 너무 쉽습니다 — 아무것도 테스트하지 않습니다. 부정적 케이스는 진정으로 까다로워야 합니다.

2단계: 사용자와 검토

HTML 템플릿을 사용하여 사용자가 검토할 수 있도록 eval 세트를 제공합니다:

assets/eval_review.html에서 템플릿을 읽습니다
플레이스홀더를 교체합니다:
- __EVAL_DATA_PLACEHOLDER__ → eval 항목의 JSON 배열 (따옴표 없이 — JS 변수 할당임)
- __SKILL_NAME_PLACEHOLDER__ → 스킬 이름
- __SKILL_DESCRIPTION_PLACEHOLDER__ → 스킬의 현재 설명
임시 파일에 저장하고 열기: open /tmp/eval_review_<skill-name>.html
사용자는 쿼리를 수정하고, should-trigger를 전환하고, 항목을 추가/제거한 다음 "Eval 세트 내보내기"를 클릭할 수 있습니다
파일은 ~/Downloads/eval_set.json으로 다운로드됩니다 — 여러 버전이 있을 경우(예: eval_set (1).json) 가장 최근 버전을 Downloads 폴더에서 확인합니다

이 단계는 중요합니다 — 잘못된 eval 쿼리는 잘못된 설명으로 이어집니다.

3단계: 최적화 루프 실행

사용자에게 말합니다: "이 작업은 시간이 걸립니다 — 백그라운드에서 최적화 루프를 실행하고 주기적으로 확인하겠습니다."

eval 세트를 워크스페이스에 저장한 다음 백그라운드에서 실행합니다:

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

현재 세션을 구동하는 시스템 프롬프트의 모델 ID를 사용합니다. 이를 통해 트리거링 테스트가 사용자가 실제로 경험하는 것과 일치합니다.

실행 중에는 주기적으로 출력을 확인하여 현재 몇 번째 반복인지와 점수가 어떤지 사용자에게 업데이트합니다.

이 스크립트는 전체 최적화 루프를 자동으로 처리합니다. eval 세트를 60% 훈련 세트와 40% 홀드아웃 테스트 세트로 분할하고, 현재 설명을 평가(신뢰할 수 있는 트리거 비율을 얻기 위해 각 쿼리를 3번 실행)한 다음, 실패한 것을 기반으로 Claude에게 확장 사고로 개선을 제안하도록 요청합니다. 훈련 세트와 테스트 세트 모두에서 각 새 설명을 재평가하고 최대 5번 반복합니다. 완료되면 결과를 브라우저에서 HTML 보고서로 열어 반복당 결과를 보여주고, best_description이 포함된 JSON을 반환합니다 — 과적합을 방지하기 위해 훈련 점수가 아닌 테스트 점수로 선택됩니다.

스킬 트리거링 작동 방식:

트리거링 메커니즘을 이해하면 더 나은 eval 쿼리를 설계하는 데 도움이 됩니다. 스킬은 Claude의 available_skills 목록에 이름 + 설명과 함께 나타나며, Claude는 그 설명을 바탕으로 스킬을 참조할지 결정합니다. 중요한 점은 Claude가 스스로 쉽게 처리할 수 없는 작업에만 스킬을 참조한다는 것입니다 — "이 PDF 읽어줘"와 같은 단순하고 한 단계짜리 쿼리는 설명이 완벽하게 일치하더라도 스킬을 트리거하지 않을 수 있습니다. Claude가 기본 도구로 직접 처리할 수 있기 때문입니다. 복잡하고 다단계이거나 전문적인 쿼리는 설명이 일치할 때 안정적으로 스킬을 트리거합니다.

이는 eval 쿼리가 Claude가 스킬을 참조함으로써 실제로 이점을 얻을 만큼 충분히 실질적이어야 함을 의미합니다. "파일 X 읽어줘"와 같은 단순한 쿼리는 설명 품질에 관계없이 스킬을 트리거하지 않으므로 좋은 테스트 케이스가 아닙니다.

4단계: 결과 적용

JSON 출력에서 best_description을 가져와 스킬의 SKILL.md 프론트매터를 업데이트합니다. 이전/이후를 사용자에게 보여주고 점수를 보고합니다.

패키징 및 제출 (present_files 도구가 있는 경우에만):

present_files 도구에 접근 가능한지 확인합니다. 없다면 이 단계를 건너뜁니다. 있다면 스킬을 패키징하고 사용자에게 .skill 파일을 제공합니다:

python -m scripts.package_skill <path/to/skill-folder>

패키징 후, 사용자가 설치할 수 있도록 결과 .skill 파일 경로를 알려줍니다.

Claude.ai 전용 지침:

Claude.ai에서는 핵심 워크플로우가 동일합니다(초안 → 테스트 → 검토 → 개선 → 반복). 단, Claude.ai에는 서브에이전트가 없으므로 일부 메커니즘이 달라집니다. 조정해야 할 사항:

테스트 케이스 실행: 서브에이전트가 없으므로 병렬 실행이 불가능합니다. 각 테스트 케이스마다 스킬의 SKILL.md를 읽은 다음 그 지침에 따라 직접 테스트 프롬프트를 수행합니다. 하나씩 순서대로 진행합니다. 이 방법은 독립적인 서브에이전트보다 엄밀하지 않지만(스킬을 작성한 사람이 동시에 실행하므로 전체 맥락을 갖고 있음), 유용한 건전성 검사 역할을 합니다 — 그리고 사람의 검토 단계가 이를 보완합니다. 베이스라인 실행은 건너뜁니다 — 스킬을 사용하여 요청된 작업을 완료합니다.

결과 검토: 브라우저를 열 수 없는 경우(예: Claude.ai의 VM에 디스플레이가 없거나 원격 서버인 경우), 브라우저 리뷰어를 완전히 건너뜁니다. 대신 대화에서 직접 결과를 제시합니다. 각 테스트 케이스에 대해 프롬프트와 출력물을 보여줍니다. 출력물이 사용자가 봐야 하는 파일(.docx나 .xlsx 등)인 경우 파일 시스템에 저장하고 다운로드해서 검토할 수 있도록 위치를 알려줍니다. 인라인으로 피드백을 요청합니다: "어떻게 보이나요? 변경하고 싶은 것이 있나요?"

벤치마킹: 정량적 벤치마킹을 건너뜁니다 — 서브에이전트 없이는 베이스라인 비교가 의미 없습니다. 사용자의 정성적 피드백에 집중합니다.

반복 루프: 이전과 동일합니다 — 스킬 개선, 테스트 케이스 재실행, 피드백 요청 — 단, 중간에 브라우저 리뷰어 없이 진행합니다. 파일 시스템이 있는 경우 여전히 반복 디렉토리에 결과를 구성할 수 있습니다.

설명 최적화: 이 섹션은 Claude Code에서만 사용 가능한 claude CLI 도구(특히 claude -p)가 필요합니다. Claude.ai에서는 건너뜁니다.

블라인드 비교: 서브에이전트가 필요합니다. 건너뜁니다.

패키징: package_skill.py 스크립트는 Python과 파일 시스템이 있는 어디서나 작동합니다. Claude.ai에서 실행하고 사용자가 결과 .skill 파일을 다운로드할 수 있습니다.

Cowork 전용 지침:

Cowork 환경에서 주요 사항:

서브에이전트가 있으므로 주요 워크플로우(테스트 케이스 병렬 생성, 베이스라인 실행, 채점 등)가 모두 작동합니다. (단, 타임아웃으로 심각한 문제가 발생하면 병렬 대신 순차적으로 테스트 프롬프트를 실행해도 됩니다.)
브라우저나 디스플레이가 없으므로, eval 뷰어를 생성할 때 서버를 시작하는 대신 --static <output_path>를 사용하여 독립형 HTML 파일을 작성합니다. 그런 다음 사용자가 클릭하여 브라우저에서 HTML을 열 수 있는 링크를 제공합니다.
어떤 이유로 Cowork 설정이 테스트 실행 후 Claude가 eval 뷰어를 생성하지 않으려는 경향이 있으므로, 다시 강조합니다: Claude Code에서든 Cowork에서든, 테스트 실행 후에는 항상 generate_review.py를 사용하여 eval 뷰어를 생성하여 사람이 예시를 검토하고 난 다음에 스킬을 수정해야 합니다. 사전에 미리 강조할게요: 직접 입력을 평가하기 전에 eval 뷰어를 생성하세요. 가능한 빨리 사람 앞에 보여줘야 합니다!
피드백은 다르게 작동합니다: 실행 중인 서버가 없으므로, 뷰어의 "모든 리뷰 제출" 버튼이 feedback.json 파일을 다운로드합니다. 그런 다음 거기서 읽을 수 있습니다(먼저 접근 권한을 요청해야 할 수도 있습니다).
패키징은 작동합니다 — package_skill.py는 Python과 파일 시스템만 필요합니다.
설명 최적화(run_loop.py / run_eval.py)는 브라우저가 아닌 subprocess를 통해 claude -p를 사용하므로 Cowork에서 잘 작동해야 합니다. 단, 스킬이 완전히 완성되고 사용자가 좋다고 동의한 후까지 저장해두세요.

참조 파일:

agents/ 디렉토리에는 특수 서브에이전트를 위한 지침이 있습니다. 관련 서브에이전트를 생성해야 할 때 읽어보세요.

agents/grader.md — 출력물에 대한 assertion 평가 방법
agents/comparator.md — 두 출력물 간 블라인드 A/B 비교 방법
agents/analyzer.md — 한 버전이 다른 버전을 이긴 이유 분석 방법

references/ 디렉토리에는 추가 문서가 있습니다:

references/schemas.md — evals.json, grading.json 등의 JSON 구조

핵심 루프를 다시 한 번 강조합니다:

스킬이 무엇에 관한 것인지 파악하기
스킬 초안 작성 또는 편집하기
테스트 프롬프트로 '스킬이 탑재된 Claude' 실행하기
사용자와 함께 출력물 평가하기:
- benchmark.json을 생성하고 eval-viewer/generate_review.py를 실행하여 사용자가 검토하도록 도움
- 정량적 evals 실행
여러분과 사용자가 만족할 때까지 반복하기
최종 스킬을 패키징하여 사용자에게 반환하기

할 일 목록이 있다면 잊지 않도록 단계들을 추가하세요. Cowork에 있다면 특히 "eval JSON을 생성하고 사람이 테스트 케이스를 검토할 수 있도록 eval-viewer/generate_review.py 실행하기"를 할 일 목록에 추가하여 반드시 실행되도록 하세요.

행운을 빕니다!

AI Skill: Concepts and Design

Recommended for

Our review

Strengths

Limitations

Security analysis

Examples

skill 학습

1단계: 개념과 배경 이해

1-1. Skill이란 무엇인가

1-2. Skill이 등장한 배경 — 바이브 코딩의 품질 문제

1-3. AI가 반복하는 전형적인 코드 문제 패턴

1-4. Rules vs Skills vs MCP — 세 개념의 차이

1-5. Progressive Disclosure — Skill의 핵심 설계 원리

1-6. Agent Skills Open Standard — 도구 간 호환성

1-7. Skill의 세 가지 유스케이스 카테고리

1단계 학습 자료

2단계: 공식 스펙과 Best Practice 정독

2-1. 디렉토리 구조

2-2. SKILL.md 파일의 두 부분

2-3. 프론트매터 필드 상세 규칙

name (필수)

description (필수)

license (선택)

compatibility (선택, 1~500자)

metadata (선택)

allowed-tools (선택, 실험적)

2-4. 마크다운 본문 작성법

Step 2: [두 번째 주요 단계]

Examples

Example 1: [흔한 시나리오]

Troubleshooting

Error: [흔한 에러 메시지]

2-5. 본문 크기 관리와 파일 분리

2-6. scripts/ 디렉토리 작성 규칙

2-7. references/ 디렉토리 작성 규칙

2-8. 하나의 Skill = 하나의 명확한 역할

2-9. 흔한 실수와 트러블슈팅

2-10. Skill 검증

2-11. 성공 기준 정의 방법

2단계 학습 자료

2단계 완료 후 자기 점검 체크리스트

3단계: SKILL.md 실전 작성 실습 가이드

사전 준비: 실습 환경 구성

에이전트별 Skill 저장 경로

실습 프로젝트 생성

실습 3-1: 기존 우수 Skill 분석

과제 A: anthropics/skills 저장소 클론 및 분석

과제 B: skills.sh 인기 Skill 비교 분석

과제 C: Clean Code Skills 분석

과제 D: 분석 보고서 작성

실습 3-2: 직접 작성 — 난이도별 5단계

연습 1 (입문): Git 커밋 메시지 규칙 Skill

연습 2 (초급): 코드 리뷰 Skill

Summary

Strengths

Issues Found

[Critical/Warning/Suggestion] — [file:line]

연습 3 (중급): 폴더 구조를 갖춘 API 설계 Skill

Error Handling

연습 4 (심화): 프로젝트 전용 Skill 세트 — 3개 Skill의 역할 분리

Rules

Rules

Rules

연습 5 (심화+): Subagent 실행과 동적 컨텍스트 주입 (Claude Code 전용)

추가 실습 과제 (심화 학습)

추가 실습 A: 기존 Skill을 npx skills로 설치하고 구조 분석

추가 실습 B: skill-creator 메타 Skill을 이용한 Skill 생성

추가 실습 C: 에이전트별 동작 차이 비교 실험

추가 실습 D: OpenCode 권한 제어 실습

추가 실습 E: GitHub Copilot 고유 기능 — user-invokable / disable-model-invocation 조합 실험

실습 3-3: 테스트 및 피드백 루프 — 체계적 방법

트리거 테스트

기능 테스트

스펙 검증

피드백 반영 사이클

전체 실습 요약 및 체크리스트

4단계: 생태계 활용과 지속 개선 — 실습 가이드

실습 4-1: npx skills CLI 완전 정복

실습 A: 기본 명령어 7종 체험

`name` (필수)

`description` (필수)

`license` (선택)

`compatibility` (선택, 1~500자)

`metadata` (선택)

`allowed-tools` (선택, 실험적)