당신의 Skill이 제대로 작동하는지 추측하는 것을 멈추세요: skill-optimizer가 이를 측정하고 개선합니다

저는 Claude Code에 다음과 같은 한 문장을 입력했습니다: 이 프로젝트의 Fastify skill을 최적화해줘, 그러고는 커피를 마시러 자리를 비웠습니다.

돌아왔을 때, 저는 Matteo Collina의 fastify-best-practices skill이 실제로 얼마나 잘 작동하고 있는지에 대한 완전한 그림을 얻을 수 있었습니다. 5개의 현실적인 평가 (eval) 시나리오, 각 시나리오에 대한 기준 점수 (baseline score), 전체적인 전/후 비교, 진단된 퇴보 (regression), 제안된 수정 사항, 그리고 개선 사항을 확인하는 재실행 결과까지 말이죠. 해당 skill은 실제 시나리오 전반에 걸쳐 평균 성공률이 67%에서 94%로 상승했습니다. 저는 평가 (eval)를 단 하나도 작성하지 않았습니다. 루브릭 (rubric)을 단 하나도 설계하지 않았습니다. 저는 그저 세 단어를 말했을 뿐이고, 나머지는 skill-optimizer가 처리하도록 두었습니다.

중요 업데이트: 이제 skill-optimizer는 당신의 skill이 아예 호출되는지 여부까지 테스트할 수 있습니다. 여러 개의 skill이 포함된 플러그인에서, 에이전트 (agent)는 최적화 로직이 의미를 갖기 전에 올바른 skill로 라우팅 (routing)을 해야 합니다. 활성화 평가 (--solver=activation)는 시나리오별로 라우팅의 공백을 드러내며, 이를 해결하기 위한 설명 (description) 재작성을 자동으로 제안합니다. 이는 당신이 놓치고 있었던 것을 깨닫게 해주는 점검입니다. 또한, 결과 분석은 이제 단순한 진단 단계를 넘어 구조화된 4개 버킷 프레임워크 (working / gap / redundant / regression)를 사용합니다.

skill-optimizer 소개

SKILL.md를 작성할 때, 당신은 본질적으로 AI 에이전트 (agent)를 위한 지침을 작성하는 것입니다. 문제는 당신이 그 지침을 눈을 가린 채 작성하고 있다는 점입니다. 당신은 다음 사항들을 알지 못합니다:

• 에이전트 (agent)가 실제로 그 지침을 따르는지
• 어떤 부분이 중복되는지 (에이전트가 skill 없이도 이미 수행 방법을 알고 있는 경우)
• 어떤 부분이 퇴보 (regression)를 일으키는지 (당신의 지침이 에이전트에게 도움을 주기보다 오히려 혼란을 주는 경우)
• 저렴한 모델 (Haiku)에서도 작동하는지, 아니면 비싼 모델 (Opus)에서만 작동하는지

skill-optimizer 플러그인은 당신의 skill을 판사 점수 기반의 평가 (eval) 파이프라인에 통과시켜, 실제 작업에서 skill이 '있을 때'와 '없을 때'의 에이전트 (agent)를 테스트한 후 그 차이 (delta)를 점수화합니다. 이제 더 이상 추측할 필요가 없습니다. 모든 Jedi가 그러해야 하듯, 당신의 느낌을 뒷받침할 실제 수치를 갖게 될 것입니다.

작동 방식: 두 가지 상호 보완적인 접근 방식

이 플러그인은 두 가지 방법을 결합합니다:

1. Skill review (tessl skill review): SKILL.md 자체에 대한 정적 분석 (Static analysis)입니다. 완성도 (completeness), 실행 가능성 (actionability), 간결성 (conciseness), 그리고 견고성 (robustness)이라는 네 가지 차원에서 점수를 매깁니다. 이 단계에서는 에이전트를 실행하기도 전에 구조적인 문제를 빠르게 잡아냅니다.
2. Task evals (tessl eval run): 당신의 Skill로부터 현실적인 작업 시나리오 (Task scenarios)를 생성합니다. 각 시나리오에 대해 에이전트를 두 번 실행하며 (한 번은 기준점 (Baseline)으로서 당신의 Skill 없이, 다른 한 번은 당신의 Skill을 사용하여), 그 다음 LLM을 판사 (Judge)로 활용하여 시나리오별 루브릭 (Rubric)에 따라 두 출력값을 평가합니다. 점수 차이 (Score delta)를 통해 Skill의 가치 증분 (Value-add)을 알 수 있습니다.

optimize-skill-performance-and-instructions Skill은 이 두 가지 접근 방식을 하나의 엔드 투 엔드 (End-to-end) 사이클로 결합합니다.

실제 사례: mcollina의 fastify-best-practices skill

mcollina/skills는 현대적인 Node.js 개발을 위한 Matteo Collina의 오픈 소스 Skill 컬렉션입니다. 이미 1,200개 이상의 스타 (Stars)와 80개 이상의 포크 (Forks)를 보유하고 있습니다. Fastify, TypeScript, 린팅 (Linting), 문서화 (Documentation), 그리고 핵심 Node.js 패턴을 다루며, 각 Skill마다 SKILL.md가 있고 공유 규칙 파일들이 이를 모두 연결합니다.

