e9tgldr/skill-router

Skill Router

현재 약 170개의 스킬이 설치되어 있으며, 그 품질과 범위는 매우 다양합니다. 여러 개가 서로 거의 중복됩니다(세 개의 "제네릭하지 않게 만드는" 디자인 스킬, 두 개의 impeccable 복사본, xlsx와 xlsx-dsh). 잘못 선택하는 것은 가능한 가장 큰 실수입니다: 잘못된 스킬은 그 전체 본문을 컨텍스트에 소모하고 답변을 표적에서 벗어나게 만들며, 반면 스킬이 전혀 없는 것이 보통 잘못된 스킬보다 낫습니다.

따라서: 먼저 라우팅하고, 그 다음 작업하세요. 이 파일이 라우팅 절차입니다. 이는 저렴합니다 — 파일 스캔 한 번, 도구 호출 한두 번 — 그리고 스킬 목록에서 추측하는 것을 대체합니다. 이 절차는 설치에 구애받지 않습니다: 아래의 개수, 이름, 패밀리는 이 절차가 작성된 카탈로그를 설명하며, 검색은 발견된 모든 카탈로그에 대해 정규화됩니다.

1. 아무것도 건드리기 전에 작업 읽기

다음 질문에 각각 한 줄로 조용히 답하세요. 이것들은 결과물이 아닌 경로를 결정합니다.

• 무엇이 생성되는가? 파일 (docx/xlsx/pdf/pptx/png), 실행 코드, 결정, 메시지, 계획.
• 무슨 도메인인가? 웹 프론트엔드, 백엔드, 데이터, 문서, 디자인, 비디오/애니메이션, VR, 운영.
• 기존 결과물이 있는가? 새 프로젝트 vs. 다른 사람의 코드 수정 — 이것은 경로를 빌드 스킬에서 감사/리뷰 및 이해 우선 스킬로 바꿉니다.
• 누가 출력을 읽는가? 투자자, 교사, 팀원, 컴파일러. 대상에 따라 기술 스킬이 아닌 작성 스킬이 변경됩니다.

요청이 순수한 의도의 한 문장이라면("멋진 걸 만들어줘"), 그것도 라우팅 신호입니다: 아직 스킬을 선택할 수 없으며 질문이 먼저 온다는 뜻입니다(6단계).

2. 빠른 경로 — 라우팅 테이블 확인

references/task-types.md(이 스킬 디렉토리 기준 상대 경로)를 읽으세요. 첫 번째 테이블은 약 40개의 일반적인 작업 형태를 한 화면에 검증된 스킬 체인으로 매핑합니다; 두 번째 테이블은 추측하기 어려운 이름(animation-vocabulary, cdn-caching, vercel-connect)을 가진 좁은 도구들을 나열하므로, 맞는 것이 없다고 결론내기 전에 확인하세요.

• 일치 항목 발견됨 → 해당 체인으로 4단계로 이동하세요. 검색하지 마세요; 테이블이 답이며 다시 검색하는 것은 토큰만 낭비합니다.
• 일치 항목 없음 또는 부분 일치 → 3단계.
• 테이블이 당신이 가지고 있지 않은 스킬을 나열하는 경우(다른 설치, 다른 환경, 새 머신) → 테이블을 완전히 건너뛰고 3단계로 가세요. 테이블은 한 설치의 매핑입니다; 검색은 모든 카탈로그에서 작동합니다. --doctor로 확인하세요.

3. 카탈로그 검색

명령어 하나, 모델 필요 없음:

# 경로는 이 스킬의 디렉토리를 기준으로 합니다.
node scripts/find_skills.mjs "랜딩 페이지가 제네릭하게 느껴짐" -n 8
node scripts/find_skills.mjs --doctor      # 어떤 루트가 스캔되었으며, 무엇이 발견되었는지

