/skills

스킬이란

스킬은 반복해서 시키는 절차나 참고 지식을 문서로 저장해 두는 방법입니다. 폴더 안의 SKILL.md가 필수이고, 필요하면 참고 문서와 스크립트를 함께 둡니다.

스킬 전체 내용은 호출될 때만 불러오므로, 긴 참고 자료를 넣어도 쓰기 전에는 비용이 적습니다. 다만 이름과 설명은 항상 컨텍스트에 들어갑니다.

my-skill/
  SKILL.md        (필수: frontmatter + 지시문)
  reference.md    (선택: 필요할 때 로드)
  scripts/        (선택: 실행용)

SKILL.md 작성법

YAML frontmatter가 파일 첫 줄부터 --- 로 둘러싸여야 하고, 그 뒤가 마크다운 지시문입니다. 모든 필드는 선택이지만 description은 권장됩니다. Claude가 이 설명을 보고 언제 불러올지 정하기 때문입니다.

• name: 명령 이름. 생략하면 폴더 이름입니다.
• description: 무엇을 하고 언제 쓰는지. when_to_use와 합쳐 1,536자 제한이 있습니다.
• disable-model-invocation: true면 나만 호출할 수 있습니다. 배포처럼 부작용이 있는 작업에 씁니다.
• user-invocable: false면 Claude만 호출하고 / 메뉴에서 숨습니다. 배경 지식용입니다.
• allowed-tools: 이 스킬이 실행되는 동안 승인 없이 쓸 도구입니다.
• $ARGUMENTS로 명령 뒤에 적은 인자를 받습니다.

---
name: deploy
description: 프로덕션에 배포한다
disable-model-invocation: true
allowed-tools: Bash(git status *)
---

$ARGUMENTS 를 프로덕션에 배포한다.
1. 테스트를 돌린다
2. 빌드한다
3. 배포 대상에 올린다

어디에 두나

• 개인: ~/.claude/skills/이름/SKILL.md. 이 컴퓨터의 모든 프로젝트에서 씁니다.
• 프로젝트: .claude/skills/이름/SKILL.md. 커밋해서 팀과 공유합니다.
• 플러그인: 플러그인의 skills/ 폴더. /플러그인이름:스킬이름으로 불립니다.
• 같은 이름이면 엔터프라이즈가 개인을, 개인이 프로젝트를 이깁니다. 플러그인 스킬은 이름에 접두어가 붙어 충돌하지 않습니다.

슬래시 명령과 훅과의 관계

예전의 사용자 정의 명령(.claude/commands/deploy.md)은 스킬에 합쳐졌습니다. 명령 파일과 스킬 폴더는 둘 다 /deploy를 만들고 기존 명령 파일도 계속 동작합니다. 새로 만든다면 스킬을 쓰라는 것이 공식 문서 입장입니다. 스킬은 지원 파일을 둘 수 있고 자동 호출이 가능합니다.

항상 지켜야 하는 규칙은 스킬이 아니라 훅이나 CLAUDE.md가 맞습니다. 스킬은 Claude가 설명을 보고 판단해 부르므로 매번 확실히 실행되는 것은 아닙니다.

실제 예시

.claude/skills/post-check/SKILL.md 에 name: post-check, description: 글 발행 전 점검, 본문에 점검 항목 목록 작성
이후 대화에서: /post-check src/posts/new.md

SKILL.md frontmatter에 disable-model-invocation: true 를 넣고, 사용할 때만 /deploy staging

흔한 실수와 쓰지 말아야 할 때

• description이 모호하면 Claude가 필요한 때에 불러오지 않거나 엉뚱한 때 불러옵니다. 언제 쓰는지를 구체적으로 적으세요.
• 스킬 파일을 만든 직후 목록에 안 보이면 /reload-skills를 실행하세요(이 사이트 명령 목록 기준).
• 부작용이 있는 스킬에 disable-model-invocation을 빼먹으면 Claude가 스스로 실행할 수 있습니다.
• 스킬을 너무 많이 켜 두면 설명이 매 턴 컨텍스트를 차지합니다. 안 쓰는 건 지우세요.
• 예전 .claude/commands 파일과 같은 이름의 스킬이 있으면 스킬이 우선합니다.

자주 묻는 질문