공용 Skill

문제

스킬을 팀에 공유하려 합니다. 전부 모델이 자율로 호출하게 두면 커밋·푸시·PR 생성 같은 스킬까지 말 한마디에 실행될까 불안합니다. 반대로 전부 수동 호출로 막으면 누구도 그 스킬의 존재를 모르고 지나갑니다.

이유

skillOverrides는 공식 문서에 없는 설정 키이지만 실제로 네 값을 받습니다.

값	동작
`off`	모델·사용자 양쪽에서 완전히 숨김
`user-invocable-only`	모델에게는 숨기고 `/name` 명시 호출만 허용
`name-only`	이름만 노출, 자율 호출 안 함
(없음)	on, 모델이 판단해서 자율 호출

이 네 값을 조회 스킬과 부작용 스킬에 반대로 적용하면 사고가 납니다. 조회 스킬을 user-invocable-only로 묶으면 그 지식에 아무도 못 닿습니다. 모델이 필요할 때 알아서 찾아 쓸 방법이 없어집니다. 반대로 커밋·푸시 스킬을 자율 호출로 열어두면 “커밋해줘”와 비슷한 뉘앙스의 말에 반응해 원치 않는 실행이 일어날 수 있습니다.

부작용 있는 스킬은 명시 호출로만 묶어 두고, 본문에도 “코드 리뷰해줘” 같은 자연어 요청으로는 실행하지 않는다는 규칙과 남용 변명별 반박 표를 넣는 방식이 효과적입니다.

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

user-invocable-only가 걸려 있으면 자연어 트리거로는 걸리지 않습니다. 실무에서 이 점을 자주 놓칩니다. 스킬이 왜 한 번도 걸리지 않는지 진단할 때 스킬 본문이나 description을 고치기 전에 이 설정부터 확인합니다.

팀에 공유하는 방법도 정해 둘 필요가 있습니다. 스킬을 별도 git repo로 관리하고 각자 ~/.claude/skills/에 심링크하는 방식은 여러 레포·여러 사람이 같은 스킬 세트를 쓰게 하는 가장 단순한 배포 경로입니다. 팀 규모가 커지면 설치 스크립트 하나로 스킬 디렉터리, 전역 지침, 훅 등록, skillOverrides까지 한 번에 맞추는 편이 사람마다 설정이 어긋나는 문제를 줄입니다.

예시

skillOverrides로 조회 스킬과 부작용 스킬을 반대로 묶는 설정입니다.

{
  "skillOverrides": {
    "docs-lookup": "on",
    "codebase-search": "on",
    "git-commit": "user-invocable-only",
    "open-pr": "user-invocable-only"
  }
}

부작용 스킬 본문 첫 줄에 넣는 방어 문구 패턴입니다.

## 실행 조건
이 스킬은 사용자가 `/git-commit`으로 명시 호출했을 때만 실행합니다.
"커밋해줘", "커밋 좀" 같은 자연어 요청은 트리거가 아닙니다.

하지 말 것

조회 스킬을 user-invocable-only로 묶기. 모델이 필요할 때 스스로 찾아 쓸 방법이 없어지고, 사람이 그 스킬 이름을 외우고 있어야만 지식에 닿습니다.

커밋·푸시·PR 생성 스킬을 자율 호출로 열어두기. “정리해서 커밋해줘” 같은 애매한 말에도 반응할 여지를 남깁니다.

팀에 배포하면서 무엇을 억제했는지 기록하지 않기. skillOverrides는 자동 발동 실패의 가장 흔한 원인입니다. 배포할 때 무엇을 막았는지와, 관련 지침이 그 스킬을 참조하고 있는지를 같이 점검합니다.

공용 Skill

문제

추천

이유

예시

하지 말 것