이 스크립트는 모든 설치된 스킬의 이름과 설명을 점수화합니다(IDF 가중치 적용, 따라서 user/code/when 같은 흔한 단어보다 희귀 단어가 더 중요함). 또한, 필요한 스킬과 어휘를 공유하지 않는 표현을 위한 선별된 개념 레이어를 추가합니다. 상위 일치 항목과 해당 SKILL.md 경로를 출력하거나, 맞는 것이 없으면 NO GOOD MATCH를 출력합니다.

잘 질의하는 방법:

• 사용자의 문장이 아닌 작업의 명사를 사용하세요: "표 차트 csv" ("이것을 그래프가 있는 무언가로 바꿔줘" 대신).
• 하나의 긴 질의보다 2~3가지 다른 관점으로 실행하세요 — 결과물 관점(피치 데크), 도메인 관점(투자자 펀드레이징), 문제 관점(텍스트가 템플릿처럼 보임). 원한다면 하나의 bash 호출에서 일괄 처리하세요.
• --explain은 각 결과가 왜 그렇게 순위가 매겨졌는지 토큰별로 출력합니다 — 결과가 잘못된 것 같을 때 원인을 추측하는 대신 사용하세요.
• 각 결과는 [strong], [likely] 또는 [weak]으로 태그됩니다. [weak]는 라우터가 하나의 우연한 단어에서 추측하고 있음을 의미합니다 — 제안으로 간주하고 자신의 판단을 우선시하세요. 모든 결과가 weak이면 스크립트가 그렇게 말합니다.
• --all은 전체 카탈로그를 덤프하고, --name pdf는 하나의 이름을 경로로 확인하며, --json은 기계 판독 가능한 출력을 제공하며, -n 20은 목록을 넓혀 차순위 항목을 보고 싶을 때 사용합니다(잘못 표현된 질의의 경우 종종 4번째가 정답입니다).
• 결과는 순위가 매겨질 뿐, 권위적이지 않습니다. 여전히 당신이 선택합니다.
• 스크립트는 이 스킬의 scripts/ 디렉토리에 있습니다. 환경이 절대 경로를 노출하면 그것을 사용하고, 그렇지 않으면 먼저 스킬 디렉토리로 cd하세요.
• 존재하는 모든 것을 인덱싱하며, 고정된 목록이 아닙니다: 여러 환경(~/.pi, ~/.claude, ~/.codex, ~/.agents, ~/.cursor, <cwd>/skills, 플러그인 node_modules)에서 일반적인 사용자별 및 프로젝트별 스킬 디렉토리를 스캔합니다. SKILL_ROUTER_ROOTS=/a/skills:/b/skills 또는 --root /a/skills를 사용하여 다른 곳을 가리킬 수 있습니다. 익숙하지 않은 머신에서는 먼저 --doctor를 실행하세요: 모든 루트, 존재 여부, 기여한 스킬 수, 중복 이름, 구문 분석할 수 없는 SKILL.md 파일을 나열합니다. 새 카탈로그에는 개념이나 게이트가 필요하지 않습니다 — 이는 어휘 순위 위의 선택적 부스트이며, 개념이 전혀 없어도 검색은 여전히 이름과 설명으로 순위를 매깁니다.

스크립트 자체를 사용할 수 없거나 검색이 두 번 연속으로 그럴듯한 결과를 반환하지 않으면, 시스템 프롬프트 목록에서 ~/.pi/agent/skills/ 설명을 읽는 것으로 대체하세요. 지체하지 말고, 하나가 맞기를 바라며 다섯 개의 SKILL.md 파일을 열지 마세요.

4. 선택 — 체인을 짧게 유지하는 규칙

1. 구현보다 프로세스. 작업이 어떻게 실행되는지를 설정하는 스킬(브레인스토밍, 계획 작성, 체계적 디버깅, 테스트 주도 개발, 스킬 작성)은 출력이 어떻게 보여야 하는지를 설정하는 스킬(디자인, docx, nextjs)보다 먼저 로드됩니다. 프로세스 스킬은 종종 다음에 구현 스킬을 로드하라고 지시합니다 — 그렇게 하세요.

2. 최대 3개의 스킬. 하나가 일반적이고, 두 개는 일반적이며, 세 개가 최대치입니다. 네 번째는 결정하는 대신 수집하고 있다는 의미입니다.