우리는 fastify-best-practices Skill에 대해 skill-optimizer를 실행했습니다. 여러분도 따라 할 수 있도록 제가 수행한 과정을 가이드 형식으로 소개합니다.

실제로 일어난 일

1단계: skill optimizer skill 설치

Skills 프로젝트 내에서 다음을 실행하세요:

`tessl i tessl-labs/skill-optimizer`

그게 끝입니다! 다음에 Claude Code를 시작하면 해당 Skills를 사용할 수 있게 됩니다.

2단계: 전체 최적화 사이클 시작

Claude Code 내부에서 저는 단 한 가지만 요청했습니다:

`Please optimize the Fastify skill in this project`

잊지 마세요, 항상 'please'라고 말하세요! 이 요청은 optimize-skill-performance-and-instructions라는 스킬을 트리거했습니다. 이는 필요에 따라 다른 스킬들을 호출하는 플러그인 내의 최상위 스킬입니다. Claude Code는 거기서부터 작업을 이어갔습니다. 단계 3부터는 Claude가 자동으로 실행한 전체 시퀀스와 각 단계에서 어떤 일이 일어났는지 확인할 수 있습니다.

단계 2a: 스킬 리뷰 (Stage 1)

Claude Code는 Tessl을 사용하여 Fastify 스킬에 대한 리뷰를 수행하며 시작합니다.

`tessl skill review skills/fastify/SKILL.md`

결과는 고무적이었습니다:

