11장. Skills: 재사용 가능한 워크플로우
Claude Code를 며칠만 진지하게 써봐도 같은 말을 반복하게 됩니다. 코드 리뷰를 시킬 때마다 보안도 같이 보라고 말하고, 배포 전에는 환경변수와 마이그레이션을 확인하라고 다시 적고, 사용자 피드백을 정리할 때는 늘 같은 형식으로 PRD 초안을 만들라고 지시하게 되죠.
이 반복은 사소해 보이지만, 솔로 빌더에게는 꽤 비싼 낭비입니다. 내가 이미 알고 있는 절차를 매번 다시 설명해야 하기 때문입니다. Skills는 바로 이 지점을 겨냥합니다. 자주 쓰는 절차를 한 번 문서화해두면, Claude가 필요할 때 그 작업 방식을 꺼내 쓰게 만드는 장치입니다. 공식 문서의 표현을 빌리면, Skills는 Claude에게 새로운 모델을 학습시키는 기능이 아니라 내가 일하는 방식을 재사용 가능한 능력으로 포장하는 방식에 가깝습니다.12
여기서 중요한 차이가 하나 있습니다. CLAUDE.md가 프로젝트의 헌법이라면, Skill은 특정 작업을 수행하는 작업 매뉴얼입니다. Hooks가 무조건 실행되는 자동문이라면, Skill은 필요할 때 꺼내 쓰는 정교한 공구함입니다. 그리고 같은 Skill은 Claude.ai, Claude Code, API 환경에서 공통된 형태로 재사용할 수 있어, 한 번 잘 만들어두면 특정 인터페이스에만 갇히지 않는다는 장점도 있습니다.23
이 장의 핵심은 간단합니다. 잘 만든 Skill은 개인의 습관을 시스템 자산으로 바꿉니다. 오늘의 귀찮은 반복이, 내일부터는 버튼 한 번짜리 워크플로우가 되는 것입니다.
![[3부] Skills: 재사용 가능한 워크플로우](https://images.tilnote.io/pages/d548a40d-fa2d-4e34-98ba-50c202c87ad4.webp)
10.1 Skill의 구조: SKILL.md와 보조 파일
Skill의 기본 단위는 폴더 하나입니다. 그 안에 꼭 필요한 진입점이 SKILL.md이고, 필요하면 예제 파일, 체크리스트, 템플릿, 스크립트를 같이 넣습니다.1
예를 들어 릴리스 전 점검용 Skill은 이렇게 생길 수 있습니다.
.claude/skills/
release-check/
SKILL.md
checklist.md
templates/
release-note.md
scripts/
verify.sh이 구조가 좋은 이유는 아주 실용적입니다.
SKILL.md에는 핵심 지침만 넣을 수 있습니다.긴 체크리스트나 템플릿은 별도 파일로 분리할 수 있습니다.
필요할 때만 자세한 자료를 읽게 만들어 컨텍스트 낭비를 줄일 수 있습니다.
초보자가 Skill을 만들 때 가장 많이 하는 실수는 SKILL.md에 모든 것을 다 때려 넣는 것입니다. 하지만 좋은 Skill은 본문이 짧고 선명합니다. 핵심 원칙, 실행 순서, 출력 형식만 적고, 자세한 내용은 보조 파일로 넘깁니다. Claude는 처음부터 전체 매뉴얼을 통째로 읽는 것이 아니라, 우선 Skill의 이름과 설명 같은 가벼운 메타데이터를 보고 관련성이 있을 때 본문과 보조 파일을 더 읽는 식으로 동작합니다.2
즉, Skill 설계의 첫 번째 원칙은 압축입니다. 사람에게도 설명이 짧고 명확해야 잘 먹히듯, 에이전트에게도 마찬가지입니다.
기본적인 SKILL.md는 보통 이런 모습입니다.
---
name: release-check
description: 릴리스 직전 변경사항, 테스트, 환경변수, 마이그레이션, 롤백 계획을 점검할 때 사용한다
argument-hint: [version]
disable-model-invocation: true
allowed-tools: Read Grep Bash(git status) Bash(npm test)
---
# Release Check
다음 순서로 점검한다.
1. 현재 변경 범위를 확인한다.
2. 테스트 상태를 확인한다.
3. 환경변수와 마이그레이션 위험을 점검한다.
4. templates/release-note.md 형식으로 릴리스 노트를 작성한다.
5. 누락 항목이 있으면 배포를 보류하라고 명시한다.
자세한 체크 항목은 checklist.md를 읽고 따른다.여기서 특히 중요한 것은 description입니다. 많은 사람이 이름만 신경 쓰는데, 실제로 Claude가 자동 호출 여부를 판단할 때 더 중요하게 보는 것은 설명입니다. 설명은 단순한 소개 문장이 아니라, 일종의 라우팅 규칙입니다. 무엇을 하는 Skill인지뿐 아니라 언제 써야 하는지를 함께 적어야 합니다.1
예를 들어 좋은 커밋 메시지를 작성한다보다 스테이징된 변경사항을 분석해 Conventional Commits 형식으로 커밋 메시지를 만들 때 사용한다가 훨씬 낫습니다. 전자는 소개이고, 후자는 발동 조건이 있는 설명입니다.
Skill을 어디에 두느냐도 중요합니다. 개인 전역용이라면 ~/.claude/skills/에, 특정 프로젝트 전용이라면 .claude/skills/에 둡니다.1 이 구분은 생각보다 큽니다. 전역 Skill은 내 직업 습관이고, 프로젝트 Skill은 그 코드베이스의 운영 방식입니다. 솔로 빌더는 둘을 섞지 않는 것만으로도 머리가 훨씬 맑아집니다.
10.2 자동 호출 vs 수동 호출
Skill은 두 가지 방식으로 일할 수 있습니다. Claude가 알아서 불러오는 자동 호출과, 내가 /skill-name으로 직접 실행하는 수동 호출입니다.1
처음에는 자동 호출이 더 멋져 보입니다. 마치 비서가 눈치껏 움직이는 것 같으니까요. 하지만 솔로 빌더에게 중요한 것은 멋짐보다 통제입니다. 어떤 Skill은 자동으로 불러오는 것이 좋고, 어떤 Skill은 절대로 자동 실행되면 안 됩니다.
구분 기준은 의외로 단순합니다.
읽고 판단하는 작업이면 자동 호출에 잘 맞습니다.
외부 상태를 바꾸는 작업이면 수동 호출이 안전합니다.
긴 분석이나 대규모 탐색이면 서브에이전트와 분리 실행을 고려할 만합니다.
예를 들어 api-conventions, security-review, copy-style 같은 Skill은 자동 호출에 잘 어울립니다. 코드를 쓰거나 문서를 작성하는 흐름 속에서 관련성이 생기면 자동으로 읽혀도 부작용이 거의 없기 때문입니다.
반대로 /deploy, /publish-changelog, /send-report 같은 Skill은 자동 실행되면 곤란합니다. 코드가 얼추 완성돼 보인다고 해서 Claude가 마음대로 배포 버튼을 누르면 안 되기 때문이죠. 이런 경우에는 frontmatter에 disable-model-invocation: true를 넣어, 사용자가 직접 호출할 때만 실행되도록 하는 것이 정석입니다.1
예시는 이렇습니다.
---
name: deploy
description: 운영 배포 절차를 실행한다
disable-model-invocation: true
allowed-tools: Bash(npm test) Bash(npm run build) Bash(deploy *) Read
---이 한 줄이 주는 의미는 큽니다. Claude가 똑똑해지는 대신, 당신이 사장으로 남는다는 뜻이니까요.
반대로 사용자가 직접 부를 필요는 없고, Claude가 배경 지식처럼 참고하면 좋은 Skill도 있습니다. 이런 경우에는 user-invocable: false를 써서 슬래시 메뉴에서는 숨기고, 관련 상황에서만 자동으로 읽히게 할 수 있습니다.1 예를 들면 레거시 인증 구조 설명, 사내 API 응답 규약, 오래된 마이그레이션 금기사항 같은 것들입니다.
정리하면 이렇습니다. 자동 호출은 조언자 역할에 가깝고, 수동 호출은 실행자 역할에 가깝습니다. Skill을 설계할 때는 먼저 묻는 편이 좋습니다. 이 Skill이 판단을 돕는가, 아니면 실제 행동을 일으키는가? 이 질문 하나로 대부분의 설정이 정리됩니다.
10.3 회사/팀 표준을 Skill로 코드화하기
이 책의 독자는 대기업 개발 조직보다 혼자 제품을 만드는 사람에 더 가깝습니다. 그래서 회사 표준을 Skill로 코드화하라는 말을 들으면 약간 멀게 느껴질 수 있습니다. 하지만 솔로 빌더에게도 표준은 필요합니다. 다만 이름이 거창하지 않을 뿐입니다.
솔로 빌더의 표준은 결국 미래의 나를 위한 운영 문서입니다.
오늘의 나는 맥락을 알고 있습니다. 왜 이 API는 낙관적 업데이트를 쓰는지, 왜 결제 관련 코드는 로그를 더 남기는지, 왜 배포 전에는 꼭 환불 시나리오를 한 번 더 보는지 기억하고 있죠. 문제는 한 달 뒤의 내가 그걸 잊는다는 데 있습니다. Skill은 이 기억의 손실을 막아줍니다.
제가 추천하는 구조는 3층입니다.
CLAUDE.md에는 항상 지켜야 할 규칙을 둡니다.Skills에는 반복 절차와 체크리스트를 둡니다.Hooks에는 반드시 강제해야 할 자동 검사를 둡니다.12
예를 들어 모든 API는 TypeScript 타입을 명시한다는 규칙은 CLAUDE.md에 어울립니다. 배포 전에는 테스트, 환경변수, 마이그레이션, 롤백 계획을 확인한다는 절차는 Skill에 어울립니다. 파일 저장 후 lint를 반드시 돌린다는 것은 Hook에 어울립니다.
이 구분을 잘하면 Claude Code 설정이 놀랄 만큼 단순해집니다. 반대로 이 구분이 없으면 모든 것이 CLAUDE.md에 몰리고, 결국 헌법이 전화번호부처럼 두꺼워집니다.
솔로 빌더가 먼저 만들어야 할 Skill은 대체로 다음 다섯 가지입니다.
코드 리뷰 Skill: 보안, 성능, 누락 테스트, 복잡도 확인
릴리스 점검 Skill: 테스트, 마이그레이션, 환경변수, 롤백 확인
버그 트리아지 Skill: 재현 경로, 영향 범위, 우선순위 정리
피드백 정리 Skill: 사용자 메시지를 문제 정의와 기능 가설로 변환
문서화 Skill: 변경사항을 README, CHANGELOG, 운영 노트로 반영
핵심은 거창한 범용 Skill을 만들지 않는 것입니다. 처음부터 만능 비서를 만들려고 하면 거의 실패합니다. 대신 내가 자주 반복하는 일 하나를 고르고, 그 일의 입력과 출력이 무엇인지부터 고정하세요.
예를 들어 고객 피드백을 기능 기획으로 바꾸는 일이 자주 있다면, 이런 식의 Skill이 좋습니다.
---
name: feedback-to-prd
description: 고객 피드백, 인터뷰 메모, CS 내용을 기능 기획 초안으로 정리할 때 사용한다
argument-hint: [source-file]
---
입력 자료를 읽고 다음 순서로 정리한다.
1. 사용자 문제를 한 문단으로 요약한다.
2. 반복적으로 등장한 불만을 묶는다.
3. 해결 가설을 2개 이상 제시한다.
4. 가장 작은 구현 범위를 MVP로 제안한다.
5. 리스크와 측정 지표를 함께 적는다.
출력은 다음 섹션을 반드시 포함한다.
- 문제 정의
- 사용자 시나리오
- 제안 기능
- 제외 범위
- 성공 지표이 정도만 있어도 엄청난 변화가 생깁니다. 예전에는 머릿속 습관에 의존하던 작업이, 이제는 재사용 가능한 프로세스로 바뀝니다. 프로젝트를 옮겨도 남고, 몇 주 쉬었다 돌아와도 남고, 나중에 협업자가 생겨도 그대로 건넬 수 있습니다.
좋은 Skill은 나의 감각을 대체하지 않습니다. 대신 감각이 흔들릴 때 기본 자세를 복구해줍니다. 피곤한 밤에도 품질이 무너지지 않게 하는 안전장치라고 생각하면 이해가 쉽습니다.
10.4 Skill 마켓플레이스와 공유 전략
Skill의 매력은 직접 만드는 데만 있지 않습니다. 이미 잘 만들어진 것을 가져와 내 방식으로 바꿔 쓰는 데에도 있습니다. Anthropic은 Skills를 만드는 전용 흐름과 예시를 제공하고 있고, 공개된 Skill 라이브러리와 커뮤니티 컬렉션도 빠르게 커지고 있습니다.34
하지만 여기서 중요한 태도는 설치보다 편집입니다. 남이 만든 Skill을 그대로 쓰면, 보통은 내 프로젝트와 어긋납니다. 체크리스트 순서가 다르고, 출력 형식이 다르고, 전제가 되는 도구 체인도 다릅니다. 좋은 솔로 빌더는 마켓플레이스를 앱스토어처럼 소비하지 않습니다. 오히려 잘 만든 Skill을 해부해서 자기 운영체제에 이식합니다.
공유 전략은 범위에 따라 나누면 깔끔합니다.
개인 습관은
~/.claude/skills/에 둡니다.프로젝트 규칙은
.claude/skills/에 두고 저장소에 커밋합니다.여러 프로젝트에 공통으로 쓰는 것은 별도 템플릿 저장소로 관리합니다.
외부 공개용은 민감한 전제와 내부 표현을 제거한 뒤 배포합니다.
이렇게 나누면 Skill이 쌓일수록 더 편해집니다. 반대로 범위를 섞어두면, 결제 서비스 배포 Skill이 블로그 프로젝트에 튀어나오고, 콘텐츠 작성 Skill이 백엔드 저장소에서 괜히 자동 발동하는 일이 생깁니다.
공개 Skill을 가져올 때는 보안 감각도 필요합니다. Skill은 단순한 문서처럼 보이지만, 스크립트와 보조 파일을 포함할 수 있습니다. 즉, 설명문만 읽고 설치할 것이 아니라 SKILL.md, 스크립트, 참조 파일을 함께 검토해야 합니다. 특히 비밀값 하드코딩, 위험한 셸 명령, 불필요한 외부 의존성은 꼭 확인해야 합니다.5
그래서 공개 Skill을 도입할 때는 다음 순서를 권합니다.
바로 설치하지 말고 먼저 읽습니다.
설명보다 실제 지침과 스크립트를 봅니다.
내 프로젝트 용어와 절차에 맞게 이름과 설명을 다시 씁니다.
처음에는 읽기 전용 또는 저위험 작업부터 연결합니다.
이 과정을 거치면 Skill 마켓플레이스는 장난감 상자가 아니라 가속 장치가 됩니다. 특히 혼자 일하는 사람에게는 더 그렇습니다. 혼자서는 모든 걸 처음부터 만들기 어렵지만, 남의 초안을 잘 고쳐 쓰는 사람은 훨씬 빨리 자기 체계를 만듭니다.
잘 만든 Skill은 습관의 컴파일 결과다
이 장에서 꼭 남기고 싶은 문장은 하나입니다. Skill은 프롬프트 저장 기능이 아닙니다. 내 작업 방식을 컴파일해 재실행 가능하게 만드는 구조입니다.
잘 만든 Skill은 이런 특징을 가집니다.
언제 써야 하는지가 설명만 봐도 분명합니다.
입력과 출력 형식이 흔들리지 않습니다.
본문은 짧고, 자세한 내용은 보조 파일로 분리돼 있습니다.
자동 호출과 수동 호출의 경계가 분명합니다.
미래의 나 또는 새로운 협업자가 바로 쓸 수 있습니다.
솔로 빌더에게 가장 큰 생산성 도약은 더 똑똑한 모델만으로 오지 않습니다. 내가 자주 하는 좋은 판단을 재사용 가능한 형태로 남길 때 옵니다. 오늘 /review, /release-check, /feedback-to-prd 같은 Skill 세 개만 제대로 만들어도, 내일부터 Claude Code는 단순한 조수가 아니라 내 방식으로 일하는 작은 운영팀이 됩니다.
참고
1Claude를 skills로 확장하기 - Claude Code Docs
2Skills explained: How Skills compares to prompts, Projects, MCP, and subagents
3Teach Claude your way of working
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.