skill-router

skill-router 스킬 개요

skill-router가 하는 일

skill-router 스킬은 여러 스킬로 구성된 Claude Code 환경에서 첫 관문 역할을 하는 선택기입니다. 직접 작업을 해결하는 대신, 들어온 요청을 분석해 어떤 전문 스킬이 가장 적합한지 판단하고, 요청이 너무 모호해 확신 있게 라우팅하기 어려울 때는 확인 질문을 던집니다. agent-playbook를 살펴보고 있거나, 팀원이 실제로 쓸 수 있는 스킬 기반 워크플로를 만들고 싶다면, skill-router는 가장 먼저 시행착오를 줄여주는 구성 요소입니다.

누가 skill-router를 설치하면 좋은가

skill-router는 사용할 수 있는 스킬이 여러 개 있고, 평소에 “어떤 스킬을 써야 하지?”, “이 프로젝트 좀 도와줘”, “여기엔 스킬 하나 써줘” 같은 요청을 자주 받는 사용자에게 특히 잘 맞습니다. 특히 다음과 같은 경우 유용합니다:

• 에이전트가 스킬을 고르는 방식을 팀 차원에서 표준화하려는 경우
• 스킬 라이브러리를 처음 접하는 사용자
• 비슷하게 뭉뚱그려진 요청이 실제로는 review, debugging, docs, testing, design 작업 중 무엇이든 될 수 있는 워크플로

반대로 스킬을 한두 개만 쓰고 있고, 어떤 스킬을 호출해야 하는지 이미 늘 정확히 알고 있다면 skill-router의 추가 가치는 크지 않을 수 있습니다.

skill-router가 실제로 해결하는 일

skill-router의 핵심 역할은 단순 추천이 아닙니다. 불충분하게 정의된 요청을 실제 다음 행동으로 바꿔주는 데 있습니다. 즉, 적절한 스킬을 고르고, 왜 그 스킬인지 설명하고, 진행에 필요한 최소한의 맥락만 더 수집합니다. 많은 스킬 시스템은 실행 품질이 병목이 되기 훨씬 전, 바로 이 첫 번째 의사결정 지점에서 실패합니다. 그런 점에서 skill-router는 초반 분기 실수를 줄이는 데 의미가 있습니다.

skill-router의 주요 차별점

일반적인 “어떤 도구를 써야 하지?” 프롬프트와 비교하면, skill-router에는 실무적으로 유리한 점이 몇 가지 있습니다:

• 잘못된 전문 스킬을 고르기 전에, 초기에 개입하도록 명시적으로 설계되어 있습니다
• 사용자 의도를 사용 가능한 스킬에 대응시키는 catalog 관점을 갖고 있습니다
• 의도가 애매할 때 clarification을 지원합니다
• after_complete hook을 통해 라우팅 결정을 기록하므로, 시간이 지나며 스킬 선택이 어떻게 이뤄지는지 추적하고 싶을 때 유용합니다

설치 전에 가장 먼저 확인할 점

skill-router를 도입하기 전에 두 가지를 먼저 확인하세요:

1. 현재 환경에 실제로 라우팅할 만한 의미 있는 하위 스킬 집합이 있는지
2. 사용자가 정교한 작업 설명보다 모호한 목표를 들고 오는 경우가 잦은지

이 스킬은 잘 정리된 스킬 생태계 안에서 dispatcher로 쓸 때 가장 강합니다. 반대로 catalog가 작거나, 오래됐거나, 많이 커스터마이즈되어 있는데도 router 로직이 그에 맞게 갱신되지 않았다면 단독 자산으로서의 가치는 떨어집니다.

skill-router 스킬 사용 방법

skill-router 설치 맥락

이 저장소에서 skill-router는 skills/skill-router에 있습니다. repo README에는 symlink 기반 설치 방식이 나와 있습니다:

ln -s ~/Documents/code/GitHub/agent-playbook/skills/skill-router/SKILL.md ~/.claude/skills/skill-router.md

