Skills

문제

스킬 하나 새로 만들 때마다 frontmatter를 처음부터 고민합니다. 자동으로 걸려야 하는 스킬과 실수로 걸리면 안 되는 스킬을 구분 없이 같은 방식으로 만듭니다.

예시

골격

---
name: skill-name
description: 언제, 무엇을 위해 쓰는 스킬인지 한 문장. 모델은 이 문장만 보고 자동 호출
  여부를 판단한다.
argument-hint: "[선택 인자]"
allowed-tools: Read, Grep, Bash
metadata:
  type: reference
---

frontmatter 아래 본문은 Instructions/Guidelines 두 절로 구성합니다.

## Instructions

...

## Guidelines

...

name은 등록 디렉터리명과 일치해야 합니다. allowed-tools는 이 스킬 실행 중 쓸 수 있는 도구를 좁힙니다. 부작용 있는 스킬일수록 여기를 좁게 씁니다.

등록은 심링크 하나입니다.

ln -s <repo>/skills/{name}/SKILL.md ~/.claude/skills/{name}/SKILL.md

레포에 .claude-plugin/plugin.json과 skills/만 있어도 정식 설치 없이는 자동 인식되지 않습니다. 위 심링크를 만들어야 인식됩니다.

자동 호출을 허용하는 읽기 전용 조회 스킬

---
name: docs-lookup
description: 도구·빌드·테스트 오류가 발생했거나 라이브러리·설정·API가 낯설 때 내부
  문서에서 관련 패턴을 찾아 선언한다.
allowed-tools: Read, Grep, Bash
metadata:
  type: reference
---

allowed-tools가 읽기 계열뿐이면 모델이 잘못 걸려도 되돌릴 수 없는 일이 일어나지 않습니다. skillOverrides에 아무것도 넣지 않으면 기본값이 on이라 이 스킬은 그대로 자동 호출 대상입니다.

수동 호출만 받는 부작용 있는 스킬

---
name: review-code
description: 코드 리뷰를 수행한다. 반드시 /review-code로 명시
  호출했을 때만 실행한다.
argument-hint: "[PR 번호 | 브랜치 | 경로]"
allowed-tools: Read, Grep, Bash, Edit
metadata:
  type: workflow
---

본문에 자연어 남용을 막는 반박 표를 둡니다.

## 남용 방지

| 변명 | 실제 |
|---|---|
| "리뷰 요청이니 이 스킬이 맞다" | 자연어 리뷰 요청은 이 스킬의 트리거가 아니다 |
| "슬래시 없이 말해도 의도는 같다" | 의도가 같아도 명시 호출이 없으면 중단한다 |

description만으로는 자동 호출을 완전히 막지 못합니다. 실제 잠금은 전역 ~/.claude/settings.json의 skillOverrides에서 겁니다.

{
  "skillOverrides": {
    "review-code": "user-invocable-only"
  }
}

user-invocable-only는 모델에게는 숨기고 /review-code 슬래시 호출만 남깁니다. off는 둘 다 숨깁니다.

이유

스킬이 한 번도 걸리지 않을 때 먼저 확인할 곳은 skillOverrides의 user-invocable-only 설정입니다. 스킬 본문이나 description을 고치기 전에 여기부터 봅니다. 세션 중 override를 제거하면 스킬이 목록에 즉시 나타납니다. 설정이 즉시 다시 읽힌다는 뜻이므로, 수정이 적용됐는지 확인하는 데도 쓸 수 있습니다.

하지 말 것

description을 넓게 써서 자연어로도 걸리게 하기. “코드 리뷰해줘” 같은 자연어 요청까지 걸리면 부작용 있는 작업이 의도치 않게 실행됩니다.

스킬 본문에 “예외 없이 실행하라”고만 적고 끝내기. 하네스가 skillOverrides로 숨겨 두면 본문에 무엇을 적어도 모델에게 보이지 않습니다. 본문을 고치기 전에 override부터 확인합니다.

.claude-plugin/plugin.json과 skills/만 두고 전역 등록을 생략하기. 정식 설치 경로인 캐시·등록 목록·활성화 세 곳을 다 거치지 않으면 자동 인식되지 않습니다. 심링크로 등록해야 인식됩니다.

Skills

문제

추천

예시

골격

자동 호출을 허용하는 읽기 전용 조회 스킬

수동 호출만 받는 부작용 있는 스킬

이유

하지 말 것