직접 만든 스킬을 한 저장소에 모아 어느 CLI에서나 설치하고, 실제로 도는지 재보기

Claude Code를 쓰면서 반복되는 일이 생기면 스킬로 만들어 두었습니다. 정해진 형식으로 MR 본문을 쓰는 것, 다른 스킬이 어떻게 도는지 그려 보는 것 같은 일들입니다. 문제는 그 스킬들이 기기마다, 프로젝트마다 흩어졌다는 점입니다. Codex 같은 다른 CLI도 병행해서 쓰고 있었습니다.

soohan-skills는 그 스킬들을 모아두는 저장소입니다. 일종의 도구 저장소입니다. 파일을 한곳에 두는 데서 끝내지 않고 저장소로 만든 이유는 네 가지였습니다. 흩어진 것을 한곳에 두고 싶었고, 남도 설치할 수 있게 하고 싶었고, 늘어날수록 구조를 강제하고 싶었고, Claude Code의 플러그인 시스템이 어떻게 생겼는지 궁금했습니다.

들어 있는 것

플러그인의 원본은 plugins/ 디렉터리 하나입니다. 플러그인마다 plugin.json 하나와 스킬 디렉터리가 있고, Claude Code가 읽는 marketplace.json은 커밋할 때 pre-commit 훅이 그 디렉터리를 훑어 다시 만듭니다. 손으로 고쳐도 다음 커밋에서 덮어써지고, 이름이 디렉터리명과 다르거나 태그가 없으면 커밋이 막힙니다. 구조를 강제하고 싶었던 부분이 여기입니다.

한 원본, 두 채널

SKILL.md는 Claude Code만의 형식이 아니라 여러 CLI가 읽는 공개 표준입니다. 그래서 런타임마다 사본을 두지 않고 원본 하나를 두 경로로 배포합니다.

curl -fsSL https://raw.githubusercontent.com/soohanpark/soohan-skills/main/install.sh | bash

install.sh는 ~/.codex, ~/.gemini, ~/.kimi, ~/.agents가 있는지 보고 각각의 skills/ 디렉터리에 스킬을 복사합니다. 의존성 없는 bash로 둔 것은 Node도 이 저장소도 없는 기기에서 이 한 줄로 끝나야 했기 때문입니다. 복사하면서 두 가지를 손봅니다. 표준은 name이 디렉터리명과 같기를 요구하는데 원본은 explain처럼 짧은 안쪽 이름을 쓰므로, 설치 디렉터리를 플러그인 이름으로 만들고 frontmatter의 name을 거기에 맞춰 고쳐 씁니다. 슬래시 커맨드는 Claude Code 전용이라 복사하지 않습니다. 다른 CLI에서는 스킬이 description만 보고 발동하므로, 그 문구가 커맨드 없이도 통할 만큼 구체적이어야 합니다.

사본을 두지 않는다는 규칙은 스킬 본문에도 걸립니다. 같은 파일을 모든 호스트가 읽으니 AskUserQuestion이나 Write 같은 Claude 전용 도구 이름을 본문에 쓰지 않습니다. "사용자에게 묻는다", "파일 쓰기 도구"처럼 적고, Claude의 이름은 여러 호스트 중 하나의 예로만 듭니다. 사본이 두 개가 되는 순간 둘이 갈라진다는 것이 이 규칙을 둔 이유입니다.

스킬이 실제로 도는지 재보기

스킬을 몇 개 만들고 나니, 그게 잘 동작하는지 테스트하는 도구를 만들어 보고 싶었습니다. score는 스킬 하나를 헤드리스 CLI로 실제로 돌려 세 가지를 잽니다. 자연어만 줬을 때 발동하는가, 스킬이 있을 때가 없을 때보다 나은가, 그 차이가 토큰값을 하는가. 발동은 케이스마다 세 번 돌려 다수결로 정합니다. 품질은 SKILL.md 본문을 쥐여준 실행과 플러그인을 아예 싣지 않은 실행을 짝지어, 별도의 심판 호출이 순서를 뒤집어 두 번 비교합니다.

만들면서 알게 된 것은 측정 도구보다 측정 환경 쪽에 있었습니다.