`Average Score: 100%

  Description: 100%
...

만점입니다. 설명(Description) 부분은 명시적인 Use when 가이드, 자연스러운 트리거 용어(Fastify, server.ts, app.ts, Pino), 그리고 일반적인 Node.js 스킬과 충돌하지 않도록 하는 명확한 Fastify 전용 용어 사용 덕분에 찬사를 받았습니다.

물론 저에게는 놀라운 일이 아니었습니다. 저는 이미 이전 PR에서 Matteo와 함께 이 모든 것들을 개선하기 위해 작업한 적이 있기 때문입니다.

하지만 여기서 중요한 교훈이 있습니다: 완벽한 리뷰 점수가 당신의 스킬이 실제로 작동한다는 것을 의미하지는 않습니다. 정적 리뷰(Static review)는 지침(Instructions)이 잘 구성되어 있는지를 알려줄 뿐입니다. 에이전트가 그 지침을 실제로 따르는지는 알려주지 않습니다. 그것이 바로 평가(Evals)가 필요한 이유입니다.

당신의 스킬이 호출되기는 하나요?

스킬에 새로 추가된 기능입니다! 플러그인에 여러 스킬이 포함되어 있을 때, 점수 산정 로직이 실행되기 전에 거쳐야 하는 단계가 있습니다. 바로 에이전트가 작업에 적합한 스킬을 선택해야 한다는 것입니다. 에이전트는 각 시나리오를 읽고, 당신의 스킬 설명을 살펴본 뒤, 그에 따라 경로를 지정(Route)합니다. 이 과정이 잘못되면, 당신의 평가 점수는 완전히 엉뚱한 것을 측정하게 됩니다.

이것이 바로 활성화 평가(Activation evals)의 목적입니다. 출력값(Outputs)에 점수를 매기는 대신, 이들은 더 간단한 질문을 던집니다: '올바른 스킬이 실제로 실행되었는가?'

tessl eval run <path/to/plugin> --solver=activation

출력값은 각 시나리오(scenario)에 대해 어떤 스킬(skill)이 활성화되었는지, 혹은 아무것도 활성화되지 않았는지를 보여줍니다. 에이전트(agent)가 작업을 검토했으나 관련이 있다고 판단되는 스킬을 찾지 못했을 수도 있습니다. Skill-optimizer는 사용자의 스킬 설명(skill descriptions)과 실패한 시나리오를 자동으로 읽고, 그 간극을 메우기 위한 최소한의 재작성(rewrites)을 제안합니다.

이것이 중요한 이유는 점수가 매겨지는 평가(scored evals)는 스킬이 일단 실행되었을 때 얼마나 잘 수행되는지만 알려주기 때문입니다. 만약 스킬이 애초에 실행조차 되지 않는다면, 아무리 지시문(instruction)을 다듬어도 점수는 올라가지 않을 것입니다.

Step 2b: 평가 시나리오 생성 (Stage 2)

그 다음 Claude는 Tessl을 사용하여 해당 스킬에 대한 5가지 실제 세계 시나리오(real world scenarios)를 생성했습니다:

`tessl scenario generate . --count=5`

생성된 다양한 시나리오들은 다음과 같습니다.

스킬의 핵심 영역을 다루는 현실적이고 범위가 잘 정해진 5가지 시나리오: 프로덕션 설정(production config), 스키마 검증(schema validation), 인증(auth), 데이터베이스 플러그인(database plugins), 그리고 테스트를 포함한 파일 처리(file handling)입니다.

Step 2c: 평가 실행 (Stage 3)

시나리오 생성에 이어, Claude는 Tessl과 함께 claude-sonnet-4-6 모델을 사용하여 각 시나리오를 평가(eval)로 실행했습니다:

`tessl eval run . --agent=claude:claude-sonnet-4-6`

Claude Code는 모니터링 URL을 공유하고 몇 분마다 상태를 확인(polls)합니다.

Step 2d: 결과 분석 (Stage 4)

결과는 다음과 같습니다:

큰 이득을 얻은 세 가지 시나리오, 한 가지의 완만한 이득, 그리고 한 가지의 퇴보(regression)가 나타납니다. 프로덕션 설정(production config) 시나리오가 단연 눈에 띕니다. 해당 스킬을 통해 에이전트의 점수가 41%에서 완벽한 100%로 상승했습니다. 스킬이 없었을 때 에이전트는 env-schema, close-with-grace, 또는 @fastify/under-pressure를 호출해야 한다는 사실을 전혀 알지 못했습니다. 하지만 스킬이 도입되자 모든 체크 항목을 완벽하게 수행했습니다.

데이터베이스 시나리오에서의 퇴보(regression)는 주의가 필요하지만, 이 수정 사항이 없었다면 우리는 이를 알 수 없었을 것입니다!

단순한 합격/불합격이 아닌 네 가지 범주

앞서 skill-optimizer가 격차를 진단하는 방식을 설명할 때, 저는 이를 스킬에 무엇이 누락되었는지를 식별하는 것으로 표현했습니다. 그 말은 여전히 유효하지만, 현재 버전은 훨씬 더 구조화되어 있습니다. 이제 평가(eval) 결과의 모든 기준은 다음 네 가지 범주 중 하나로 분류됩니다:

• 잘 작동함 (Working well): 스킬 적용 시 점수(with-skill score)가 높고 베이스라인(baseline)보다 유의미하게 높습니다. 이것은 여러분의 강점입니다. 그대로 두세요.
• 플러그인 격차 (Plugin gap): 베이스라인과 스킬 적용 시 점수 모두 낮습니다. 에이전트는 여러분의 도움 없이는 이를 알지 못하며, 스킬 또한 아직 이를 가르치지 못하고 있습니다. 이 부분은 수정했을 때 가장 높은 수익(return)을 기대할 수 있습니다.
• 중복됨 (Redundant): 스킬 없이도 베이스라인이 이미 높습니다. 에이전트는 일반적인 학습을 통해 이미 이를 알고 있으며, 이는 여러분의 지시사항이 이 기준에 대해 가치를 더하지 못한 채 컨텍스트 오버헤드(context overhead)만 추가하고 있음을 의미합니다.
• 퇴보 (Regression): 스킬 적용 시 점수가 베이스라인보다 낮습니다. 스킬이 이 지점에서 에이전트를 적극적으로 혼란스럽게 만들고 있습니다. 해결해야 할 최우선 순위입니다.

중복되는 버킷(redundant bucket)은 사람들이 방심하기 쉬운 부분입니다. 더 많은 가이드가 항상 더 낫다는 본능적인 생각이 들 수 있지만, 모델이 이미 잘 수행하고 있는 내용을 다루는 지침은 단지 어텐션 예산(attention budget)만 차지할 뿐입니다. skill-optimizer는 이러한 부분을 플래그(flag)로 표시하고, 해당 기준을 아예 제거하거나, 당신의 스킬이 실제로 기여하는 바를 테스트할 수 있는 더 어려운 시나리오로 교체할 것을 제안합니다.

Step 2e: 진단 및 수정 (Stage 5)

회귀(Regression): database-plugin-architecture

체크별 세부 분석(per-check breakdown)을 파고들면 문제가 드러납니다:

  `Scenario 4: Database plugin architecture with official adapters

  Baseline (without context)
...

에이전트가 스킬 없이도 잘 처리했던 두 가지 체크 항목이 스킬 적용 후 오히려 악화되었습니다. Claude Code는 원인을 다음과 같이 진단했습니다: hooks.md에 콜백 스타일(callback-style)의 AVOID 예시가 포함되어 있어 에이전트의 비동기 훅(async hook) 구현을 혼란스럽게 만들었습니다. 또한 database.md에는 라우트 핸들러(route handlers)에서의 구조화된 로깅(structured logging) 예시가 없었으며, 이로 인해 베이스라인 에이전트가 스스로 부분적으로 채우고 있던 공백이 생겼습니다.

공백(Gaps): TypeBox 스키마 시나리오

  `Shared schema with $id and $ref              0/8  (0%)   → 두 실행 모두 동일한 점수
  additionalProperties: false on input schemas 0/8  (0%)   → 스킬이 이를 가르치지 않음
  @fastify/error used                          0/10  (0%)  → 스킬에 언급되지 않음`

결과적으로 이것들은 회귀(regression)가 아니라, 스킬이 해당 내용들을 전혀 다루지 못하고 있었던 것이었습니다.

다음은 Claude가 자동으로 수행한 수정 사항의 요약입니다: