AI 에이전트(AI Agent)에 skill이나 slash command를 추가하면 처음에는 편리해집니다. /tdd, /diagnosing-bugs, /to-prd와 같이 작업의 유형을 이름으로 부를 수 있기 때문입니다.

하지만 수가 늘어나면 또 다른 고민이 생깁니다.

"지금 호출해야 하는 것이 /tdd인가, /diagnosing-bugs인가. 먼저 설계를 구체화해야 하는가. 아니면 issue화해야 하는가."

이 판단을 매번 그 자리에서 하고 있다면, 스킬 모음은 아직 운영 설계가 되지 않은 상태입니다. 프롬프트(Prompt)를 놓는 장소만 늘어났을 뿐입니다.

여기서 말하는 AI 에이전트는 Claude Code, Codex, Cursor와 같은 개발 지원 도구입니다. 채팅 지시를 받아 코드를 읽고, 파일을 편집하며, 테스트를 실행합니다. skill은 그 에이전트에게 읽히는 추가적인 작업 절차서입니다. slash command는 그 skill이나 작업 모드를 호출하기 위한 이름입니다.

mattpocock-skills@1.0.0의 흥미로운 점은 새로운 slash command가 늘어났다는 것이 아닙니다. AI 에이전트에게 전달할 스킬을 「누가 호출하는가」까지 설계하기 시작했다는 점에 있습니다. GitHub Release에는 이 기사에서 다루는 범위 내에서도 ask-matt의 추가, 공유 설계 스킬의 추가, 여러 개의 파괴적 변경(Breaking change), 그리고 Commands / Skills에서 User-invoked / Model-invoked로의 분류 변경이 기록되어 있습니다.

이 기사에서는 mattpocock-skills v1.0.0을 단순한 릴리스 소개가 아니라, agent skill을 팀에서 사용할 때의 설계 사례로 읽고자 합니다.

먼저, 전제를 맞추기

대상 독자는 Claude Code, Codex, Cursor 등의 AI coding agent를 일상적으로 사용하기 시작한 개발자입니다. 팀에 agent skills를 도입하려는 테크 리드(Tech Lead)에게도 유용합니다.

먼저, 세 가지만 짚고 넘어가겠습니다.

• AI 에이전트는 채팅으로 지시를 받아 개발 작업을 돕는 도구입니다.
• skill은 AI 에이전트에게 추가로 읽히는 작업 절차입니다.
• slash command는 skill이나 작업 모드를 호출하기 위한 이름입니다.

이 기사에서 다루는 것은 주로 다음 세 가지입니다.

• slash command를 늘리기 전에 User-invoked와 Model-invoked를 나누는 이유
• mattpocock-skills v1.0.0의 파괴적 변경이 팀 운영에서 어디에 효과적인가
• agent skills를 도입하기 전에 결정해 두어야 할 것

skill 이름은 곧 운영 절차가 된다

개인적인 이용이라면 스킬 이름을 기억하고 있으면 그만입니다. /diagnose가 편리했다, /grill-me가 좋았다, 라는 경험만으로도 충분합니다.

하지만 팀에서 사용하기 시작하면 스킬 이름은 문장이나 설정에 매립됩니다.

• README에 스킬 이름을 작성
• 온보딩(Onboarding) 자료에 호출 절차를 작성
• issue template이나 PRD template에 전제 skill을 작성
• agent config나 dotfiles에 도입 절차를 작성
• "이 종류의 작업에서는 먼저 이 skill을 호출한다"라는 암묵적인 규칙이 생성

이 상태에서 skill 이름이 바뀌면 단순한 이름 변경으로 끝나지 않습니다. 운영 절차가 망가집니다.

실제로 mattpocock-skills@1.0.0에서는 diagnose가 diagnosing-bugs로 개명되었고, write-a-skill은 writing-great-skills로 교체되었으며, caveman과 zoom-out은 삭제되었습니다. 릴리스 노트는 이것들을 Breaking change로 취급하고 있습니다.

agent skills는 「편리한 명령 모음」이라기보다, 팀의 개발 워크플로우(Workflow)에 들어가는 의존물입니다. 그렇기에 호출 방식과 업데이트 방법을 미리 결정해 두어야 합니다.

User-invoked와 Model-invoked를 나누기

mattpocock/skills의 docs/invocation.md는 스킬을 두 종류로 나누고 있습니다.

