한눈에 보기
- Claude Code 스킬은 직접 만들기 전에 기본 제공 스킬 다섯 개부터 써 보는 것이 가장 부담이 적다. 여기서는
/verify,/run-skill-generator,/doctor,/skill-doctor,/claude-api를 골랐다. - 이 순서는 인기 순위가 아니다. 사용 통계를 확인할 수 없어서, 특정 작업에 묶이지 않고 바로 시도할 수 있는 것을 필자가 골랐다.
- 스킬은
SKILL.md파일이 든 디렉터리다. 본문은 쓸 때만 불러오므로 긴 참고 자료를 넣어 둬도 평소 비용이 작다. - 저장소에 들어 있는 스킬의
allowed-tools는 신뢰 대화상자와 상관없이 적용될 수 있다. 남의 저장소나 외부 스킬은 열기 전에 확인한다.
스킬이 무엇이고 어떻게 불러오나
같은 지시를 채팅창에 계속 붙여 넣고 있다면 스킬로 옮길 때다. 스킬은 Claude Code가 스스로 불러오거나 /스킬이름으로 직접 부르는 지침 묶음이다. 예전의 .claude/commands/ 커스텀 명령도 스킬로 합쳐졌고 그대로 동작한다.
형식은 단순하다. SKILL.md 한 파일에 YAML frontmatter와 마크다운 지침을 쓴다. 모든 필드는 선택이고 description을 권장한다. Claude는 이 설명을 보고 요청에 맞을 때 스킬을 불러온다.
---description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks you notice...!`git diff HEAD` 줄은 동적 컨텍스트 주입이다. 명령이 Claude가 스킬을 보기 전에 실행되고, 출력이 그 자리를 대신한다. SKILL.md는 500줄 아래로 두고 나머지는 옆 파일로 나눠 참조하라고 안내한다.
스킬 위치에 따라 적용 범위가 달라진다. 개인 스킬은 ~/.claude/skills/<name>/SKILL.md로 모든 프로젝트에, 프로젝트 스킬은 .claude/skills/<name>/SKILL.md로 그 저장소에 적용된다. 이름이 겹치면 엔터프라이즈가 개인보다, 개인이 프로젝트보다 우선한다. 플러그인 스킬은 /플러그인이름:스킬이름으로 부른다.
추천 5개와 고른 기준
기준은 둘이다. 공식 문서에 설명이 있어서 무엇을 하는지 확인할 수 있을 것, 그리고 특정 언어나 업무에 묶이지 않고 시작할 수 있을 것. /code-review, /simplify, /batch, /debug, /loop도 기본 제공 스킬이지만, 특정 작업에 쓰는 것이라 처음 시작하는 목록에서는 뺐다.
1. /verify: 테스트 대신 실제로 돌려 확인한다
문서의 설명은 “Build and run your app to confirm a code change does what it should, without falling back to tests or type checks.”이다. 변경이 의도대로 동작하는지 앱을 빌드하고 실행해서 본다. 호출할 때만 실행되는 스킬이다.
2. /run-skill-generator: /run과 /verify에 우리 프로젝트를 가르친다
설명은 “Teach /run and /verify how to build and launch your project.”이다. 프로젝트별 실행 방법을 .claude/skills/run-<name>/에 기록한다. /verify를 쓸 계획이면 먼저 이것으로 실행 방법을 알려 주는 편이 자연스럽다. 한 번 만든 기록은 저장소에 커밋해 팀과 나눌 수 있다.
3. /doctor: 설정 상태를 한 번에 점검한다
설치 상태, 확장(안 쓰는 스킬·MCP 서버·플러그인과 느린 훅), CLAUDE.md, 권한, 사용량을 점검한다. 사용량 점검은 Claude Code v2.1.305 이상이 필요하고 Pro·Max·Ultra·Team·Enterprise 플랜에서 나온다. 먼저 결과를 보고하고 바꾸기 전에 확인을 묻는다. /doctor prompt-audit은 CLAUDE.md, 스킬 등 설정에서 오래됐거나 서로 충돌하는 지침을 찾으며 v2.1.283 이상이 필요하다. 세션을 시작하지 않고 설치 진단만 읽기 전용으로 보려면 터미널에서 claude doctor를 실행한다.
4. /skill-doctor: 스킬이 컨텍스트를 얼마나 쓰는지 본다
스킬마다 컨텍스트 비용과 사용 빈도를 보여 줘서 끌 것을 고르게 한다. 대화형 세션에서는 /plugin 관리 화면의 Stats 탭에 나오고, -p 모드에서는 텍스트로 출력한다. Claude Code v2.1.252 이상이 필요하다. 스킬을 많이 설치했다면 이 스킬이 정리의 출발점이다.
5. /claude-api: Claude API 코드를 쓸 때 참고 자료를 불러온다
프로젝트 언어에 맞는 Claude API·Managed Agents 참고 자료를 불러온다. 코드가 anthropic이나 @anthropic-ai/sdk를 import하면 Claude가 자동으로 활성화한다. 하위 명령은 migrate, upgrade, api-version, managed-agents-onboard, managed-agents-secure, prompt-audit, cost-optimize, build-eval, hillclimb, preserved-thinking-migration이고, 명령마다 필요한 Claude Code 버전이 다르다. API를 쓰지 않는 프로젝트라면 건너뛰어도 된다.
왜 중요한가: 스킬은 코드를 실행하고 도구를 허용한다
스킬은 글이 아니라 설정에 가깝다. 문서가 경고하는 점이 몇 가지 있다.
- 저장소 스킬은 도구를 허용할 수 있다.
allowed-tools는 프롬프트 없이 도구를 쓰게 하며, 작업 공간 신뢰 여부로 막히지 않는다. 신뢰하지 않는 폴더에서-p로 실행해도 프로젝트 스킬의allowed-tools가 적용된다. !`명령`은 Claude가 스킬을 보기 전에 실행된다. 허용 규칙에 없는 명령이 있으면 호출이 중단된다. 끄려면"disableSkillShellExecution": true를 설정하며, 사용자가 바꿀 수 없는 관리 설정에서 가장 유용하다고 한다.- 스킬 폴더 안의
.claude-plugin/plugin.json이 에이전트·훅·MCP 서버를 불러올 수 있다. 프로젝트의.claude/skills/에서는 작업 공간 신뢰 대화상자를 먼저 수락해야 한다. - 같은 이름의 개인·프로젝트 스킬이 기본 제공 스킬을 가릴 수 있다. 문서의 예로, 프로젝트의
code-review스킬은/code-review를 대체하지만 별칭/review는 그 스킬을 실행하지 않는다.
누구에게 어떤 영향이 있나
혼자 쓰는 개발자는 위 5개로 충분히 시작한다. 직접 만든 스킬은 처음에 하나만 두고, /skill-doctor로 비용을 보면서 늘리면 된다.
팀 저장소에 스킬을 커밋하는 쪽은 allowed-tools를 리뷰 대상에 넣어야 한다. 관리자는 allowManagedPermissionRulesOnly로 프로젝트·개인 스킬의 allowed-tools를 무시하게 할 수 있고, strictPluginOnlyCustomization에 hooks를 넣으면 hooks를 선언한 개인·프로젝트 스킬은 allowed-tools 사전 승인을 잃는다.
외부 스킬 모음이 필요하면 Anthropic의 anthropics/skills 저장소가 있다. 이 저장소의 스킬 다수는 Apache 2.0 오픈소스이고, docx·pdf·pptx·xlsx는 소스 공개(source-available)이지 오픈소스가 아니다. 어느 스킬이 어떤 라이선스인지는 스킬 폴더마다 확인해야 한다.
직접 해보기
- Claude Code에서
/doctor를 실행해 현재 설정의 문제를 확인한다. 바꾸기 전에 확인을 묻는다. /run-skill-generator로 프로젝트의 빌드·실행 방법을 기록하고, 코드를 바꾼 뒤/verify를 호출한다./skill-doctor로 스킬별 컨텍스트 비용을 보고 쓰지 않는 스킬은 끈다.- 같은 지시를 세 번 이상 붙여 넣었다면
.claude/skills/<이름>/SKILL.md를 만들고description에 언제 쓰는지까지 적는다. - Anthropic 예시 스킬을 써 보려면 다음을 실행한다.
/plugin marketplace add anthropics/skills/plugin install example-skills@anthropic-agent-skills설치한 뒤에는 요청에 스킬을 언급한다. 저장소 안내의 예는 “Use the PDF skill to extract the form fields from path/to/some-file.pdf.”이다. 문서 쪽 스킬은 document-skills@anthropic-agent-skills로 설치한다.
검증 범위: 스킬 형식·기본 제공 스킬 설명·보안 주의점은 스킬 문서 전체를 대조했고, 명령 목록과 allowManagedPermissionRulesOnly는 명령어 레퍼런스와 설정 레퍼런스도 대조했다(B). 설정 레퍼런스에서는 allowManagedPermissionRulesOnly 항목 일부와 strictPluginOnlyCustomization.hooks의 색인 줄만 읽었고, strictPluginOnlyCustomization과 hooks 문장의 근거는 스킬 문서다. 저장소 설치 명령과 라이선스는 저장소 소개 페이지를 대조했다. 직접 실행한 결과는 없다.
결론적으로, 스킬을 처음 쓴다면 만들기보다 /verify·/run-skill-generator·/doctor·/skill-doctor·/claude-api부터 써 보는 것이 가장 부담이 적고, 그다음에 반복하는 지시를 골라 하나씩 스킬로 옮기면 된다.
출처
이 글은 2026-11-05 기준으로 작성했습니다. 이후 달라진 내용은 2027-05-05에 확인해 이 자리에 추가합니다.