스킬 170개 중 90개가 한 번도 안 떴습니다

"꼭 필요한 스킬 10개", "90%가 모르는 스킬 3개" — 이런 제목을 보면 저장하게 됩니다. 저도 그렇게 모으다 보니 170개가 됐습니다.

그런데 정작 쓰는 건 늘 쓰던 것뿐이었습니다. 클로드가 알아서 꺼내 쓸 줄 알았는데 아무것도 안 하고 있었던 겁니다.

직접 세어봤습니다. 170개 중 90개, 절반이 넘는 게 한 번도 뜨지 않았습니다.

스킬은 어디에 있고, 어떻게 확인하나요

스킬을 받으면 ~/.claude/skills/ 폴더에 넣습니다. 각 스킬은 폴더 하나이고, 그 안에 SKILL.md 파일이 전부입니다.

~/.claude/skills/
  ├── blog-writer/
  │   └── SKILL.md
  ├── verification-loop/
  │   └── SKILL.md
  └── marketing-agent/
      └── SKILL.md

Claude Code 터미널에서 /skills를 치면 설치된 목록을 볼 수 있습니다. 또는 ls ~/.claude/skills/로 직접 확인해도 됩니다.

SKILL.md를 열면 파일 맨 위에 이런 블록이 있습니다:

---
name: blog-writer
description: "Helps with blog writing tasks."
---

# Blog Writer
...

description 한 줄 — 클로드는 이 줄만 보고 "이 스킬을 지금 꺼낼지 말지"를 판단합니다.

왜 안 뜨는 걸까요

스킬이 나쁜 게 아닙니다. description에 정보가 없었던 겁니다.

description을 어떻게 고치면 되나요

언제 써야 하는지와 내가 실제로 치는 말을 넣으면 됩니다.

description: "A comprehensive
  verification system for
  Claude Code sessions."

description: |
  Use when verifying code.
  Triggers on "이거 맞아?",
  "한번 확인해봐", "검증해줘",
  배포 전 체크, 코드 리뷰 시.

저장하면 재시작 없이 다음 대화부터 바뀐 description으로 동작합니다.

내 트리거를 직접 설계하는 방법

아래 틀을 복사해서 쓰면 됩니다.

description: |
  Use when [어떤 상황].
  Triggers on "[내가 실제로 치는 말 1]",
  "[내가 실제로 치는 말 2]".
  한국어: "[한국어 표현]".

작성할 때 스스로에게 물어볼 것들:

• 이 스킬을 쓰고 싶을 때 클로드에게 어떻게 말하나요? 그 문장을 그대로 넣습니다.
• 이 스킬이 필요한 상황은 어떤 작업 중인가요? 그 맥락을 씁니다.
• 비슷하지만 이 스킬을 쓰면 안 되는 상황이 있나요? 구분 기준을 씁니다.

남이 만든 스킬이 유독 안 뜨는 이유

트리거가 그 사람이 쓰는 말 기준으로 걸려 있기 때문입니다.

영어권 개발자가 만든 스킬이면 트리거가 이렇게 돼 있습니다:

Triggers on "deploy", "ship it", "push to prod".

저는 "배포해줘", "올려봐", "운영에 올리자"라고 씁니다. 키워드가 하나도 안 겹칩니다. 당연히 안 뜹니다.

제 스킬 170개 중 한국어 표현이 들어간 건 4%였습니다. 나머지 96%는 영어 트리거만 있었습니다.

description: "Marketing agent
  for app promotion and
  content creation."

description: |
  Use when marketing an app.
  Triggers on "이 앱 마케팅
  시작해줘", "마케팅 다음 단계",
  ASO·카드뉴스·블로그 요청 시.

고쳐도 안 뜨는 경우 4가지

진단 스크립트 — 내 스킬 상태를 한번에 확인

스킬마다 하나씩 열어서 확인하는 건 번거롭습니다. 아래 스크립트를 받아서 실행하면 설치된 스킬 전체를 한번에 진단합니다.

Node.js만 있으면 됩니다. 아무것도 설치하지 않아도 바로 실행됩니다.

node check-skills.mjs

# 결과 예시
스킬 170개

  뜬다      79개  46%
  애매       1개   1%
  안 뜬다   90개  53%

  한국어 트리거가 들어간 스킬: 6개 (4%)

⚠ 트리거 이전의 문제
  [srt-whiteboard-animation] 파일명이 skill.md → 맥·리눅스에서 안 읽힙니다

확인한 뒤 다음 단계가 뭔지 모르는 분들께

check-skills.mjs 결과를 보면 "안 뜬다"는 스킬 목록이 나옵니다. 이걸 어떻게 고쳐야 하는지 막막하다면, 결과 전체를 Claude에 붙여넣고 이렇게 입력하면 됩니다.

Claude가 각 스킬의 description 수정안을 바로 만들어줍니다. 파일 경로까지 알려주기 때문에 복붙만 하면 됩니다.

실제로 동작하는 트리거 예시

아래는 제가 실제로 쓰고 있는 트리거입니다. 같은 방식으로 내 말 기준으로 바꾸면 됩니다.

위 트리거는 제 스킬의 description 맨 끝에 한국어 트리거: '말 그대로 이렇게 씁니다' 형태로 추가해놓은 것들입니다. 내 스킬에도 같은 방식으로 추가하면 됩니다.