사용 중인 환경이 skill manager를 지원한다면, 설치 경로는 로컬 스킬 디렉터리에 맞게 조정하면 됩니다. 중요한 것은 SKILL.md가 예상된 스킬 이름으로 Claude Code skill loader에 의해 발견 가능해야 한다는 점입니다.

먼저 읽어볼 파일

빠르게 평가하려면 다음 순서로 읽는 것이 좋습니다:

1. skills/skill-router/SKILL.md
2. skills/skill-router/README.md

SKILL.md에는 실제 activation logic, allowed tools, routing behavior, available skill catalog가 들어 있습니다. README.md는 상위 수준의 흐름과 예시를 파악하는 데 유용하지만, 설치 여부를 판단하는 데 필요한 핵심 정보는 주로 SKILL.md에 있습니다.

언제 skill-router를 먼저 실행해야 하나

다음처럼 요청이 스킬 선택 단계에서부터 불분명할 때는 skill-router를 먼저 쓰는 것이 좋습니다:

• “이 코드베이스 좀 도와줘”
• “이거 개선하는 데 스킬 하나 써줘”
• “이 PR에는 어떤 스킬을 써야 해?”
• “이게 debugging인지 refactoring인지 잘 모르겠는데 도움이 필요해”

이 저장소는 skill-router를 스킬 관련 요청의 기본 진입점으로 명시하고 있습니다. 특히 사용자가 “skill”, “which”, “how to”를 언급하거나, 확신이 없다는 신호를 보일 때 그렇습니다.

skill-router에 필요한 입력 정보

skill-router는 다음 정보가 포함될 때 가장 잘 작동합니다:

• 작업 목표
• 산출물 유형: PR, bug, README, test suite, design file, commit 등
• 원하는 결과
• 어떤 종류의 도움이 필요한지에 대한 불확실성

이 정도 신호가 있어야 router가 단순히 폭넓은 확인 질문으로 빠지지 않고, 의도를 적절한 스킬에 매핑할 수 있습니다.

모호한 요청을 라우팅 가능한 프롬프트로 바꾸기

약한 입력:

• “내 프로젝트에 스킬 하나 써줘”

더 나은 입력:

• “Node.js API용 pull request를 리뷰하는 데 도움이 필요해. correctness, security, maintainability 관점의 피드백이 필요해. 어떤 스킬을 써야 할까?”

왜 이 편이 더 좋은가:

• 작업 대상을 명확히 밝힙니다
• 어떤 품질 기준을 볼지 제시합니다
• 가능한 스킬 범주를 좁혀줍니다
• 그래도 최종 라우팅 판단은 skill-router에 맡깁니다

skill-router 사용 예시 패턴

직접 라우팅이 필요한 경우:

• “이 staged changes에 대해 깔끔한 commit message를 쓰려면 어떤 스킬을 써야 할까?”
• “Python service에서 failing test suite를 진단해야 해. 어떤 스킬이 가장 적합해?”
• “이 repo에서 docs, testing, refactoring 작업 전반에 대해 Skill Discovery 용도로 skill-router를 써줘.”

애매해서 clarification이 예상되는 경우:

• “릴리스 전에 이 프로젝트를 개선하고 싶어.”
• “이 design handoff에 맞는 스킬 하나 써줘.”
• “막혔는데 debugging, review, refactoring 중 뭐가 필요한지 모르겠어.”

skill-router 라우팅 이후 추천 워크플로

실무적으로는 다음 흐름이 효과적입니다:

1. 대략적인 작업 설명으로 skill-router를 호출합니다
2. 나오는 clarification 질문에 짧되 구체적으로 답합니다
3. 추천된 스킬을 확인합니다
4. 다듬어진 작업 설명과 함께 전문 스킬로 전환합니다
5. 정리된 맥락을 유지해 하위 스킬이 충분한 정보로 시작하게 합니다

바로 이 지점에서 skill-router의 가치가 생깁니다. 모호한 의도를 실행 가능한 전문 스킬 호출로 넘기는 handoff를 짧고 명확하게 압축해 줍니다.

기대할 수 있는 catalog 범주

저장소 발췌 내용을 보면 skill-router는 다음과 같은 영역을 포함하는 catalog를 중심으로 구성되어 있습니다:

