시즌 2-12편. Claude로 나만의 skill.md 만들어보기

 

지난 편에서는 ChatGPT의 UI 안에서 나만의 GPT를 만드는 방법을 30분 튜토리얼로 정리했습니다. Configure 탭에 인스트럭션을 채우고, 참고 자료를 업로드하고, 미리보기로 테스트해 발행하는 흐름이었죠.

오늘은 같은 감각을 조금 더 개발자스럽게 옮겨보려 합니다. UI가 아니라 파일로 관리하는 방식입니다. 시즌 2-1편에서 다뤘던 skill.md를 실제로 만들어보는 편입니다. Anthropic이 Claude Skills라는 이름으로 공식 기능을 낸 이후로, 이 방식이 개발자와 자동화 사용자 사이에서 빠르게 퍼지고 있습니다.

오늘은 처음 skill.md를 하나 만들어보는 사람의 시선에서, 준비부터 실제 사용까지 순서대로 정리해보겠습니다.

먼저 지난 편과의 차이부터 짚고 가겠습니다.

• 나만의 GPT: ChatGPT의 UI 안에서 관리되는 챗봇. 인스트럭션과 참고 자료가 웹 계정에 저장됨
• skill.md: 마크다운 파일 하나. 파일 시스템 안에 저장되고, 여러 도구/에이전트에서 재사용 가능

한 문장으로 정리하면 이렇습니다.

skill.md는 UI 없이 파일로 관리되는, 재사용 가능한 AI 스킬 정의입니다.

UI 관리는 편하지만, 파일 관리는 자유도가 훨씬 큽니다. 여러 프로젝트에서 같은 스킬을 재사용할 수 있고, 버전 관리를 붙일 수 있고, 팀에서 공유하기도 쉽습니다.

🍳 다시 매뉴얼 비유로

시즌 2-1편에서 skill.md를 "AI를 위한 업무 매뉴얼"에 비유했었죠. 이번에는 그 비유를 조금 확장해보겠습니다.

• 나만의 GPT: 특정 카페 브랜드가 자체 앱 안에 넣어둔 매뉴얼. 그 앱을 통해서만 볼 수 있음
• skill.md: 매뉴얼이 인쇄되어 있는 종이 파일. 어느 카페든 이 파일을 두면 그 매뉴얼대로 일함

두 방식 다 유효합니다. 다만 관리 방식과 확장성이 다릅니다. 종이 매뉴얼(파일)은 어느 카페(도구)로든 옮겨갈 수 있다는 강점이 있죠.

🛠️ 오늘 만들 skill.md

튜토리얼의 목표는 이번에도 실용성 우선입니다.

블로그 초안 리뷰 스킬 — 블로그 원고 초안을 던지면 정해진 원칙(톤, 구조, 회귀 오프닝 여부 등)에 따라 리뷰해주는 skill.md

이 스킬을 잘 만들어두면, 어떤 도구(Claude Desktop, Cursor, VSCode 확장 등)에서든 원고 초안을 던지고 "블로그 초안 리뷰 스킬 발동해줘"라고 요청하면 같은 결과가 나오게 됩니다.

🛠️ 준비물

필요한 건 세 가지입니다. Claude Desktop 또는 skill.md를 지원하는 다른 도구(Cursor 등), 텍스트 편집기(VSCode, 메모장, 심지어 노션 마크다운 뷰어도 가능), 그리고 대략 30~40분의 시간.

전체 흐름은 5단계로 정리했습니다. (1) 스킬 폴더 준비, (2) skill.md 뼈대 잡기, (3) 규칙과 예시 채우기, (4) 도구에 등록, (5) 실제 초안으로 테스트.

1단계: 스킬 폴더 준비

skill.md는 그냥 파일 하나만 있어도 되지만, 실전에서는 폴더 단위로 관리하는 게 편합니다. 저는 홈 디렉토리 아래에 ~/skills 폴더를 하나 만들고, 그 안에 각 스킬별 하위 폴더를 만들었습니다.

각 스킬 폴더 안에 SKILL.md 파일 하나가 반드시 있고, 필요하면 참고 자료가 담긴 references/ 하위 폴더를 둡니다. 이 구조는 Anthropic이 제안하는 공식 형태와 거의 같습니다.

여기서 헤맸던 지점: 처음에는 파일 하나만 딱 만들고 끝내려 했는데, 참고 자료가 늘어나면서 관리가 지저분해졌습니다. 처음부터 폴더 구조를 만들어두는 게 나중을 위해 훨씬 낫다는 걸 배웠습니다.

2단계: skill.md 뼈대 잡기

