Skills

문제

스킬을 계속 만드는데 어떤 것은 모델이 알아서 부르고 어떤 것은 그러면 안 되는지 판단하기 어렵습니다. 커밋·초기화처럼 부작용 있는 스킬까지 모델이 자율로 트리거하면 위험합니다.

이유

skillOverrides에 걸 수 있는 값은 네 가지입니다. off는 모델·사람 양쪽에서 숨깁니다. user-invocable-only는 모델에게는 숨기고 /name으로만 부를 수 있게 남깁니다. name-only는 description 없이 이름만 보여줍니다. 값이 없으면 on입니다. 판단 기준은 도구 종류가 아니라 부작용 유무입니다. allowed-tools가 Read·Bash처럼 읽기 전용이면 모델 자율 호출을 허용하고, 커밋·초기화·외부 발송처럼 되돌리기 어려운 스킬은 user-invocable-only로 잠급니다.

“이 스킬이 왜 한 번도 안 걸리는가”를 진단할 때 1순위로 볼 지점이 여기입니다. 본문이나 description을 고치기 전에 user-invocable-only부터 확인합니다. 세션 중 override를 지우면 목록에 즉시 나타납니다. 설정이 라이브 리로드된다는 뜻이고, 수정이 적용됐다는 증거로도 쓸 수 있습니다.

등록 방법은 하나만 실제로 동작합니다. 전역 등록은 ~/.claude/skills/{name}/SKILL.md입니다. 레포에 .claude-plugin/plugin.json과 skills/를 갖춰 두어도 그것만으로는 자동 인식되지 않습니다. 실제로 동작하는 방법은 심링크입니다.

사용량 카운터를 볼 때는 어느 카운터인지부터 확인합니다. 스킬 쪽 lastUsedAt은 실제 디스패치에만 기록되므로 신뢰할 수 있지만, 플러그인 쪽은 설치 시점에 시드되는 값이라 다르게 읽어야 합니다. 두 카운터의 차이는 Plugins에서 다룹니다.

스킬을 만들었다는 것과 스킬이 쓰인다는 것은 다른 사실입니다. 만든 지 얼마 안 된 스킬이라도 호출 이력이 늘지 않고 멈춰 있다면, 본문을 고치기보다 이 스킬이 애초에 필요했는지부터 재검토하는 편이 낫습니다. 스킬은 만드는 비용이 낮은 만큼 쌓이기도 쉽습니다. 새로 만들기 전에 기존 스킬을 넓혀 쓸 수 없는지부터 봅니다. CLAUDE.md 한 줄이나 기존 스킬처럼 더 작은 수단으로 되는 일이면 그것으로 끝냅니다.

본문에 “실행하지 말 것”을 명시하면 남용이 줄어들기 쉽습니다. 부작용 있는 스킬은 “코드 리뷰해줘” 같은 자연어 요청으로는 실행되지 않는다고 본문에 못박고, 남용 변명별 반박 표를 둡니다.

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

읽기 전용 조회 스킬에는 이런 반박 표가 필요 없습니다. 잘못 걸려도 되돌릴 수 없는 일이 일어나지 않기 때문입니다. 반박 표는 부작용 있는 스킬에만 둡니다.

스킬은 두 종류입니다

무엇을 스킬로 만들지 판단할 때, 부작용 유무보다 먼저 보는 축이 있습니다.

	도메인 스킬	프로세스 스킬
담는 것	특정 라이브러리·서비스·코드베이스의 지식	매번 같은 순서로 하는 일
필요한 때	그 대상을 다룰 때만	작업 종류가 맞을 때마다
호출 방식	모델 자율 호출	게이트를 걸어 순서를 강제
실패하는 방식	필요할 때 안 걸림	건너뛰고 진행됨

도메인 스킬은 모델이 알아서 불러야 값이 있습니다. 사람이 그 스킬의 존재를 기억해야만 쓰이는 지식은 실제로는 쓰이지 않기 쉽습니다. 그래서 description은 검색어처럼 씁니다. 그 지식이 필요한 순간에 모델이 떠올릴 단어를 넣습니다.

이것이 도메인 지식을 CLAUDE.md에 넣지 않는 이유이기도 합니다. CLAUDE.md는 매 세션 로드되지만 도메인 지식은 가끔만 관련이 있습니다. 관련 없는 세션에서는 잡음이 되고, 문서가 길어질수록 정작 지켜야 할 규칙이 묻힙니다.

프로세스 스킬은 반대입니다. 목적이 순서를 강제하는 것이므로, 모델이 “이번에는 건너뛰어도 되겠다”고 판단할 여지를 남기면 의미가 없습니다. 부작용까지 있다면 수동 호출로 잠급니다.

도메인 스킬은 프로젝트마다 새로 생기기 때문에 더 빨리 쌓입니다. 프로세스 스킬은 적은 수가 오래 쓰입니다. 그래서 생태계에서 가져다 쓸 수 있는 것이 대개 이쪽입니다.

예시

조회 스킬은 allowed-tools를 읽기 전용으로 좁혀 모델 자율 호출을 허용합니다.

---
name: docs-lookup
description: 도구·빌드·테스트 오류가 발생했거나 라이브러리·설정·API가 낯설 때 관련 문서를 찾습니다
allowed-tools: Read, Bash
---

부작용 있는 스킬은 settings.json에서 수동 호출만 남깁니다.

"skillOverrides": {
  "git-commit": "user-invocable-only"
}

전역 등록은 심링크로 합니다.

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

하지 말 것

스킬을 계속 새로 만들기. 만든 스킬이 쌓이기만 하고 실제로는 거의 안 걸리는 경우가 드물지 않습니다. 만드는 것과 쓰이는 것은 다른 문제입니다.

“이 스킬이 왜 안 걸리지”를 본문부터 고치기. user-invocable-only부터 확인하는 것이 먼저입니다. 구조적으로 모델에게 보이지 않으면 본문을 아무리 고쳐도 소용없습니다.

lastUsedAt만 보고 “이 스킬은 안 쓰인다”고 판단하기. 플러그인 쪽 lastUsedAt은 설치 시점에 시드되므로 usageCount도 같이 봐야 합니다.

Skills

문제

추천

이유

스킬은 두 종류입니다

예시

하지 말 것