• core development
• design and UX
• documentation and testing

catalog에 나온 예시 스킬로는 commit-helper, code-reviewer, debugger, refactoring-specialist, figma-designer, 그리고 documentation 성격의 스킬들이 있습니다. 즉, 요청이 이런 catalog 범주 안에 들어갈수록 skill-router의 활용도가 높아집니다.

skill-router 사용의 현실적인 한계

skill-router는 전문 스킬을 대체하지 않습니다. 최종 실행기가 아니라 선택기입니다. 작업이 이미 충분히 구체적이어서 바로 debugger나 code-reviewer로 가면 되는 상황이라면, 먼저 라우팅하는 과정은 불필요한 오버헤드가 될 수 있습니다.

또한 이 스킬은 catalog 품질에 크게 의존합니다. 실제 설치된 스킬 구성이 SKILL.md의 catalog와 다르면, 추천이 오래됐거나 오해를 부르는 방향으로 흘러갈 수 있습니다.

눈여겨볼 도구와 동작

이 스킬은 Read, AskUserQuestion, WebSearch, Grep를 사용할 수 있습니다. 실사용에서는 특히 AskUserQuestion이 중요합니다. 추천 전에 모호함을 해소할수록 라우팅 품질이 크게 좋아지기 때문입니다.

또한 “Log skill routing decisions”라는 이유로 session-logger용 after_complete hook을 정의하고 있습니다. 스킬 분류 과정을 감사 가능하게 보고 싶거나, 사용자가 어떤 작업에서 자주 헷갈리는지 분석하고 싶다면 유용한 구현 디테일입니다.

skill-router 스킬 FAQ

skill-router는 초보자에게도 좋은가

네. 특히 사용 가능한 스킬 목록이 길어서 어디서 시작해야 할지 모르는 초보자에게 유용합니다. skill-router는 “X를 도와줘”를 “다음엔 이 구체적인 스킬을 써라”로 바꿔 주며 진입 장벽을 낮춰줍니다.

skill-router는 Skill Discovery에만 쓰는가

아니요. 다만 skill-router for Skill Discovery는 가장 강한 활용 사례 중 하나입니다. 팀 워크플로에서 일관된 첫 단계 triage가 중요하고, 각 개인이 catalog를 얼마나 잘 아는지는 덜 중요할 때도 표준 라우팅 계층으로 유용합니다.

skill-router는 일반 프롬프트와 무엇이 다른가

일반 프롬프트로도 모델에게 스킬 추천을 요청할 수는 있습니다. 하지만 skill-router는 그 동작을 재사용 가능하고 트리거 가능한 스킬 형태로 묶어 두고, 명시적인 activation cue, 알려진 catalog, clarification logic까지 포함합니다. 그래서 라우팅 단계가 더 일관되고 운영에 옮기기 쉬워집니다.

언제 skill-router를 건너뛰어야 하나

다음 경우에는 생략해도 됩니다:

• 이미 올바른 전문 스킬을 알고 있는 경우
• 환경에 스킬이 거의 없는 경우
• skill-router의 catalog가 실제 설치된 스킬 세트를 반영하지 않는 경우
• 애매함이 거의 없어서 곧바로 실행에 들어가고 싶은 경우

커스텀 스킬 생태계에서도 skill-router가 잘 작동하나

작동할 수는 있지만, 실제 스킬과 catalog를 계속 맞춰 둔다는 전제하에서만 그렇습니다. router의 가치는 정확한 매핑에서 나옵니다. 많이 커스터마이즈된 환경에서는 오래된 catalog 항목이 가장 큰 도입 리스크입니다.

skill-router 설치 수고를 들일 가치가 있나

대체로 그렇습니다. 여러 사람이 같은 스킬 라이브러리를 쓰거나, 사용자가 넓고 불충분하게 정의된 질문을 자주 던진다면 특히 그렇습니다. 반대로 스킬 사용이 개인적이고, 빈도가 낮고, 이미 사용 방식이 충분히 정리돼 있다면 설치는 필수라기보다 선택 사항에 가까울 수 있습니다.