이제 blog-review/SKILL.md 파일을 만들고 뼈대를 잡아보겠습니다. skill.md의 뼈대는 크게 세 부분입니다.

• 프론트매터(맨 위 --- 사이): 스킬의 이름과 발동 조건 명세. YAML 형식
• 본문: 이 스킬이 무엇을 하고, 어떤 원칙을 따르며, 어떤 절차로 일하는지 서술
• 참고 예시: 좋은 예/나쁜 예, 참고 파일 목록 등

가장 기본이 되는 프론트매터의 형태는 이렇습니다.

description이 가장 중요합니다. AI는 이 한 줄을 보고 "지금 상황이 이 스킬을 써야 할 때인가?"를 판단하거든요. 시즌 2-1편에서 이야기했던 것처럼, 매뉴얼 표지의 큰 글씨 같은 자리입니다.

여기서 헤맸던 지점: 처음에는 description을 짧게 "블로그 리뷰 스킬"이라고만 썼습니다. 그러니 AI가 언제 이 스킬을 발동해야 하는지 잘 판단하지 못했습니다. 언제 발동해야 하는지의 조건까지 함께 쓰는 것이 중요합니다.

3단계: 규칙과 예시 채우기

뼈대를 잡았으니, 본문에 실제 규칙을 채워봅니다. 저는 이렇게 썼습니다.

이 파일에서 눈여겨보실 부분을 몇 개 짚어보겠습니다.

첫째, 원칙을 불릿으로 리스트업했습니다. AI는 리스트를 잘 처리합니다. "이런 게 있고 저런 게 있고..."라는 서술형보다, 딱 나열된 항목이 훨씬 정확하게 지켜집니다.

둘째, 절차를 번호로 명시했습니다. "1번부터 5번까지 순서대로 하라"는 형태로 쓰면, AI가 그 순서를 지키려고 노력합니다. 순서가 뒤바뀌면 결과 품질이 흔들리는 리뷰 같은 작업에 특히 유용합니다.

셋째, "하지 말 것"을 명시했습니다. 시즌 2-11편에서도 강조했지만, 금지사항 명시는 답의 안정성을 크게 올립니다.

4단계: 도구에 등록하기

파일이 완성되면 이제 이 스킬을 인식할 도구에 등록해야 합니다. 대표적으로 Claude Desktop을 예로 들어보겠습니다.

Claude Desktop의 설정 화면에서 스킬 폴더 경로를 지정할 수 있습니다. 앞서 만든 ~/skills 폴더를 지정하면, 그 안의 모든 스킬을 Claude가 자동으로 인식합니다.

📸 [스크린샷 자리: Claude Desktop 설정 화면에서 스킬 폴더 경로를 등록한 상태]

등록되면 Claude가 각 스킬의 description을 훑고, "이런 스킬들이 등록되어 있다"는 걸 파악합니다. 이제 사용자가 어떤 요청을 던지면, Claude가 스스로 판단해서 관련 스킬을 발동합니다.

Cursor 같은 다른 도구에서도 최근에는 비슷한 방식으로 스킬 폴더를 인식하는 기능이 붙고 있습니다. 즉 스킬 파일 하나를 잘 만들어두면, 여러 도구에서 재활용할 수 있는 자산이 되는 것이죠.

5단계: 실제 초안으로 테스트

이제 실전 테스트입니다. 저는 이번 시즌 12편의 초고를 하나 던지고 "블로그 초안 리뷰 스킬로 리뷰해줘"라고 요청했습니다.

Claude는 스스로 blog-review 스킬을 발동하고, 정확히 제가 정의한 형식으로 답했습니다. 8가지 원칙별 O/△/X 판정, 개선 제안, 톤 관찰, 다음 편 연결 코멘트까지. 놀라운 것은 매번 요청할 때마다 같은 구조의 리뷰가 돌아온다는 점이었습니다. 프롬프트를 매번 새로 쓰지 않아도, 스킬 하나만 등록해두면 이후로는 "리뷰해줘" 한 마디로 끝납니다.

📊 skill.md와 나만의 GPT를 다시 비교

두 방식의 차이를 표로 정리해보겠습니다.

구분 나만의 GPT skill.md

저장 위치	ChatGPT 웹 계정	로컬 파일 시스템
관리 방식	UI에서 클릭	텍스트 편집기
재사용성	ChatGPT 안에서만	여러 도구에서 재활용
버전 관리	어려움	Git으로 가능
팀 공유	링크 공유	파일/저장소 공유
진입 장벽	낮음 (UI)	중간 (파일 관리 익숙해져야)
자유도	제한적	매우 큼