• 발동 실패 10건 중 9건이 description 탓이 아니었습니다. 전역으로 설치된 다른 플러그인의 훅이 단 하나뿐인 턴을 먼저 가져갔습니다. 유저 스코프를 빼고 대상 플러그인만 실어 돌리자 세션에 보이는 스킬이 66개에서 23개로 줄었고, 그제야 description이 점수를 정하게 됐습니다.
• 발동을 1턴 안에 재면 54런 중 47런이 잘렸습니다. 모델이 "그 스킬을 쓰겠다"고 말하고 탐색에 첫 턴을 쓰면 스킬 호출 전에 끊깁니다. 그래서 정찰 1턴을 허용해 2턴으로 재고, 즉시 발동과 정찰 후 발동을 갈라서 보여줍니다.
• 헤드리스 실행이 세션의 도구 149개를 그대로 상속했고 그중 116개가 연결된 MCP 서버였습니다. 평가 실행이 업무용 Slack MCP를 호출한 일이 실제로 있었습니다. MCP를 끊고, 실행이 끝난 뒤에도 남는 일을 만드는 도구를 막아 15개만 남겼습니다. Bash·Read·Write·Edit 같은 작업 도구는 남겼습니다. 일할 능력까지 뺏으면 도구가 없어서 진 것을 품질 문제로 읽게 되기 때문입니다.

이런 일을 몇 번 겪은 뒤 판정을 합격·불합격 둘에서 판정 불가를 더한 셋으로 바꿨습니다. 실행 에러로 분모에서 빠진 케이스가 있으면 남은 한 케이스가 100%를 만들어 게이트를 통과시키는 일이 있었습니다. 측정이 성립하지 않았는데 합격이 찍히는 것이 이 도구가 가장 경계하는 모양입니다.

안 만든 것과 바꾼 것

처음 설계에서 뺀 것이 셋 있습니다. 남의 플러그인을 카탈로그에 올리는 외부 큐레이션, 웹 카탈로그 화면, 사용 통계입니다. 나중에 붙일 수 있는 구조만 남기고 만들지 않았습니다.

바꾼 것도 있습니다. 첫 플러그인은 dry-skill이었습니다. 다른 스킬을 실행하지 않은 채 어떤 도구를 부를지와 그 결과를 시뮬레이션해 보여주는 스킬이었는데, 8월에 skill-lab:explain으로 방향을 바꿨습니다. 시뮬레이션 결과와 바뀔 파일을 보여주는 틀을 걷어내고, 스킬이 어떻게 도는지 다이어그램과 단계 표로 설명하는 데서 멈춥니다. 그때 플러그인의 단위도 바꿨습니다. dry-skill, blin-mr, skill-eval처럼 도구 하나가 플러그인 하나였던 것을 skill-lab, work, document처럼 영역 하나로 묶었습니다. install.sh가 설치 디렉터리를 플러그인 이름으로 짓되 스킬이 둘 이상이면 플러그인-스킬로 짓는 규칙은 이때 생겼습니다.

지금

자주 쓰지는 않지만 간간히 씁니다. 완성된 물건이 아니라 쓰면서 계속 고치는 저장소입니다.

score는 그중 가장 덜 돌립니다. 한 번 재는 데 케이스 5~7건 기준 2.6~4.6달러가 듭니다. 케이스 하나가 실제 에이전트 세션 다섯 개이고, 그 위에 심판 호출이 쌍마다 두 번 붙기 때문입니다. 8월에 비용을 파헤쳐 보니 값을 정하는 것은 모델이 생각한 양이 아니라 CLI를 몇 번 띄웠는가와 매번 새로 쓰는 시스템 프롬프트 캐시였습니다. 격리하려고 실행마다 새 임시 디렉터리를 cwd로 주자 그 경로가 시스템 프롬프트 앞머리에 박혀 모든 런이 캐시 프리픽스를 통째로 새로 썼습니다. 격리가 의도치 않게 만든 비용입니다. 동적 섹션을 프롬프트 앞머리에서 빼자 발동 측정 한 번이 0.056달러에서 0.027달러로, 심판 호출의 도구 정의를 비우자 심판 한 번이 0.068달러에서 0.011달러로 줄었습니다. 이 작업은 아직 브랜치에 있고 main에 합치지 않았습니다.

이 글도 그 저장소의 writing-post 절차로 썼습니다. 이 블로그의 글 규칙이 그 스킬을 가리키고, 스킬의 절차는 이 블로그에 올라간 글쓰기 리서치에서 나왔습니다.