3. 패밀리당 하나. 같은 패밀리의 두 멤버를 절대 로드하지 마세요 — 첫 번째 열을 선택하세요:

   패밀리	하나 선택
   프론트엔드 취향 / 안티-제네릭	design-taste-frontend, ui-craft, impeccable, frontend-design, craft
   중복 복사본	impeccable (agents/) over impeccable-dsh; xlsx over xlsx-dsh; kimi/* over dsh/* (단, dsh 것이 명확히 더 구체적이지 않은 경우)
   문서 형식	파일과 정확히 일치하는 것: docx, pdf, pptx, xlsx
   모션	animate (웹), animate-expo (React Native) — 둘 다 아님
   백엔드	backend-patterns, create-a-backend, api-design — 최대 2개
   퀘스트 / VR	hz-* 패밀리 + metavr-cli; 항상 hz-quest-verify-first로 시작

4. 플랫폼 게이트를 존중하세요. hz-*, portal, metavr-cli는 Quest/VR 컨텍스트가 필요합니다; cloudbase는 CloudBase가 필요합니다; kimi-webbridge / kimi-cu는 실제 브라우저 또는 데스크탑 GUI가 필요합니다. 작업이 플랫폼을 명명하지 않으면, 단어가 아무리 잘 일치해도 스킬이 적용되지 않습니다.

5. 정당화 또는 거부. 각 후보에 대해 한 가지 이유: 왜 이것인지. 이유가 "같은 단어를 언급하기 때문에"라면 거부하세요. 두 스킬이 어휘를 공유하더라도 다른 기계를 위한 것일 수 있습니다.

6. 없음도 유효한 답변입니다. 아무것도 기준을 통과하지 못하면 몇 마디로 말하고 자신의 판단으로 작업을 수행하세요. 누락된 스킬이 반쯤 관련된 스킬을 가동하는 이유가 되지 않습니다.

7. 전환 시에만 다시 라우팅하세요. 동일한 워크플로우 내의 새로운 하위 작업은 새로운 검색을 트리거하지 않습니다. 도메인 변경(사용자가 "사실 데크로 만들어줘"라고 말하는 경우)은 트리거합니다.

5. 한 줄로 알리고, 그 다음 진행

작업을 수행하기 전에 경로를 한 번 명시하세요:

design-taste-frontend(템플릿화되지 않은 랜딩 페이지) → 히어로를 위한 animate 사용. 카피라이팅 부분에 맞는 스킬이 없음; 직접 작성 중.

해당 줄의 규칙: 한두 문장, 이름 + 이유만. 스킬 인벤토리에 대한 에세이, "다음 스킬을 선택했습니다…" 없음. 사용자는 토론이 아닌 결정을 보고 싶어합니다. 경로가 특이하거나 의도적으로 테이블에서 벗어나는 경우, 추가 설명이 필요한 한 가지 경우입니다.

6. 작업을 막는 것만 질문하세요

라우팅의 가치가 발휘되는 곳입니다: 선택된 스킬은 무엇을 알아야 하는지 알려주므로, 그 질문들 — 그리고 오직 그것들만 — 하세요.

질문해야 하는 경우는 다음과 같습니다:

• 작업에 두 가지 이상의 진정으로 다른 결과물이 있는 경우("포스터"가 PNG일 수도 있고 슬라이드 데크일 수도 있으며 파일이 다릅니다),
• 대상 또는 형식을 알 수 없고 컨텍스트에서 추측할 수 없는 경우,
• 선택한 스킬의 지침에 사용자가 결정해야 하는 사항(브랜드, 예산, 자격 증명, 실제 데이터 vs. 모의 데이터)이 필요한 경우,
• 경로에 실제 비용이 들거나 프로덕션에 영향을 미치는 경우.

질문하지 말아야 할 것:

• 어떤 스킬을 사용할지 — 이것은 이 스킬의 역할입니다. 결과에 대해 물어보고, 라우팅이 답변을 따르게 하세요,
• 요청이 이미 답변한 것, 코드베이스나 파일이 답변하는 것,
• 합리적인 기본값이 커버하는 것. 기본값을 선택하고, 알림 줄에서 선택한 기본값을 말하고, 계속 진행하세요. 이 사용자는 턴바이턴 확인보다 긴 무인 실행을 선호합니다.

형식: ask_user_question 호출 한 번, 최대 3개 질문, 각각 2-4개 옵션, 권장 옵션 먼저 "(Recommended)" 레이블, 각 옵션에 대해 무엇을 약속하는지 한 문장으로 설명. 첫 번째 질문 직후에 두 번째 질문 세트를 쌓지 마세요; 답변이 새로운 질문을 제기하면, 또 다른 왕복보다 합리적인 기본값을 선호하세요.

로드한 스킬에 자체 발견 또는 질문 단계가 있는 경우(대부분의 디자인 및 계획 스킬이 그렇습니다), 직접 만드는 대신 그것을 실행하세요. 연속으로 두 번의 질문 라운드는 지연으로 읽힙니다.

7. 로드 및 실행

• read 도구로 SKILL.md를 검색 결과가 반환한 경로에서 전체를 읽으세요. 대충 읽은 스킬은 대충 만든 결과물을 낳습니다.

• references/, scripts/, assets/ 경로를 해당 스킬의 디렉토리를 기준으로 확인하세요 — 검색 출력이 파일을 출력하므로, 상위 디렉토리가 스킬 루트입니다.

• 스크립트를 그대로 실행하세요. 스크립트에 문서화되지 않은 인수가 필요하면, 자신의 구현으로 대체하지 말고 그렇게 말하세요.

• 스킬이 동점을 이깁니다. 로드되면, 그 지침이 작업 수행 방법에 대한 이 파일의 의견과 일반적인 모범 사례를 재정의합니다. 이 파일은 선택만 했습니다.

• 로드된 스킬이 "먼저 사용자에게 물어보기" 또는 "코드 작성 전에 계획하기"로 시작하면 그렇게 하세요 — 프로세스 스킬로 라우팅한 다음 그 프로세스를 건너뛰는 것은 라우팅을 전혀 하지 않는 것보다 더 나쁩니다.

• 작업 중 스킬이 잘못되었음을 발견하면, 솔직하게 말하고 다시 라우팅하세요(4단계). 잘못된 스킬을 조용히 해결하는 것은 실패 모드입니다.

• 수정 사항을 기록하여 같은 실수가 반복되지 않도록 하세요:

  node scripts/find_skills.mjs --learn "<실패한 표현>" <올바른 스킬>
  node scripts/find_skills.mjs --wrong "<실패한 표현>" <잘못된 스킬>
  

  사용자가 경로를 거부하거나, 로드된 스킬이 잘못된 도구로 판명되거나, 검색이 놓쳐서 수동으로 라우팅해야 할 때마다 이 작업을 수행하세요. 학습된 수정 사항은 유사한 미래 질의에서 어휘 점수보다 우선하며, 설치와 함께 이동합니다 — 이것이 이 라우터가 본 적 없는 환경에서 더 나아지는 방법입니다.

8. 종료

끝에 한 줄: 사용된 스킬과 결과물이 있는 위치. 그런 다음 중지 — 스킬 내용 요약, 라우팅 설명 제안 없음.

유지 관리 — 라우터를 망가뜨리지 않고 변경하기

라우터는 감이 아니라 점수로 평가됩니다. scripts/eval_routing.mjs는 80개의 실제 질의를 포함하며, 각각 진정으로 수용 가능한 답변인 스킬 세트와 12개의 게이트 케이스(일반 React 질의가 절대 Quest 스킬을 표면화해서는 안 됨)를 가지고 있습니다. 변경 전후에 실행하세요:

node scripts/eval_routing.mjs
# 점수: 80/80 (100.0%)  게이트 누수: 0
node ... --verbose      # 사례별 순위
node ... quest          # 일치하는 사례만

node scripts/smoke_portable.mjs   # 외부 카탈로그 + 학습 + 600개 스킬 규모

smoke_portable.mjs는 이식성 테스트입니다: 이 라우터가 본 적 없는 도메인(Kubernetes, Rust, Salesforce, Terraform…)에서 16개의 스킬을 생성하고, 순위, 의역 견고성, 이식 가능 게이트, 학습, 중복 이름, 빈 카탈로그, 공백이 있는 경로, SKILL_ROUTER_ROOTS, 600개 스킬 규모 실행을 확인합니다. 점수를 변경하면 두 스위트 모두 녹색을 유지해야 합니다 — 평가는 알려진 카탈로그에서 품질을 보호하고, 스모크 테스트는 알려지지 않은 카탈로그에서 동작을 보호합니다.

점수를 올리는 변경은 개선이고, 점수를 낮추는 변경은 코드가 아무리 깔끔하게 읽혀도 회귀입니다. 예상 스킬이 설치되지 않은 경우는 실패가 아닌 건너뛰므로, 모든 머신에서 실행할 수 있습니다.

실제 작업이 잘못 라우팅될 때, 그것을 설명하는 가장 저렴한 계층에서 수정하세요:

1. 같은 아이디어에 대한 잘못된 단어 → find_skills.mjs에서 선별된 CONCEPTS 규칙을 추가하세요(when 정규식 → boost 점수, 선택적 unless 거부 및 demote). 이것은 스킬과 어휘를 공유하지 않는 의도를 위한 계층입니다: "막연한 아이디어, 명세 없음" → brainstorming. 일회성? 이것을 사용하지 마세요 — 대신 기록하세요(--learn). CONCEPTS는 일반적인 동작을 위한 것입니다; 메모리는 "이 표현, 이 스킬"을 위한 것입니다.
2. 반복되는 작업 형태 → references/task-types.md에 행을 추가하세요. 질의 시간에 비용이 들지 않으며 빠른 경로가 검색을 완전히 건너뜁니다.
3. 시끄러운 이웃에게 계속 지는 스킬 → DEMOTE에 추가하거나, 시끄러운 스킬에 개념에서 demote를 부여하세요(예: dashboard만으로는 ui-craft를 ui-craft-dense-dashboard로 이길 수 없음).
4. 일반 질의로 누출되는 플랫폼 스킬 → GATES를 확장하여 스킬이 적격이 되기 위해 반드시 있어야 하는 단어를 추가하세요.
5. 사용자가 수정한 경로 → --learn / --wrong, 그런 다음 진행하세요. 가끔 --memory를 확인하세요: 같은 스킬이 같은 종류의 표현에 대해 계속 수정되는 경우, 패턴을 CONCEPTS로 승격시키고 --forget으로 항목을 제거하세요.

먼저 실패하는 질의를 CASES에 추가하고, 실패를 지켜본 후, 수정하세요. 기록하지 않은 질의로 점수를 조정하지 마세요 — 그것이 라우터가 당신의 예제에는 좋고 사용자의 예제에는 나쁘게 되는 방법입니다.

위험 신호 — 당신은 합리화하고 있습니다, 중지하세요

생각	현실
"이것은 간단해서 라우팅이 필요 없어"	빠르게 라우팅하고, 빠르게 구현하세요. 빠른 경로는 가볍습니다.
"이 스킬에 가장 가까운 것 같아, 한번 해보자"	검색 또는 테이블을 사용하세요. 추측하지 마세요.
"사용자가 질문을 싫어할 거야"	그들은 잘못된 결과물을 더 싫어합니다. 진정으로 필요한 경우에만 질문하세요(규칙 6).
"더 많은 스킬 = 더 나은 결과"	더 많은 컨텍스트 = 더 흐릿한 프롬프트. 세 개의 스킬 이후에는 그 중 어떤 것도 제대로 실행되지 않습니다.
"이 스킬은 완벽하지 않지만, 스스로 해결할 수 있어"	해결하지 마세요. 그것을

…

[번역을 위해 잘림]