귀하의 팀은 API용 스킬을 출시했습니다. 이 스킬은 깔끔하게 설치되며, 데모에서는 코딩 에이전트가 올바르게 보이는 통합 코드를 작성합니다. 그러다가 누군가가 에이전트가 그 스킬과 제품을 더 정확하게 통합하는지, 아니면 단순히 토큰만 추가하고 유지보수 작업만 늘리는 것인지 묻습니다. 아무도 답을 보여줄 수 없습니다.
이를 알아내기 위해서는 통제된 조건 하에서 동등한 통합 작업을 비교하고 비용과 함께 올바른 결과(correct outcomes)를 측정해야 합니다. 성공적인 스킬 로드가 통합이 성공했다는 증거가 아닙니다. 스킬은 동일한 작업이 스킬 유무에 따라 실행되었을 때, 수용 가능한 비용으로 더 많은 정확한 통합 결과를 만들어낼 때 그 자리를 얻게 됩니다.
이제 하나의 스킬이 여러 에이전트에 도달할 수 있습니다. Anthropic의 Agentic AI Foundation에 에이전트 스킬 기증 게시물(2026년 10월 22일)에는 "ChatGPT, Cursor, GitHub Copilot, VS Code를 포함하여 70개 이상의 에이전트 플랫폼이 Agent Skills를 통합했습니다."라고 명시되어 있습니다. 여기에 인용된 모든 결과는 자체 실행 기록을 발표한 팀에서 나온 것이며, 각각의 한계가 존재합니다.
핵심 요약 (TL;DR)
- 각 통합 작업을 스킬 유무에 따라 두 번 실행하고 다른 것은 아무것도 변경하지 마십시오. 기본 에이전트는 문서를 읽을 수 있어야 합니다.
- 출력 품질과 별개로 활성화(activation)를 테스트하십시오. 스킬 로드를 강제한다고 해서 개발자의 일반적인 프롬프트가 이를 트리거하는지 여부는 알 수 없습니다.
- 점수화하기 전에 승인 검사(acceptance checks)를 작성하고, 통과 또는 실패와 함께 시간, 토큰, 재시도 횟수, 인간의 도움을 기록하십시오.
- 실패 지점을 찾기 위해 두세 개의 작업부터 시작한 다음, 의사결정을 내리는 데 중요한 작업을 반복하십시오.
- 테스트한 워크로드를 기준으로 유지(keep), 수정(revise), 또는 제거(remove)를 결정하고, 스킬, 문서, 모델 또는 런타임이 변경될 때 다시 실행하십시오.
테스트 대상 세 가지 항목 명시
모든 결과는 한 번에 세 가지 부분을 설명합니다. 첫 번째는 특정 버전의 제품별 스킬입니다. 두 번째는 에이전트와 런타임(runtime)입니다: 모델에 도구, 설정 및 제한 사항을 적용하여 실행하는 하네스 프로그램(harness program)이 포함됩니다. 세 번째는 통합 작업(integration task)입니다. 이 중 어느 하나라도 변경하면 다른 실험을 수행하는 것입니다.
Agent Skills overview에 따르면, 활성화는 "작업이 스킬의 설명과 일치할 때" 발생하므로 런타임이 사용자의 지침이 도착하는 시점을 결정합니다. Anthropic의 skill authoring guide는 "스킬을 사용할 계획인 모든 모델로 스킬을 테스트하십시오"라고 말합니다.
스킬을 설치하기 전에 SKILL.md를 읽어보는 것은 저렴한 첫 번째 필터링 방법이며, 이는 our ranking of Claude skills for documentation의 기반이 된 접근 방식입니다. 읽기는 스킬이 무엇을 수행한다고 주장하는지 보여주지만, 페어드 런(paired run)은 그것이 사용자의 작업 결과에 변화를 주는지 보여줍니다.
무언가를 실행하기 전에 "더 좋다"는 것을 정의하십시오
API 팀에게 '더 좋다'는 것은 현재 지원되는 제품 동작에 대한 작동하는 통합을 의미합니다. 어떤 점수화도 하기 전에 작업별 수용 검사(acceptance checks)를 작성하여, 아무도 결과를 본 후에 릴리스 검사의 기준을 움직이지 않도록 해야 합니다.
두 가지 수치를 분리하여 기록하십시오. 어설션 패스율(assertion pass rate)은 개별 검사를 계산합니다. 전체 작업 성공률(whole-task success rate)은 처음부터 끝까지 작동하는 통합을 계산합니다. 실행이 5개 중 4개의 검사를 통과하더라도 위조된 요청을 수락하는 웹훅 핸들러를 배포할 수 있으므로, 두 가지 모두 기록해야 합니다.
Agent Skills 가이드(https://agentskills.io/skill-creation/evaluating-skills)는 체크가 통과로 간주되려면 구체적인 증거를 요구하며, "두 구성에서 항상 통과하는 단언문은 제거하거나 대체하라"고 조언합니다. Samuel Berthe도 같은 지적을 합니다: 스킬 유무와 관계없이 통과하는 체크는 공통 지식을 테스트하는 것입니다. 답변 자체도 프롬프트에서 제외해야 합니다. Tessl은 생성한 작업 중 30%가 채점 기준의 의미 있는 양을 작업 설명에 누설하는 것을 발견했습니다.
이러한 제거 조언은 스킬이 추가하는 가치를 측정하기 위한 것입니다. 가이드에 따르면, 그러한 단언문들은 "실제 스킬 값을 반영하지 못하면서도 스킬 사용 시 통과율을 부풀립니다." 이 가이드는 릴리스 체크(release checks)를 다루지 않습니다. 저희의 권장 사항은 다음과 같습니다: 통합이 절대 깨뜨려서는 안 되는 것, 예를 들어 변조된 webhook 페이로드를 거부하는 것과 같은 일부 체크는 수용 체크(acceptance checks)에 유지해야 합니다. 스킬 유무와 관계없이 두 실행 모두 통과하더라도 이들을 유지하십시오. 다만, 두 통과율을 비교할 때는 제외해야 합니다. Claude Code의 plugin evals는 부분적으로 "플러그인을 변경하거나 새로운 모델이 출시될 때 회귀(regressions)를 포착하기 위해" 존재합니다.
Matrix for runs that had the skill available: rows ask whether the skill loaded (loaded, not loaded, unknown) and columns ask whether the integration worked (works, fails). Loaded and works: compare cost to the baseline. Loaded and fails: diagnose the skill or setup. Not loaded and works: baseline result, skill untested. Not loaded and fails: fix the description first. Unknown: cannot credit or blame the skill. Cost is recorded separately for every run: time, tokens, retries, human help.
모든 스킬 실행을 두 축으로 읽고, 어느 쪽이든 비용(cost)을 기록해야 합니다.
두 개의 개별 실험 실행: 활성화 및 결과
스킬은 로드되지 않거나, 로드는 되더라도 작동하지 않는 통합(integration)으로 인해 실패할 수 있습니다. 각각 독립적으로 테스트해야 합니다.
첫 번째 실험은 현실적인 프롬프트(prompt)에서의 자동 활성화(automatic activation)를 확인합니다. 스킬 설명 최적화 가이드는 "스킬이 활성화되어야만 도움이 된다"는 전제에서 시작합니다. 이 가이드는 약 20개의 질의(query)를 권장하며, 그중 810개는 트리거 되어야 하고 나머지 810개는 트리거 되어서는 안 되는 질문입니다. 초기에는 각각을 세 번 실행하고, 해당 질의들을 학습 세트(train set)와 검증 세트(validation set)로 약 60/40 비율로 분할합니다. '트리거 되면 안 되는' 프롬프트는 인접한 제품에 대한 질문과 같은 근접 실패 사례(near misses)를 만드세요.
두 번째 실험은 스킬이 사용될 때의 출력 품질(output quality)을 확인합니다. 여기서는 지침(instruction)이 무엇을 하는지 테스트하는 것이므로, 에이전트에게 스킬을 로드하도록 지시할 수 있습니다. 에이전트에게 명시적으로 스킬 로드를 지시한다고 해서 일반 사용자가 이를 트리거 할 것임을 증명할 수는 없습니다. Tessl은 강제되지 않은 활성화(unforced activation)를 "41%" (2,286개 작업 중 929개)로 측정했고, 강제 활성화(forced activation)는 "98%" (2,286개 작업 중 2,240개)로 측정했습니다.
활성화 자체만으로는 결과에 대해 거의 증명할 수 없습니다. Vercel의 Next.js 16 API 작업 평가에서 명시적 지침은 "트리거율을 95%+로 개선하고 통과율(pass rate)을 79%까지 끌어올렸지만," 여전히 동일한 테스트에서 문서 인덱스(docs index)에 뒤처졌습니다.
모든 실행에 대해 활성화 여부를 '예(yes)', '아니오(no)', 또는 '알 수 없음(unknown)'으로 기록하세요. 실행 기록(run transcript)이 에이전트가 스킬을 읽는 것을 보여주면 '예'로 기록합니다. 런타임(runtime)에서 증거를 찾을 수 없다면 '알 수 없음'으로 기록하며, 런타임이 스킬 로드를 노출한다고 가정하지 마세요. 스킬 평가 도구에 대한 Hacker News 스레드의 한 댓글 작성자는 에이전트가 "트리거 조건이 존재하더라도 때때로 스킬을 가져오지 못할 수 있다"고 썼습니다.
공정한 쌍별 실행 설정 (Set up a fair paired run)
각 테스트 케이스는 두 개의 팔(arm)을 가집니다. 하나는 스킬을 사용한 실행이고 다른 하나는 스킬을 사용하지 않은 실행입니다. 평가 가이드에서는 이를 핵심 패턴이라고 부릅니다. 즉, 각 테스트 케이스를 스킬을 사용하여 한 번 실행하고, 스킬 없이 한 번 더 실행하거나 이전 버전으로 실행하여 비교할 수 있는 기준선(baseline)을 확보하는 것입니다. Anthropic의 skill-creator는 테스트 케이스당 스킬을 사용하는 서브 에이전트와 사용하지 않는 서브 에이전트를 각각 실행합니다. NVIDIA's SkillEvaluator는 설계 규칙으로 “실험 변수는 스킬이 설치되었는지 여부뿐이다”라고 제시합니다.
두 팔 모두에서 다음 사항들을 일정하게 유지해야 합니다:
- 작업 입력값과 시작 리포지토리 상태
- 권한 및 도구 접근성
- 현재 제품 문서(양쪽 팔 모두에서 접근 가능)
- 모델, 런타임 설정, 그리고 턴 수나 시간 같은 제한 사항들
오직 한 가지만 변경해야 합니다: 스킬의 사용 가능 여부 또는 어떤 버전인지입니다.
모든 실행은 격리되어야 합니다. “각 평가 실행은 깨끗한 컨텍스트에서 시작해야 합니다.” 기준선으로의 누수(leakage)도 막아야 합니다. Berthe의 규칙은 “형제 스킬(sibling skills)을 절대 로드하지 마십시오. 이들은 중복되는 가이드를 유출하여 ‘사용 안 함’ 점수를 부풀립니다.” 기준선 에이전트가 여는 리포지토리 안에 어떤 스킬 폴더도 존재하지 않도록 확인해야 합니다.
실행은 변동성이 크기 때문에 중요한 작업들을 반복해야 합니다. 평가 가이드에 따르면 “2~3개의 테스트 케이스로 시작”하고, 해당 단계에서는 “원시 패스 카운트와 델타(delta)에 집중”해야 한다고 말합니다. 왜냐하면 표준 편차는 “평가당 여러 번의 실행이 있을 때만 의미가 있기” 때문입니다. NVIDIA의 카탈로그는 대부분 스킬당 한 번의 시도에서 멈췄습니다. 그들의 스킬 중 “게시된 결과가 있는 경우, 85%가 한 번의 시도를 했으며,” 해당 게시물에는 신뢰 구간(confidence intervals)이 보고되지 않았습니다. 실패를 찾기 위해 두세 가지 작업으로 파일럿 테스트를 수행하고, 그 수치를 통계적 증거가 아닌 신호로 취급해야 합니다.
세 가지 작업을 선택하여 먼저 검사를 작성하세요
에이전트가 어려움을 겪는 곳에서 시작하세요. Anthropic의 작성 가이드(authoring guide)는 "평가를 먼저 구축하라(Build evaluations first)"고 말하며, "격차 식별: Skill 없이 대표적인 작업에 Claude를 실행하라(Identify gaps: Run Claude on representative tasks without a Skill)."로 시작합니다. 그런 다음 세 가지 유형의 작업을 선택하세요:
- 현실적인 설정 작업(Setup): 신규 고객이 현재 SDK를 사용하여 구축하는 통합.
- 실패 및 복구 작업(Failure and recovery): 에이전트가 손상된 통합에서 시작하여 원인을 찾고 수정해야 하는 경우.
- 경계 작업(Boundary): 제품이 지원하지 않는 요청이며, 올바른 답변은 이를 명시하고 지원되는 경로를 안내하는 것입니다.
점수를 매기기 전에 수용 확인(acceptance checks)을 작성하고, 실패 사례가 나타날 때마다 케이스를 추가하세요. 튜닝하는 탐색적 사례(exploratory cases)는 보류된 출시 검사(held-out release checks)와 분리하여 유지하세요. 해당 테스트는 결정했을 때만 실행해야 합니다. 왜냐하면 자신을 평가하는 사례로 튜닝된 Skill은 실제보다 더 좋아 보이게 만들기 때문입니다. 평가 가이드(evaluating guide)는 첫 번째 실행 후에 상세한 단언(detailed assertions)을 추가합니다. 공정한 평가를 위해 확인 사항을 동결하고 출시 결정을 위해 케이스를 보류하는 것이 우리의 권장 사항입니다.
예시 시나리오: 결제 API를 위한 웹훅 검증
이 예시 표는 세 가지 작업 유형을 가상의 결제 API에 적용합니다. 결과 열은 아무도 실행하지 않았기 때문에 비어 있습니다.
| 작업 유형 | 프롬프트 | 수용 확인 (Acceptance checks) | with_skill 결과 | without_skill 결과 |
|---|
| 설정 (Setup) | "현재 SDK를 사용하여 결제 서비스에 웹훅 서명 검증을 추가하세요." | 현재 SDK 문서에서 명시하는 검증 방법을 사용하고; 설정에서 서명 비밀(signing secret)을 읽어오며; 테스트에서 변조된 페이로드(tampered payload)를 거부합니다; 빌드 및 테스트가 통과됩니다. | | |
| ... | | | | |
한 행은 모든 확인 사항이 충족될 때만 통과하며, 워크시트는 통과된 확인 사항을 개별적으로 기록합니다.
각 실행 비용 기록하기
평가 가이드에서는 비용(cost)을 품질(quality) 옆에 배치하는데, 그 이유는 “출력 품질을 극적으로 개선하지만 토큰 사용량을 세 배로 늘리는 스킬은 더 좋고 저렴한 스킬과는 다른 트레이드오프이기 때문”입니다. 경과 시간, 런타임 보고 시에는 토큰 수, 재시도 횟수(retries), 그리고 인간의 개입 횟수를 기록하십시오. 측정값이 누락된 경우 '사용 불가(unavailable)'라고 작성합니다. 원본 토큰 수는 달러 비용이 아니므로 자체적인 가격 책정으로 변환해야 합니다.
스킬 변경은 비용을 크게 움직일 수 있습니다. [Wix의 스킬과 문서 비교 실행](https://www.wix.engineering/post/we-ran-250-ai-agent-evals-to-find-out-if-skills-beat-docs-the-answer-is-more-complicated-than-we-ex]에서 보듯이, 한 스킬의 코드 조각에는 내보내기 선언(export declaration)이 누락되어 “문서 실행 대비 39%의 토큰 증가”를 초래했습니다. 이것은 단일 사례입니다.
단일 시도 예시에서 NVIDIA는 cuopt-install이라는 스킬 하나가 토큰 사용량을 25,227개에서 55,582개(120.3%)로 증가시켰다고 보고하며 원인을 밝히지 않았습니다.
수정하기 전에 실패 진단하기
각 실패 클래스는 다른 수정 방법을 가리킵니다.
| 실패 클래스 | 기록에 표시된 내용 | 수정 방법 |
|---|
| 활성화 없음 (No activation) | should-trigger 프롬프트에서 활성화가 없거나 알 수 없음 | 설명을 다시 작성하고 활성화 테스트를 재실행합니다 |
| ... | | |
권한 누락(Permission gaps) 및 잘못된 검사(bad checks)는 테스트 설정에서 수정되었으며, 나머지 네 가지 클래스는 스킬 자체에서 수정되었습니다.
만약 대규모 언어 모델 심사관(LLM judge)이 실행 결과를 채점한다면, 직접 채점된 기록의 샘플을 읽어보십시오.
“에이전트는 이미 우리 문서를 읽을 수 있습니다. 왜 스킬을 추가해야 하나요?”