• User-invoked: 인간이 이름을 입력했을 때만 도달할 수 있습니다. 입구, 판단, 오케스트레이션 (Orchestration)에 적합합니다.
• Model-invoked: 인간과 모델 모두 도달할 수 있습니다. 모델이 태스크 (Task)에 따라 자율적으로 선택할 수 있습니다. 재사용 가능한 디시플린 (Discipline)이나 공유 어휘에 적합합니다.

User-invoked는 인간이 명시적으로 시작하는 작업입니다. 예를 들어, 계획을 구체화하거나, 이슈 (Issue)를 정리하거나, 작업의 입구를 선택하는 등의 상황입니다.

Model-invoked는 모델이 작업 중에 참조해도 좋은 절차입니다. 테스트 주도 (TDD), 버그 진단, 도메인 모델 (Domain Model) 업데이트, 설계 어휘 참조 등이 여기에 해당합니다. 인간이 매번 "이 사고방식을 사용해"라고 말하지 않아도, 모델이 작업 중에 참조할 수 있는 상태로 만들어 두는 것을 의미합니다.

같은 문서에서는 User-invoked skill은 Model-invoked skill을 호출할 수 있지만, 다른 User-invoked skill에는 도달할 수 없다고 설명되어 있습니다.

이 제약은 미미해 보이지만 효과적입니다. 모든 것을 slash command로 나열하면, 스킬은 늘어나더라도 판단의 부하는 인간에게 남게 됩니다. 입구와 공유 절차를 나누어 두면, "인간이 시작하는 작업"과 "모델이 중간에 참조하는 작업"을 정리할 수 있습니다.

도해: 「누가 호출하는가」로 정리하기

글로만 설명하면 추상적이므로, 구조만 추출하겠습니다.

skill을 「누가 호출하는가」로 나눈다. 입구는 인간이 시작하고, 공유 절차는 모델이 참조한다.

그림을 통해 말하고자 하는 핵심은 User-invoked를 「인간이 시작하는 입구」로 만드는 것입니다. 그리고 Model-invoked를 「모델이 작업 중에 참조할 수 있는 공유 절차」로 만드는 것입니다. /ask-matt와 같은 라우터 스킬 (Router skill)은 입구로서 편리합니다. 다만, 참조 대상인 user-invoked skills도 함께 관리하지 않으면, 라우터만 남고 제대로 기능하지 않습니다.

v1.0.0에서 무엇이 정리되었는가

mattpocock-skills@1.0.0은 기능 목록으로 훑어보기보다, 호출 방식의 정리로서 읽는 것이 맥락에 맞습니다.

/ask-matt: 첫 번째 입구를 만들다

v1.0.0에서는 ask-matt가 추가되었습니다. 릴리스 노트 (Release note)에서는 상황에 맞는 skill이나 flow를 안내하는 user-invoked router라고 설명되어 있습니다.

이는 "스킬이 늘어난 뒤, 처음에 무엇을 선택할 것인가"에 대한 답입니다.

다만, ask-matt는 단독으로 완결되는 입구가 아닙니다. 릴리스 노트에는 ask-matt가 다른 user-invoked skills를 전제로 라우팅 (Routing)하기 때문에, 그것들도 설치되어 있어야 한다고 적혀 있습니다.

이 부분은 주의가 필요합니다. /ask-matt는 /implement를 안내하지만, mattpocock-skills@1.0.0의 .claude-plugin/plugin.json에 기재된 17개의 skill path에는 /implement가 포함되어 있지 않았습니다.

확인 시점의 main branch, 즉 package.json이 1.0.1이 된 상태에서도, .claude-plugin/plugin.json에 ./skills/engineering/implement는 포함되어 있지 않습니다. 반면, skills/engineering/implement/SKILL.md 자체는 리포지토리 (Repository)에 존재합니다.

즉, 리포지토리에는 존재하지만, 플러그인 매니페스트 (Plugin manifest)에는 포함되지 않은 skill을 라우터가 참조하고 있는 상태입니다.

라우터 스킬은 의존하는 스킬군과 함께 관리되어야 비로소 사용할 수 있습니다.

공유 어휘를 skill로 분리하기

v1.0.0에서는 codebase-design과 domain-modeling이 추가되었습니다.

codebase-design은 module, interface, depth, seam, adapter와 같은 설계 어휘를 공유하는 스킬입니다. domain-modeling은 프로젝트의 도메인 모델을 다듬고, CONTEXT.md나 ADR을 업데이트하기 위한 스킬입니다.

