Claude Code에 같은 작업을 요청할 때마다, 매번 같은 절차 설명을 다시 입력하고 계시지는 않나요? 이 '매번 하는 설명'을 없애는 것이 바로 Skills입니다. 절차를 SKILL.md라는 파일에 적어두면, Claude Code가 요청 문구로부터 "이 작업이라면 그 절차서구나"라고 스스로 판단하여 읽어 들여, 매번 같은 흐름과 같은 품질로 작업을 재현합니다.
저는 이 메커니즘을 통해 웹사이트(블로그) 운영을 하고 있으며, 기사 작성·공개·소재 수집·접속 분석까지 11개의 Skills가 작동하고 있습니다. 이 기사에서는 서식·만드는 법·주의할 점을 정리합니다.
스킬은 .claude/skills/<skill-name>/SKILL.md에 둡니다. 구조는 YAML frontmatter + Markdown 본문뿐입니다.
---
name: meeting-notes
description: 회의 메모로부터 의사록을 만든다. "의사록 정리해줘", "미팅 메모 정리해줘" 등으로 사용.
...
중요한 것은 description입니다. Claude Code는 요청 문구와 description을 대조하여 스킬을 발동하므로, 여기에는 기능 설명뿐만 아니라 "어떤 말로 요청했을 때 사용할 것인가"라는 발동 키워드까지 적습니다. 자신이 평소 그 작업을 요청할 때 쓰는 습관적인 말투를 넣어두는 것이 요령입니다.
가장 확실한 만드는 방법은 Claude Code 스스로 쓰게 하는 방법입니다.
그 작업을 우선 한 번 평범하게 요청한다 — 납득할 만한 결과가 나올 때까지 대화로 완성한다 -
"지금의 절차를 Skill로 만들어줘"라고 요청한다 — 잘 진행된 대화 내용을 그대로 절차서로 변환시킨다 -
생성된 SKILL.md를 확인한다 — 발동 키워드(description)와 절차의 입도(granularity)만 스스로 조정한다 -
다음부터는 신호 하나로 호출한다 — "의사록 정리해줘"라는 말만으로 저장된 절차가 시작된다
포인트는 책상 앞에 앉아 매뉴얼을 작성하는 것이 아니라, 실제로 한 번 작동한 절차를 그 자리에서 파일화하는 것입니다. 이 순서라면 절차서가 실제 상황과 어긋나지 않습니다.
| 스킬 | 역할 |
|---|
| knowledge-harvest | 소재 노트(Discord)로부터 깨달음을 수집하여 지식 파일로 정형화 |
| ... | |
| "오늘의 블로그 써줘"라는 한마디로, blog-write가 정해진 형식의 초안을 돌려줍니다. 공정마다 스킬을 나누어 놓은 이유는, 실패했을 때 "어느 공정의 절차서가 잘못되었는지"를 특정하여 그 파일만 수정할 수 있도록 하기 위해서입니다. | |
frontmatter는 반드시 파일의 맨 앞에 둔다. frontmatter보다 앞에 H1 헤더 등을 쓰면 해석되지 않아 description이 작동하지 않고 "스킬이 호출되지 않는" 상태가 됩니다 (한 번 실수했습니다) -
만든 직후에 발동 테스트를 한다. 평소 쓰는 말투로 실제로 호출하여 제대로 시작되는지 확인한 후 운영에 적용한다 -
절차서에 "도구"를 동봉하면 재현성이 높아진다. 저의 blog-publish 스킬은 절차 중에서 검색 엔진 알림용 작은 스크립트를 실행합니다. 매번 AI에게 코드를 쓰게 하는 것이 아니라, 고정된 처리는 스크립트로 묶어서 절차서에서 호출한다 —— "스킬 = 절차서 + 도구 상자"라고 생각하면 안정적입니다
또한, 이 절차서 메커니즘(Agent Skills)은 공통 규격으로서 다른 AI 도구에도 채택이 확산되고 있으므로, 작성한 자산은 Claude Code 외부에서도 활용할 수 있습니다.
- Skills는 "매번 하는 설명"을 파일화하는 메커니즘. description에 발동 키워드를 적는 것이 핵심
- 만드는 법은 "한 번 잘 시켜본 뒤, 그 절차를 스킬화시키는 것"이 최단 경로
- frontmatter는 맨 앞에. 만들면 발동 테스트. 고정 처리는 스크립트로 만들어 동봉
비엔지니어용 해설판은 블로그에 적어두었습니다: Claude Code Skills 만드는 법 | 이 사이트 운영은 11개의 "절차서"로 움직이고 있다
