스킬 활성화 확인
스킬은 모델이 적절한 순간에 스킬을 사용할 때만 그 가치를 발휘합니다.
이 결정은 거의 전적으로 스킬의 프론트매터 description을 기반으로 이루어집니다. 따라서 "내 스킬이 트리거되는가?"는 측정 가능한 질문이며, 이를 측정하는 방법은 다음과 같습니다: 레이블이 지정된 사용자 요청 세트를 구축하고, 각 요청에 대해 실제 에이전트를 실행한 후 스킬이 사용되었는지 여부를 점수화합니다.
사용자의 요청은 다음과 같습니다: $ARGUMENTS
1단계 — 대상 스킬 찾기
$ARGUMENTS는 SKILL.md의 경로, 스킬 디렉토리의 경로, 스킬 이름 또는 비어 있을 수 있습니다.
- 비어 있음:
.claude/skills/*/SKILL.md및**/skills/*/SKILL.md를 글로브(glob)합니다. 일치하는 항목이 하나 → 사용합니다. 여러 개 → 목록을 표시하고 어느 것을 사용할지 질문합니다. 없음 → 그렇다고 말하고 중단합니다. - 디렉토리: 해당 디렉토리 안의
SKILL.md를 사용합니다. - 이름: 일치하는 스킬 디렉토리를 찾습니다.
스킬의 기본 이름은 SKILL.md가 포함된 디렉토리 이름입니다. 프론트매터 description을 읽고 바로 앞에 두십시오: 이 문자열은 모델이 매칭하는 대상이므로, 행 설계의 기본 입력이며 결국 편집을 권장하게 될 대상입니다.
해당 위치에서 description의 길이를 측정하십시오 — 두 가지 별도의 예산이 description을 자르며, 둘 중 하나라도 적용되면 마치 잘못된 문구처럼 보이는 낮은 재현율 결과가 생성됩니다.
- 스킬별 잘림.
description과when_to_use가 연결되어 고정된 문자 예산인 1,536자에서 잘리며, 이는skillListingMaxDescChars설정을 통해 구성 가능합니다. 잘린 지점 이후의 트리거 텍스트는 활성화에 전혀 영향을 미칠 수 없으므로 존재하지 않는 것이나 마찬가지입니다. - 전체 목록 예산, 활성화 스위트를 실행하는 저장소일수록 더 중요합니다. 목록에는 항상 모든 스킬 이름이 포함되지만, 전체 문자 예산은 모델의 컨텍스트 창의 약 1% 크기로 조정되며, 사용자가 설치한 모든 스킬이 공유합니다. 초과되면 Claude Code는 사용 빈도가 가장 낮은 스킬부터 설명을 삭제합니다.
두 번째 항목은 한 가지 결과를 명확히 언급할 가치가 있습니다: 많은 스킬이 있는 저장소에서는 스킬이 완벽하게 좋은 설명을 가지고 있어도 재현율이 거의 0에 가까울 수 있습니다. 그 이유는 설명이 목록에 포함되지 않았기 때문입니다. 이 경우 문구를 다시 작성해도 아무것도 해결되지 않습니다. 그리고 삭제 순서는 가장 덜 호출된 것부터이므로, 새로 작성된 스킬(정의상 거의 호출되지 않으며, 정확히 누군가가 이 스위트를 실행하는 대상)이 가장 희생될 가능성이 높습니다. 이는 테스트 중인 스킬에 대한 체계적인 편향입니다.
목록이 문제인 경우 해결 방법: skillListingBudgetFraction(기본값 1%), SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수(고정 문자 수), 그리고 skillOverrides를 "name-only"로 설정하여 매칭이 필요하지 않은 스킬의 예산을 확보합니다.
스킬의 프론트매터에 설명이 없는 경우, 발견 사항으로 중단하고 보고하십시오 — 설명이 없는 스킬은 모델이 호출할 수 없으므로 스위트는 구조적으로 재현율이 0점이 되어 이미 알고 있는 정보 외에는 아무것도 알려주지 않습니다.
2단계 — coder-eval 설치 확인
coder-eval --version을 실행합니다. 이 플러그인을 설치했다고 CLI가 설치된 것은 아니며, 이 CLI 없이는 스위트를 검증하거나 실행할 수 없습니다.
CLI가 없는 경우 ${CLAUDE_PLUGIN_ROOT}/reference/cli-setup.md를 따릅니다: 설치를 제안하고, 실행하기 전에 허락을 구한 후, 이후 coder-eval --version으로 확인합니다. 절대 요청 없이 설치하지 말고, 사용자가 거부하면 계속 진행하지 마십시오.
해당 참조 문서는 버전 확인의 다른 부분, 즉 이 프로젝트가 특정 coder-eval 버전을 고정하고 있는지 여부와 설치된 버전이 일치하지 않을 때 수행할 작업도 다룹니다.
3단계 — 이 스킬을 이미 다루고 있는 항목 확인
무언가를 설계하기 전에 저장소에 이미 무엇이 있는지 확인하십시오. ${CLAUDE_PLUGIN_ROOT}/reference/repo-layout.md에 따라 작업 트리를 찾고, skill_triggered 기준을 가진 작업을 글로브합니다.
기존 스위트가 이미 이 스킬을 명명하고 있다면, 해당 스위트의 적용 범위(긍정 행 및 방해 행 수, 게이트하는 suite_thresholds)를 보고하고, 병렬 스위트를 구성하는 대신 데이터 세트에 행을 추가하여 확장할 것을 제안하십시오. 하나의 스킬에 두 개의 스위트가 있으면 서로 분기되어 사용자는 매 실행마다 두 스위트에 대한 비용을 지불하게 됩니다. 이 스킬을 다루는 항목이 전혀 없거나, 사용자가 기존 항목을 확인한 후 확장을 선택하는 경우에만 새로 구성하십시오.
조용히 우회하기보다 보고할 가치가 있는 두 가지 사항:
- 방해 행이 없는 기존 스위트. 정밀도는 정의상 1.0이므로 결과의 절반이 무의미합니다. 방해 행을 추가할 것을 제안하십시오 — 경쟁 스위트를 구성하고 아무 말도 하지 않는 것보다 실제로 개선된 것입니다.
- 다른 스킬을 명명하는 인접 스위트.* 이는 적용 범위가 아닙니다. 새로 구성하고, 인접 스위트가 적용 범위로 간주되지 않는 이유를 설명하십시오.
그런 다음 agent.plugins가 어디에서 와야 하는지 확인하십시오. 작업이 해결할 실험이 이미 해당 블록을 제공한다면, 상속받고 새로 작성하지 마십시오 — 실험이 제공하는 것을 작업이 다시 선언하면 분기되며, 이를 잡아낼 방법이 없습니다. 샌드박스에 스킬을 노출시키는 항목이 없을 때만 템플릿 자체 블록을 작성하십시오. 여러 실험이 존재하고 이 작업이 어느 실험을 해결할지 명확하지 않다면, 추측하지 말고 질문하십시오.
4단계 — 행 설계
이 단계는 전체 실험입니다. 나머지는 절차에 불과합니다.
긍정 행 — 실제 사용자가 그럴듯하게 할 법한 요청으로, 설명이 다루겠다고 주장하는 내용입니다. 의역하십시오; 설명에서 문구를 절대 복사하지 마십시오. 설명에서 가져온 행은 문자열 매칭을 테스트하는 것이지 활성화를 테스트하는 것이 아닙니다. 어휘를 다양하게 하고, 사용자가 스킬이 수행하는 작업이 아닌 문제를 설명하는 간접적인 행을 최소한 하나 포함하십시오.
방해 행 — 스킬이 응답해서는 안 되는 인접 요청, 특히 설명과 어휘를 공유하는 요청입니다. 이것이 정밀도를 의미 있게 만드는 요소입니다.
형제 소유 행 (선택 사항) — 합법적으로 동일 저장소의 명명된 다른 스킬에 속하는 요청으로, expected_skill이 해당 형제 스킬로 설정됩니다. 여러 스킬이 있는 저장소에서 두 인접 스킬 간의 잘못된 라우팅이 일반적인 실패이며, 일반 방해 행은 오발이 발생했다는 것만 보여줄 뿐 어디로 갔는지는 보여주지 않습니다. 이러한 행은 그 위치를 알려줍니다.
두 스킬이 중복되는 주제를 가지고 있고 어느 스킬이 우선하는지 알고 싶을 때 추가하십시오. 추가 행이 필요하며, 모든 행은 전체 에이전트 실행입니다 — 따라서 목표 지향적인 후속 조치로 취급하고 기본값으로 사용하지 마십시오.
프롬프트에 스킬 이름을 절대 명시하지 마십시오. 이는 활성화가 아닌 복종을 테스트합니다:
- 나쁨: "pdf-forms 스킬을 사용하여 이 지원서를 작성하세요."
- 좋음: "이 지원서 PDF의 필드를 작성하여 다시 보내야 합니다."
이 규칙은 형제 소유 행의 영향을 받지 않습니다: expected_skill은 데이터 세트의 레이블이며, 기준에서 읽혀지고 에이전트에게는 절대 표시되지 않습니다. 행의 prompt는 여전히 어떤 스킬 이름도, 형제 스킬 이름도 명명해서는 안 됩니다.
크기 조정. 최소 3개의 긍정 + 3개의 방해 행. 신뢰할 수 있는 신호를 위해 각각 8–12개를 목표로 하십시오 — 3개 행에 대한 재현율은 33포인트 단위로 움직이므로 실제 회귀와 노이즈를 구별하기에는 너무 거칠습니다. 제공된 템플릿은 6개 행을 포함하는데, 이는 설명을 위한 최소치일 뿐 목표가 아닙니다. 형제 소유 행은 그 위에 추가됩니다: 8–12개의 긍정 행과 8–12개의 방해 행은 이미 16–24번의 실행이므로, 스위트를 작성하기 전에 결과 총계를 명시하십시오.
방해 행이 없는 스위트 생성을 거부하십시오. 부정 행이 없으면 정밀도는 정의상 1.0이므로 결과의 절반이 무의미합니다. 이유를 설명하고 대신 인접 사례를 요청하십시오.
5단계 — 스위트 작성
두 개의 템플릿 파일을 사용자의 작업 트리(${CLAUDE_PLUGIN_ROOT}/reference/repo-layout.md를 따라 찾음. 저장소에 없으면 위치를 제안하고 질문)에 복사하십시오:
${CLAUDE_PLUGIN_ROOT}/reference/templates/activation.yaml${CLAUDE_PLUGIN_ROOT}/reference/templates/activation-rows.jsonl
그런 다음 대체하십시오. JSONL은 YAML 옆에 유지(dataset.paths 항목은 작업 파일을 기준으로 해석):
task_id→<skill-name>-activationskill_name→ 기본 스킬 이름- 각 긍정 행의
expected_skill→ 동일한 기본 이름; 방해 행은""유지; 형제 소유 행의expected_skill→ 해당 형제의 기본 이름 - 모든 행의
prompt→ 4단계에서 설계된 요청, 한 줄에 하나의 JSON 객체
그런 다음 스킬에 도달할 수 있도록 만드십시오. 이 단계가 스위트가 실제로 무언가를 측정하는지 결정합니다. 작업은 사용자의 파일이 전혀 없는 새로운 샌드박스에서 실행되므로, 작업이 스킬의 위치를 알려주지 않으면 에이전트는 아무 스킬도 제공받지 못합니다. 이것이 템플릿의 agent.plugins 블록입니다 — 그리고 이미 스킬을 노출시키는 항목이 없는 경우에만 템플릿이 이 블록을 담당합니다: 3단계에서 해당 블록을 제공하는 실험을 찾았다면 상속받고 템플릿의 복사본을 삭제하여 두 번째 선언을 작성하지 마십시오.
그렇지 않으면 채우십시오. path는 플러그인 루트여야 합니다: skills/ 하위 디렉토리를 포함하는 디렉토리로, 스킬이 <path>/skills/<skill-name>/SKILL.md에 위치하도록 합니다. .claude-plugin/plugin.json은 선택 사항입니다 — 없으면 네임스페이스는 디렉토리 자체 이름으로 기본 설정됩니다.
.claude/skills/pdf-forms/SKILL.md의 경우 해당 루트는 **.claude**이며, .claude/skills가 아닙니다. 스킬 디렉토리만 있는 디렉토리를 가리키면 아무것도 로드되지 않습니다.
.claude 자체를 가리키는 대신 최소한의 루트를 준비하십시오. 플러그인 루트는 스킬뿐만 아니라 전체 플러그인을 로드합니다: skills/ 옆에 있는 agents/, commands/ 또는 hooks/ 디렉토리도 평가되는 에이전트에게 표시됩니다. 저장소의 .claude를 가리키면 모든 프로젝트 서브에이전트와 명령을 에이전트에 제공하게 됩니다. 그리고 요청에 응답할 수 있는 서브에이전트는 세부 사항이 아니라 혼란 요인입니다. pdf-forms를 측정하는 동안 .claude/agents/pdf-expert.md가 존재하면 에이전트는 스킬을 호출하는 대신 해당 서브에이전트에 위임할 수 있습니다. skill_triggered는 no를 기록하고, 스킬의 설명과는 전혀 무관한 이유로 재현율이 떨어집니다. 또한 숫자가 저장소에 의존하게 되어 두 스위트를 더 이상 비교할 수 없게 됩니다.
따라서 테스트 대상 단위만 정확히 포함하는 루트를 구축하고, 해당 루트를 가리키십시오:
SKILL_ROOT="$(mktemp -d)"
mkdir -p "$SKILL_ROOT/skills"
ln -s "$(pwd)/.claude/skills/pdf-forms" "$SKILL_ROOT/skills/pdf-forms"
export SKILL_SOURCE_PATH="$SKILL_ROOT"
심볼릭 링크가 까다로운 경우(Windows, 일부 CI 이미지) ln -s 대신 cp -R을 사용하십시오. 사용자가 한 줄 명령을 선호하는 경우 export SKILL_SOURCE_PATH="$(pwd)/.claude"도 작동합니다 — 단, .claude 아래의 모든 것도 노출되므로 낮은 재현율이 형제 스킬 때문일 수 있다는 점을 명확히 말하십시오.
YAML에 절대 경로를 하드코딩하는 대신 환경 변수로 유지하십시오. 스위트는 커밋되어 다른 머신에서 다시 실행됩니다. 변수가 설정되지 않으면 스킬이 단순히 존재하지 않게 되고, 모든 긍정 행이 0점을 받으며, 결과는 스킬이 절대 트리거되지 않는 경우와 구분할 수 없게 되므로, 낮은 재현율 결과를 보고하기 전에 변수가 설정되었는지 확인하십시오.
skill_name은 스킬이 플러그인에서 와서 plugin:skill로 호출되더라도 기본 이름이어야 합니다 — 검사기는 비교 전에 네임스페이스를 제거합니다. 여기서 네임스페이스가 포함된 값을 사용하면 모든 행에서 조용히 0점 재현율을 기록하며, 이는 마치 고장난 스킬처럼 보입니다.
매칭이 기본 이름으로 이루어지기 때문에 이름 충돌을 견딜 수 없습니다. 두 개의 init 스킬(하나는 플러그인, 하나는 내장)은 기준에 대해 동일한 문자열이므로, 어느 것이 발사되든 테스트 대상인 것처럼 인정합니다. 결과를 신뢰하기 전에 설치된 모든 것에서 이름이 고유한지 확인하십시오(/context 및 /doctor가 활성 세트를 나열합니다). 충돌은 오류를 발생시키지 않으며, 잘못된 스킬을 측정합니다. 충돌이 존재하면 숫자를 보고하지 말고 언급하십시오 — 스킬 이름을 바꾸거나 충돌이 없는 곳에서 측정하는 것이 유일한 정직한 수정 방법입니다.
이 템플릿을 넘어서는 기준 필드는 ${CLAUDE_PLUGIN_ROOT}/reference/criteria.md를 읽으십시오.
6단계 — 비용을 지출하기 전에 검증
coder-eval plan <path-to-activation.yaml>이 0으로 종료되어야 합니다. 스키마 확인만 수행하며 데이터 세트 파일은 읽지 않습니다. 따라서 JSONL이 YAML 옆에 있고 한 줄에 하나의 객체가 있는지도 확인하십시오.
7단계 — 실행
모든 행은 전체 에이전트 실행입니다: N개의 행은 N번의 실행과 실제 토큰 비용을 의미합니다. 행 수와 사용될 에이전트/모델을 명시한 후, 시작하기 전에 질문하십시오.
coder-eval run <path-to-activation.yaml>
기준은 에이전트에 구애받지 않습니다 — Skill 도구를 통해 Claude가 스킬을 사용하는 것을 감지하고, 해당 도구가 없는 모든 에이전트(예: Codex)에 대해서는 디스크에서 스킬 파일을 읽어 감지합니다 — 따라서 동일한 스위트가 작업이 해결하는 에이전트에 관계없이 작동합니다.
8단계 — 보고 및 해석
재현율, 정밀도, F1 및 혼동 행렬을 제시한 후, 그 의미를 설명하십시오:
- 낮은 재현율 (잡았어야 할 행을 놓침): 설명이 과소 주장한다고 결론 내리기 전에 잘림 및 목록 제거를 먼저 배제하십시오. 둘 다 잘못된 문구와 구분할 수 없는 낮은 재현율 결과를 생성하며, 둘 다 확인하는 데 비용이 거의 들지 않습니다:
/doctor는 목록의 컨텍스트 비용과 가장 큰 기여자를 추정하며,/context의 스킬 행은 예산이 적용된 후의 목록 크기를 보고합니다 — 이것이 모델이 실제로 수신한 것입니다. 설명이 목록에 있고 스킬별 잘림 한도 내에 있다는 것이 입증된 후에야 문구가 원인입니다: 트리거해야 할 상황, 파일 형식 또는 표현을 명명하지 않습니다. - 낮은 정밀도 (방해 행에서 발사): 설명이 과도하게 주장하며 인접 요청을 가로채고 있습니다. 설명을 좁히고, 스킬이 무엇을 위한 것이 아닌지 명시적으로 말하십시오.
- 오발이 하나의 형제 스킬에 집중됨 (형제 소유 행 포함): 이는 하나의 모호한 설명이 아니라 두 설명 간의 경계 분쟁입니다. 테스트 중인 스킬만 수정하면 실패가 이동하는 경향이 있을 뿐 제거되지는 않습니다 — 각 스킬이 무엇을 위한 것이 아닌지 명시적으로 말하고, 다시 실행하십시오.
- 둘 다 높음: 숫자와 행 수를 보고하고, 작은 스위트는 많은 것을 말해주지 않는다는 점을 언급하며 확장할 것을 제안하십시오.
편집할 대상으로 프론트매터 description을 지적하고, 특정 행을 인용하십시오.