이 변경을 통해 improve-codebase-architecture, tdd, grill-with-docs는 개별적으로 설계 어휘를 떠안는 방식에서, 공유 스킬을 참조하는 방식으로 변화하고 있습니다.

AI 지원 개발에서는 코드를 작성하는 속도뿐만 아니라, 어휘의 불일치(vocabulary drift)도 문제가 됩니다. 모델이 매번 프로젝트 용어를 추측하게 되면 설명이 길어지거나 명명(naming)이 흔들릴 수 있습니다. 설계 판단 또한 대화마다 리셋되기 쉽습니다.

공유 어휘를 Model-invoked skill로 분리하는 것은 이러한 리스크를 줄이기 위한 설계로 읽힙니다.

버그 진단을 모델이 포착할 수 있는 절차로 만들기

diagnose는 diagnosing-bugs로 이름이 변경되었습니다. 릴리스 노트(release notes)에는 오래된 /diagnose는 더 이상 존재하지 않는다고 명시되어 있습니다.

이 변경 사항에 대해 관련 X 포스트(post)에서는 diagnosing-bugs가 model-invocable해졌다고 설명하고 있습니다.

이름만 보면 작은 변경처럼 보입니다. 하지만 의미가 있습니다. 버그 진단은 인간이 매번 "진단 모드로 들어가"라고 명령하는 것보다, 모델이 "이것은 재현, 가설, 측정, 수정의 루프가 필요하다"라고 판단하여 참조할 수 있는 편이 더 자연스럽습니다.

삭제된 skill이 보여주는 공개 범위의 경계

caveman과 zoom-out은 삭제되었습니다. 릴리스 노트에는 caveman은 테스트 중인 다른 skill과의 중복으로 인해 공개 의도가 없었으며, zoom-out은 실제 운영에서 사용되지 않았다는 점이 이유로 적혀 있습니다.

여기서 알 수 있는 것은 skill pack은 단순히 추가하기만 하면 되는 것이 아니라는 점입니다. 공개된 skill은 계속 사용됩니다. 설명도 계속됩니다. 고장 나면 마이그레이션(migration)도 필요합니다. 불필요한 skill을 남겨두면 선택지가 늘어날 뿐만 아니라, 운영의 인지 부하(cognitive load)도 증가합니다.

도입 전에 결정할 것

mattpocock/skills를 도입한다면, 명령어를 실행하기 전에 다음 사항을 결정해 두는 것이 안심됩니다.

1. latest를 따를 것인가, 고정할 것인가

tag 시점의 README에 기재된 설치 명령어(install command)는 다음과 같습니다.

npx skills@latest add mattpocock/skills

개인적인 이용이라면 latest를 사용해도 큰 문제는 없을지 모릅니다. 하지만 팀 운영에서는 skill의 이름 변경이나 삭제가 문서(docs)와 절차에 영향을 미칩니다.

이번 사례처럼 v1.0.0 이후에 main branch가 다른 버전으로 진행된 경우에는, 조사 대상인 tag와 현재의 main을 구분해서 읽어야 합니다. 조사 시점에서 tag의 package.json은 1.0.0이었고, 2026-06-19 확인 시점의 main branch의 package.json은 1.0.1이었습니다.

2. 입구와 공유 절차를 분리하기

모든 것을 slash command로 나란히 배치하면 선택 부하(selection load)가 인간에게 남게 됩니다.

• 작업의 입구, 판단, 합의 형성은 User-invoked에 가깝게 배치한다.
• 진단, 설계 어휘, TDD, 도메인 모델 업데이트와 같이 재사용 가능한 규율(discipline)은 Model-invoked에 가깝게 배치한다.

이 분류는 mattpocock/skills에만 국한된 이야기가 아닙니다. 다른 agent skill pack에서도 사용할 수 있는 판단 기준입니다.

3. setup contract를 어디에 남길 것인가

README는 /setup-matt-pocock-skills를 선택하여 issue tracker, triage labels, docs location을 설정하도록 안내하고 있습니다.

작은 설정처럼 보이지만, 팀 운영에서는 불일치의 원인이 됩니다. agent가 issue를 생성하고, label을 달고, docs를 업데이트합니다. 이때 어디를 기준으로 삼을지가 모호하면 절차가 어긋나기 쉽습니다.

4. 오래된 skill 이름을 찾을 수 있는 상태로 만들기

v1.0.0에서는 다음과 같은 변경 사항이 있습니다.

• /diagnose → /diagnosing-bugs
• /write-a-skill → /writing-great-skills
• /caveman 삭제
• /zoom-out 삭제