정리하면 이렇습니다. 일회성 챗봇에는 GPT가, 자동화의 재료로 축적할 스킬에는 skill.md가 더 어울립니다.

🔗 시즌 2 개념들과의 결합

이번에 만든 blog-review 스킬은 시즌 2에서 소개한 여러 개념이 그대로 손에 잡히는 사례입니다. 시즌 2-1편의 skill.md 정의가 실제 파일로 손에 잡혔고, 시즌 2-4편의 컨텍스트 엔지니어링이 규칙과 절차를 파일로 정리하는 형태로 실행됐으며, 시즌 2-5편의 MCP 관점에서 보면 skill.md는 도구 간 이동이 자유로운 재료입니다.

특히 이 스킬은 앞으로 시즌 2-13편, 15편에서 다룰 자동화 워크플로의 재료가 됩니다. 여러 skill.md를 조합해서 자동 파이프라인을 만들 수 있는 시작점이 되는 것이죠.

💭 처음 만들어보고 느낀 세 가지

첫째, 파일 관리가 익숙하지 않은 분에게는 초반 진입 비용이 있습니다. 저도 처음에 파일 위치, 하위 폴더 구조, 문법 등 사소한 부분에서 시간을 꽤 썼습니다. 다만 한 번 감이 잡히면 이후는 매우 편해집니다.

둘째, 여러 스킬을 만들다 보면 자연스럽게 나만의 라이브러리가 쌓입니다. 저는 지금 blog-review, meeting-summary, resume-tune 세 개를 갖고 있는데, 새 요청이 올 때마다 어떤 스킬이 발동될지가 자동으로 정해지니 반복 지시가 눈에 띄게 줄었습니다.

셋째, 스킬을 잘 쓰면 결국 문서 쓰기 감각이 다시 부각됩니다. description을 잘 쓰는 법, 규칙을 명확히 명시하는 법, 예시를 잘 넣는 법 모두 사람용 사용자 설명서를 쓰는 감각과 정확히 같습니다.

🎯 Technical Writer와 DevRel 관점에서

skill.md는 저에게 특별한 도구가 됐습니다. Technical Writer의 감각이 그대로 살아나는 새 문서 장르라는 게 명확히 보였기 때문입니다.

• 독자를 헷갈리게 하지 않는 설명서 쓰기
• 절차를 순서대로 명확히 명시하기
• 예외 상황과 금지 사항을 미리 알려주기

이런 감각은 시즌 1 6주차에서 다룬 좋은 사용자 설명서의 원칙과 정확히 겹칩니다. 다만 독자가 사람이 아니라 AI일 뿐입니다.

DevRel과 Technical Writer 자리로 옮겨가는 여정에서 저는 이 skill.md 감각을 계속 다듬어가려 합니다. 앞으로 팀마다 **"어떤 스킬 파일을 잘 축적하고 있는가"**가 팀의 자동화 실력을 가늠하는 지표가 될 것 같거든요. 그 자리에서 좋은 스킬을 설계할 줄 아는 사람의 가치는 계속 커질 것 같습니다.

📌 정리

• skill.md 만들기 5단계: 폴더 준비 → 뼈대 잡기(프론트매터+본문+예시) → 규칙 채우기 → 도구에 등록 → 실전 테스트
• 핵심은 description: AI가 언제 이 스킬을 발동할지 판단하는 근거. 언제 발동해야 하는지의 조건까지 담기
• 본문 원칙: 리스트로 원칙 나열, 절차는 번호로 명시, 하지 말 것도 함께 명시
• 나만의 GPT와의 차이: UI가 아닌 파일 관리. 재사용성, 버전 관리, 자유도가 큰 대신 초반 진입 비용 있음
• 실전 효과: 여러 스킬을 축적하면 반복 지시가 눈에 띄게 줄어들고, 여러 도구에서 재사용 가능
• 문서 관점: skill.md 잘 쓰는 감각은 좋은 사용자 설명서 쓰는 감각과 같다

다음 글에서는 이번에 만든 blog-review 스킬을 시작으로, 비전공자가 만든 첫 자동화 워크플로를 소개해보려 합니다. 여러 스킬을 조합해서 실제로 뭔가를 자동화해본 실험기입니다. 저의 첫 자동화니만큼 시행착오도 정직하게 담아보겠습니다.

읽어주셔서 감사합니다.

---

TAG: #skillmd #ClaudeSkills #Anthropic #AI스킬파일 #자동화튜토리얼 #DevRel준비 #DocsToDevRel #TechnicalWriter #비전공자 #AI실전