Claude Agent Skills 완벽 가이드: 첫 스킬 만들기

"같은 지시를 매번 다시 입력하기 지치지 않으셨나요?"

📌 핵심 3줄 요약

• claude agent skills는 Claude Code에 재사용 가능한 작업 묶음을 가르치는 SKILL.md + 보조 파일 폴더다.
• frontmatter의 description 필드 한 줄이 자연어 호출 매칭의 핵심 — 변별 가능한 키워드를 박는다.
• 5단계(폴더 → SKILL.md → references → 호출 검증 → 다듬기)로 첫 스킬을 30분 안에 만들고 git 커밋만으로 팀 공유까지 끝낸다.

1. Skills가 뭐고 왜 필요한가

Skills는 .claude/skills/<skill-name>/ 폴더 안에 SKILL.md(지침서)와 보조 파일을 넣어 두는 방식이다. 사용자가 슬래시 명령이나 자연어로 호출하면 에이전트가 그 폴더 내용을 컨텍스트로 끌어와 작업한다. 함수가 아니라 매뉴얼이다.

Tools·Plugins와 헷갈리기 쉬워 한 표로 정리한다.

구분	Tools	Plugins(MCP)	Skills
형태	함수 호출 스키마	외부 서버·표준 프로토콜	마크다운+파일 묶음
호출 주체	모델 자동 선택	모델이 도구처럼 호출	사용자/에이전트 명시 호출
적합 작업	검색·계산 단발성	외부 API·DB 연동	반복 워크플로·도메인 지침

핵심 차이는 마지막 행이다. Skills는 절차적 지식을 LLM에 직접 가르친다. 코드를 못 짜는 도메인 전문가도 마크다운만 쓰면 스킬을 만들 수 있다.

2. 폴더 구조와 SKILL.md 골격

표준 트리:

.claude/skills/
└── pr-reviewer-ko/
    ├── SKILL.md           # 진입점: YAML frontmatter + 본문
    ├── references/        # 체크리스트·스타일 가이드
    ├── scripts/           # 보조 스크립트
    └── examples/          # 모범 답안

SKILL.md는 frontmatter + 본문 두 부분이다. frontmatter의 description은 에이전트가 어떤 스킬을 부를지 결정하는 한 줄이라 추상어 대신 변별 키워드를 박는다.

---
name: pr-reviewer-ko
description: 한국어로 PR 리뷰 코멘트를 작성한다. diff를 받아 코드 품질·테스트·문서화 3축으로 점검하고 존댓말로 출력한다.
trigger: ["/pr-review", "PR 리뷰해줘"]
---

# 절차
1. diff에서 변경 파일 목록을 뽑는다.
2. references/checklist.md의 12개 항목을 순서대로 적용한다.
3. 각 코멘트는 "근거 한 줄 + 제안 한 줄"로 작성한다.

💡 핵심 포인트

• SKILL.md 본문은 호출 시 컨텍스트에 그대로 주입 → 100~200줄 이내로 유지
• 판정 기준·예시는 references/에 분리 → 필요할 때만 LLM이 Read
• description은 "PR 리뷰" 같은 추상어 금지 → "한국어·diff·3축" 같은 키워드

3. 첫 스킬 5단계로 만들기

예시: "한국어 블로그 마크다운 점검기" 스킬을 30분 안에.

1. 폴더 + 빈 SKILL.md 생성: mkdir -p .claude/skills/ko-blog-linter/references
2. references/ 채우기: forbidden_phrases.md에 정규식 금지 표현, style_rubric.md에 자연스러움 5항목
3. SKILL.md 절차 5줄: "읽는다 → 정규식 매칭 → 표 출력 → 점수 → 재작성 제안"
4. 호출 검증: /ko-blog-linter draft.md 또는 자연어. 첫 호출은 출력 형식이 어긋날 가능성 큼 → examples/에 모범·반례 1건씩 추가
5. git 커밋 = 팀 공유: 폴더 자체를 커밋하면 팀원이 클론만 해도 같은 스킬 사용

⚠️ 자주 막히는 함정

• SKILL.md가 길어짐 → 토큰 비용 폭증. 본문 200줄 넘으면 references로 분리.
• description이 너무 추상적 → 다른 스킬과 충돌. "한국어·diff·3축" 같은 변별 키워드 필수.
• 스킬끼리 호출 → 깊이 1까지만. 그 이상은 메타 에이전트 패턴 권장.
• 외부 네트워크 가정 → Skills는 로컬 파일이라 사내 보안망에서도 동작.

🚀 지금 바로 할 일

1. 팀에서 매주 반복되는 작업 1개 골라 SKILL.md 골격(50줄)부터 작성
2. 사내 컨벤션 문서를 그대로 references/에 복사 → LLM이 같은 기준으로 판단
3. 스킬 호출 결과를 1주일 모은 뒤 description 한 문장만 다듬어 재커밋

💬 의견

이미 자체 스킬을 운영 중이라면 description을 어떻게 쓰고 계신지 댓글로 공유 부탁드립니다. 다음 글은 MCP와 Skills를 한 워크플로에 묶는 패턴을 다룰 예정입니다.

함께 보면 좋은 글

• MCP 시작 가이드 — 외부 API·DB 연동을 Plugins(MCP) 쪽에서 풀고 싶을 때 함께 보면 Skills와의 역할 분담이 분명해진다.
• Cursor 시작 가이드 — 같은 워크플로를 다른 에디터에서 어떻게 만드는지 비교해 보고 싶다면.
• Claude Projects vs Custom GPTs — 컨텍스트 주입 방식이 제품마다 어떻게 다른지 큰 그림을 잡는 데 도움이 된다.
• OpenAI Agents SDK 튜토리얼 — 같은 "에이전트 + 도구" 개념을 OpenAI 쪽에서는 어떻게 표현하는지 대조해 볼 수 있다.

참고 자료

• Anthropic Docs — Agent Skills overview
• Anthropic 공식 발표 — Introducing Agent Skills
• github.com/anthropics/skills 공식 예시 모음

---

작성자: AI·개발자 도구를 한국어로 정리하는 기술 블로거

최종 업데이트: 2026-05-05

참고 시점: Skills는 빠르게 진화 중. 6개월 단위로 본문(SKILL.md 권장 길이·trigger 문법)을 점검 권장.