팀에 이미 도입되어 있다면, 적어도 README, docs, agent config, issue template, 온보딩(onboarding) 자료는 검색 대상에 포함하는 것이 좋습니다.

5. 숫자는 발표와 재측정을 분리하기

동일한 X 포스트에서는 skill descriptions의 토큰 비용(token cost)을 63% 절감했다고 밝히고 있습니다.

이 수치를 그대로 사용하지 않고, 저희 쪽에서도 측정해 보았습니다. ee8bae4 Reduced description lengths 전후로, plugin manifest에 기재되는 skill의 frontmatter description: 항목만을 tiktoken의 cl100k_base로 계산했습니다. 해당 범위 내에서 18개의 manifest-exposed description:은 731 tokens였고, 변경 후 17개는 547 tokens였습니다. 절감률은 25.2%입니다. manifest에 기재되는 항목 수도 달라졌기 때문에, 동일한 skill 그룹의 description만 순수하게 짧아졌다는 식의 비교는 아닙니다.

이 기사의 측정 방식으로는 63% 절감을 재현할 수 없었습니다. 대상 범위나 tokenizer가 다를 가능성은 있습니다. 본문에서는 63%를 "발표상의 주장", 25.2%를 "이번 한정적인 재측정 결과"로 구분하여 다루겠습니다. 측정 출력값은 수중에 있는 검증 로그에도 남겨두었습니다.

AI 관련 도구 기사에서는 속도, 정밀도, token cost 수치가 독자적으로 떠돌기 쉽습니다. 수치를 기재한다면 적어도 측정 대상과 측정 방법을 세트로 묶어야 합니다. 기재하지 않는다면 발표상의 주장임을 명시해야 합니다. 이 선을 그어두면 기사의 신뢰도가 조금 더 견고해집니다.

skill을 늘리기 전에, 운영을 고정하라

mattpocock-skills v1.0.0에서 가져올 수 있는 것은 특정 스킬명이 아닙니다. skill pack을 운영물로 취급하는 관점입니다.

skill은 편리해 보인다고 계속 추가하기만 하면 금방 어질러집니다. 인간이 명시적으로 시작하는 입구인지, 모델이 작업 중에 참조하는 절차인지, 우선 이 부분을 구분해야 합니다. /ask-matt와 같은 router skill을 넣는다면, 참조 대상인 user-invoked skills도 동일한 단위로 관리합니다. 입구만 남아있고 실제 작업으로 이어지지 못하면 의미가 없기 때문입니다.

설계 어휘(design vocabulary)나 도메인 모델링(domain modeling)과 같은 공유 지식은 개별 skill에 중복해서 심어두기보다, Model-invoked skill로 분리하는 설계도 고려해 볼 수 있습니다. 팀에서 사용한다면 setup contract도 README, CONTEXT.md, ADR 등 나중에 참조할 수 있는 곳에 남겨두는 것이 안전합니다.

또 하나, registry 표시만 믿지 않는 것이 좋습니다. release note, tag, manifest, 실제 파일을 대조하지 않으면 오래된 skill 명칭이나 삭제된 slash command가 docs나 config에 남을 수 있습니다. 수치 주장도 마찬가지입니다. 재측정한 것과 발표상의 주장은 구분해서 다루는 것이 안전합니다.

확인 시점의 registry 표시로서 skills.sh와 Skill Vault도 살펴보았습니다.

skill 도입 시 먼저 결정해야 할 것은 "어떤 skill을 넣을 것인가"만이 아닙니다. 어떤 판단을 인간이 가질 것인가, 어떤 절차를 모델에게 맡길 것인가, 어떤 정보를 팀의 공유물로 고정할 것인가 하는 점입니다.

편리함보다, 판단의 위치

mattpocock-skills@1.0.0은 신기능의 개수보다 스킬을 어떻게 호출할지를 재정리했다는 점이 흥미롭습니다.

AI 지원 개발에서는 코드를 쓰는 속도뿐만 아니라, 판단을 어디에 둘 것인가가 문제가 됩니다. 어떤 작업은 인간이 명시적으로 시작하는가, 어떤 규율(discipline)은 모델이 자율적으로 참조해도 되는가, 공유 어휘는 어디에 두는가, 파괴적 변경(breaking changes)을 어떻게 이행하는가 등입니다.

편리한 slash command를 늘리기 전에 이러한 구분법을 정해두는 것. mattpocock-skills v1.0.0은 이를 위한 구체적인 사례로 읽힙니다.

Discussion