스킬 관리기가 훑는 자리를 Claude Code 가 읽는 곳으로만 줄였다

tokenbill 의 로컬 뷰어에 스킬 관리 탭을 붙이고 있다. 시작은 단순한 불편이었다. AI 를 오래 쓰다 보니 SKILL.md 파일이 PC 여기저기에 흩어졌고, 어떤 것이 실제로 읽히는 자리에 있고 어떤 것이 그냥 내려받은 채 묻혀 있는지 한눈에 알 수 없었다. 그래서 흩어진 것을 한 화면에 모아 보고, 쓰는 자리로 옮기고, 다른 PC 로 넘길 수 있게 하자는 것이 계획이었다.

처음 계획은 “넓게 훑기” 였다

처음 설계는 스캔 범위를 최대한 넓게 잡았다. Claude Code 가 읽는 개인 스킬 폴더와 플러그인 폴더는 당연히 보고, 다른 도구가 쓰는 스킬 폴더도 보고, 내려받기 폴더와 문서 폴더까지 깊이 제한을 두고 훑었다. “흩어진 것을 찾아낸다” 는 목표에 충실한 설계였다. 찾은 것마다 “설치됨” 배지를 붙이거나 [설치] 버튼을 달아, 어디에 있든 한 번 클릭으로 개인 스킬 폴더로 복사할 수 있게 했다.

그런데 화면이 나오고 나니 이상한 점이 보였다. 목록에 나오는 스킬 가운데 상당수가 Claude Code 와 아무 관계가 없는 것들이었다. 다른 도구용으로 만들어진 스킬, 어떤 패키지 안에 참고 자료로 들어 있던 SKILL.md 사본, 예전에 받아 두고 잊은 폴더가 모두 같은 목록에 섞여 있었다. 이 도구는 “Claude Code 가 지금 무엇을 읽고 있는가” 를 보여 주려는 것인데, 결과는 “내 PC 에 SKILL.md 라는 이름의 파일이 몇 개 있는가” 에 가까웠다.

하루 만에 범위를 되돌렸다

그래서 같은 날 오후에 결정을 바꿨다. 스캔 대상을 Claude Code 가 공식적으로 스킬을 읽는 세 자리로만 한정했다.

• 개인 폴더(~/.claude/skills): 어느 폴더에서 열든 읽힌다
• 프로젝트 폴더(<저장소>/.claude/skills): 그 폴더에서 열 때만 읽힌다
• 플러그인 폴더: 플러그인이 관리하므로 읽기 전용으로만 보여 준다

다른 도구의 스킬 폴더와 내려받기 폴더는 목록에서 뺐다. Claude Code 가 읽지 않는 자리에 있는 파일은, 이 화면에서는 존재하지 않는 것으로 취급하기로 했다.

이 결정에 따라 화면의 어휘도 바뀌었다. 전에는 “설치됨” 과 “설치” 였는데, 지금은 “어디서나 사용”, “이 폴더에서만”, “플러그인” 세 가지 배지로 나뉜다. 버튼도 [설치] 대신 [어디서나 쓰기] 가 됐다. 프로젝트 폴더에만 있는 스킬을 개인 폴더로 복사해, 어느 폴더에서 열든 쓸 수 있게 한다는 뜻이다. “설치” 라는 말은 바깥에서 안으로 들여온다는 느낌을 주는데, 실제로 하는 일은 이미 Claude Code 안에 있는 스킬의 적용 범위를 넓히는 것뿐이라서 이름을 바꿨다.

화면만 바꾼 것이 아니라 API 도 같이 막았다. 복사 요청이 들어오면 원본 폴더가 Claude Code 가 기억하는 프로젝트의 .claude/skills 아래에 있는지 확인하고, 아니면 거절한다. 화면에서 보이지 않더라도 경로를 직접 넣어 아무 폴더나 개인 스킬 폴더로 밀어 넣을 수 없게 한 것이다. 이 두 가지를 확인하는 테스트를 추가해 전체 21개가 통과하는 상태로 두었다.

돌아보면 처음 목표가 두 개였다

되돌리고 나서 생각해 보니, 처음 설계에는 목표가 두 개 섞여 있었다. 하나는 “Claude Code 가 지금 읽는 스킬을 관리한다” 는 것이고, 다른 하나는 “PC 에 흩어진 스킬 파일을 발굴한다” 는 것이다. 둘 다 그럴듯해서 하나의 화면에 담으려 했는데, 발굴 쪽이 관리 쪽을 흐리게 만들었다. 발굴은 어쩌다 한 번 하는 일이고 관리는 매번 하는 일이라, 매번 보는 화면에 어쩌다 한 번 쓸 정보가 섞이면 매번이 불편해진다.

이번에는 관리 쪽만 남겼다. 발굴이 필요해지면 그때 별도 기능으로 만드는 편이 낫다고 본다.

설명 한 줄 읽기가 생각보다 까다로웠다

같은 날 아침에는 더 작은 문제를 고쳤다. 스킬 목록에 각 스킬의 설명을 한 줄씩 보여 주는데, SKILL.md 의 frontmatter 에서 description: 줄을 정규식 하나로 뽑고 있었다. 한 줄짜리 설명만 가정한 코드였다.

실제 SKILL.md 들은 그렇지 않았다. 설명이 길어서 YAML 블록 문법(description: |)으로 여러 줄에 걸쳐 적힌 것이 있었고, 그런 파일에서는 설명이 | 한 글자로 나왔다. frontmatter 에 설명이 아예 없어 본문 첫 줄을 대신 쓰는 경우에는, 본문이 표로 시작하는 파일에서 | 항목 | 값 | 같은 표 머리글이 설명으로 올라왔다.

고친 방식은 단순하다. description: 뒤에 | 나 > 같은 블록 표시가 오면, 그다음에 이어지는 들여쓴 줄들을 모아 한 문장으로 잇는다. 본문에서 설명을 대신 뽑을 때는 제목, 표, 인용, 목록 기호로 시작하는 줄과 너무 짧은 줄을 건너뛴다. 완전한 YAML 파서를 들이지 않고도 실제로 마주친 형태는 다 처리된다.

작은 수정이지만 되새길 만한 점이 있었다. 내가 쓰는 SKILL.md 형식만 보고 짠 코드는, 다른 사람이 만든 스킬을 읽는 순간 바로 깨진다. 스킬 관리기는 본질적으로 남이 만든 파일을 읽는 도구라서, 형식의 다양성을 처음부터 가정했어야 했다.

남은 일

계획 문서의 마지막 단계는 단위 테스트 보강, README 와 가이드 정리, 배포다. 스캔 범위를 좁히면서 테스트와 가이드 문구는 함께 손봤고, 패키지 버전은 1.1.9 로 올렸다. 다음은 MCP 설정 탭 쪽의 토큰 마스킹과 내보내기 템플릿을 같은 눈으로 다시 보는 일이 될 것 같다.