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)만 스스로 조정한다 -
다음부터는 신호 하나로 호출한다 — "의사록 정리해줘"라는 말만으로 저장된 절차가 시작된다

포인트는 책상 앞에 앉아 매뉴얼을 작성하는 것이 아니라, 실제로 한 번 작동한 절차를 그 자리에서 파일화하는 것입니다. 이 순서라면 절차서가 실제 상황과 어긋나지 않습니다.

frontmatter는 반드시 파일의 맨 앞에 둔다. frontmatter보다 앞에 H1 헤더 등을 쓰면 해석되지 않아 description이 작동하지 않고 "스킬이 호출되지 않는" 상태가 됩니다 (한 번 실수했습니다) -
만든 직후에 발동 테스트를 한다. 평소 쓰는 말투로 실제로 호출하여 제대로 시작되는지 확인한 후 운영에 적용한다 -
절차서에 "도구"를 동봉하면 재현성이 높아진다. 저의 blog-publish 스킬은 절차 중에서 검색 엔진 알림용 작은 스크립트를 실행합니다. 매번 AI에게 코드를 쓰게 하는 것이 아니라, 고정된 처리는 스크립트로 묶어서 절차서에서 호출한다 —— "스킬 = 절차서 + 도구 상자"라고 생각하면 안정적입니다

또한, 이 절차서 메커니즘(Agent Skills)은 공통 규격으로서 다른 AI 도구에도 채택이 확산되고 있으므로, 작성한 자산은 Claude Code 외부에서도 활용할 수 있습니다.

• Skills는 "매번 하는 설명"을 파일화하는 메커니즘. description에 발동 키워드를 적는 것이 핵심
• 만드는 법은 "한 번 잘 시켜본 뒤, 그 절차를 스킬화시키는 것"이 최단 경로
• frontmatter는 맨 앞에. 만들면 발동 테스트. 고정 처리는 스크립트로 만들어 동봉

비엔지니어용 해설판은 블로그에 적어두었습니다: Claude Code Skills 만드는 법 | 이 사이트 운영은 11개의 "절차서"로 움직이고 있다