skill-router 스킬 개선 방법

skill-router에 더 좋은 라우팅 신호 주기

skill-router 결과를 가장 빠르게 개선하는 방법은 첫 입력의 품질을 높이는 것입니다. 다음 정보를 포함하세요:

• 작업 유형
• 산출물 또는 대상
• 원하는 결과
• 언어, repo 영역, 마감 시한 같은 제약 조건

예를 들어 “something is broken”보다 “packages/api에서 failing CI test가 있는데 root cause를 분리해내고 싶다”가 훨씬 더 잘 라우팅됩니다.

clarification 질문에는 의사결정에 필요한 정보로 답하기

skill-router가 후속 질문을 하면 “그냥 좀 개선해줘” 같은 일반적인 답은 피하세요. 어떤 개선을 원하는지 밝혀야 합니다. 예를 들면 correctness, readability, docs quality, UX fidelity, test coverage, release readiness 같은 기준입니다. 이 차이가 어떤 스킬을 선택해야 하는지를 바꿉니다.

skill catalog를 최신 상태로 유지하기

구조적으로 봤을 때 skill-router를 개선하는 가장 큰 방법은 catalog 유지보수입니다. 저장소에서 하위 스킬이 추가, 제거, 이름 변경되면 router도 바로 업데이트해야 합니다. router는 자신이 알고 있는 선택지의 품질만큼만 좋습니다.

더 강한 모호성 해소 규칙 추가하기

가장 흔한 실패 유형은 가까운 스킬 범주끼리 겹치는 경우입니다. 예를 들어 debugging vs refactoring, documentation vs review 같은 구분입니다. skill-router를 개선하려면 다음 경계를 가르는 cue를 더 촘촘히 다듬는 것이 좋습니다:

• diagnosis와 code improvement의 구분
• review와 generation의 구분
• design interpretation과 implementation planning의 구분

실제로 애매한 요청에 대한 예시 강화하기

이 스킬은 이미 직접 요청과 모호한 요청 예시를 함께 보여줍니다. 도입을 더 쉽게 만들려면, 실제 내부 요청에 가까운 예시를 더 추가하는 편이 좋습니다. 예를 들면:

• release prep
• root cause가 불명확한 failing CI
• “이 PR을 배포 가능한 상태로 만들어줘”
• design file을 implementation task로 전환하기

이런 예시는 사용자가 더 깔끔하게 라우팅되는 방식으로 요청을 작성하도록 돕습니다.

라우팅 로그를 활용해 skill-router 다듬기

skill-router는 session-logger를 통해 라우팅 결정을 기록하므로, 가능하다면 그 로그를 검토해 보세요. 특히 다음을 확인하면 좋습니다:

• clarification이 반복적으로 맴도는 패턴
• 계속 잘못 라우팅되는 요청
• 뚜렷하게 맞는 스킬이 없는 빈번한 의도

이 피드백 루프는 시간이 지나며 skill-router를 개선하는 가장 실용적인 방법 중 하나입니다.

첫 추천 이후 한 번 더 다듬기

첫 추천이 아주 틀리진 않지만 어딘가 어색하다면, 바로 스킬을 포기하지 마세요. 빠진 맥락을 넣어 작업 설명을 다시 잡아보면 됩니다:

• 정확히 어떤 산출물인가?
• diagnosis, review, generation, restructuring 중 무엇이 필요한가?
• 무엇이 성공의 기준이 되는가?

이 과정을 거치면 첫 번째의 넓은 추천이 두 번째에는 올바른 전문 스킬 handoff로 바뀌는 경우가 많습니다.

단순한 규칙으로 팀 차원의 도입 개선하기

운영 규칙으로는 다음 한 줄이 유용합니다: 사용자 요청이 명확히 정의된 작업 수행보다 “어떤 종류의 도움이 맞는지 찾는 것”에 가까울 때는 먼저 skill-router를 사용한다. 이렇게 하면 router를 모든 워크플로에 억지로 끼워 넣지 않으면서도, 가치가 큰 초기 triage에 집중시킬 수 있습니다.