Claude Code의 skill-creator로 기존 skill을 검증해 보았다

개요

Anthropic이 공개하고 있는 Agent Skills를 위한 공식 리포지토리입니다.

샘플 skill의 구성이나 Claude Code로부터의 플러그인 이용 절차 등이 README에 정리되어 있습니다.

이전에 작성한 zenn-blog-writing skill을 제대로 측정하고 싶었기에, Claude Code에서 사용할 수 있는 skill-creator에 주목했습니다.

검증 플로우를 밟으면서 benchmark를 통해 기존 skill의 정밀도가 어떻게 보이는지 시험하고 측정해 보았습니다.

본 기사에서는 그 결과로부터 읽어낼 수 있는 skill의 효과와 실제로 수행한 개선까지를 정리하고 있습니다.

왜 검증하려고 했는가

skill을 준비하는 것 자체는 비교적 간단합니다.

반면 「제대로 효과가 있는지」를 확인하는 수단이 부족한 경우도 있습니다.

textlint처럼 규칙을 정의하여 기계적으로 패스할 수 있는지 확인할 수 있는 것도 아니어서, skill을 거친 출력의 좋고 나쁨은 주관적인 판단이 되기 쉬웠습니다.

재현 가능한 태스크와 스코어로 효과를 파악하고 싶었던 것이 출발점입니다.

skill-creator란

그 하나의 수단으로서, Claude Code에는 skill-creator라는 skill이 준비되어 있습니다.

Claude Code의 skill (.claude/skills/ 하위의 SKILL.md)을 작성·개선·평가하기 위한 skill입니다.

주요 기능은 다음 3가지입니다.

• 「작성」 기능에서는 요구사항으로부터 새로운 skill을 생성합니다.
• 「개선」 기능에서는 기존 skill의 기술을 정밀 조사 및 수정합니다.
• 「평가」 기능에서는 eval을 실행하여 skill의 유무에 따른 품질 차이를 수치화합니다.

eval은 「태스크 정의」, 「기대하는 출력 조건」, 「채점 로직」을 세트로 관리합니다.

1회의 benchmark에서 여러 개의 eval을 실행하여, with / without skill의 차이를 스코어로 비교합니다.

skill-creator가 벤치마크 결과를 반환하기까지

skill-creator를 이용하면 임시 폴더에 벤치마크 결과가 출력되어 HTML로 확인할 수 있는 상태가 됩니다.

실행 로그와 리포트 화면의 이미지는 다음과 같습니다.

검증 대상: zenn-blog-writing skill

이번에 검증한 zenn-blog-writing skill은 Zenn의 기술 기사를 작성할 때의 가이드라인 모음입니다.

커버하고 있는 내용은 주로 다음과 같습니다.

• frontmatter의 형식 (topics의 기호 불가 규칙 등)
• 문장 품질 기준 (문장 길이·능동태·AI스러운 표현 회피)
• 코드 블록의 언어 지정
• textlint 체크와의 연동

기술 기사를 쓸 때마다 스스로 규칙을 떠올리는 것이 번거로워 만들었지만, 얼마나 출력 품질에 영향을 미치고 있는지는 측정한 적이 없었습니다.

skill의 경위나 프로젝트에서의 운용, SKILL.md의 구성에 대해서는 다음 기사에 정리해 두었습니다.

검증 순서

/skill-creator를 호출하여, benchmark 모드로 실행합니다.

# Claude Code의 REPL 상에서
/skill-creator benchmark zenn-blog-writing

skill-creator가 eval 태스크를 자동 생성하고, with / without의 2가지 조건으로 실행합니다.

각 eval에는 채점 기준(rubric)이 설정되어 있으며, 스코어가 반환됩니다.

이번에는 2회 반복(iteration)을 실시했습니다.

iter-1의 결과로부터 skill을 개선하고, iter-2에서 재측정하는 흐름입니다.

iteration-1의 결과

3개의 eval을 실행했습니다. 태스크의 개요와 결과는 다음과 같습니다.

eval	태스크 개요	skill 있음	skill 없음
eval-1	AI 표현 리뷰	5/5 (100%)	4/5 (80%)
...		77.8%

skill 유무에 따른 차이는 **16.7%**였습니다.

일관되게 스코어 차이가 나타나고 있습니다.

비용은 skill이 있는 쪽이 약 3300 tokens 더 많았고, 처리 시간은 약 4초 더 느렸습니다.

어디에서 차이가 났는가

eval-1 (AI 표현 리뷰)

유일하게 탈락한 것은 topics-lowercase였습니다.

skill이 없는 경우는 ["React", "TypeScript", "JavaScript"]를 대문자 그대로 출력했습니다.

Zenn은 topics에 기호나 공백을 금지하고 있지만, 대소문자에 대해서는 명시적인 에러를 발생시키지 않습니다.

따라서 모델이 "대충 맞는 것 같다"라고 판단한 표기를 그대로 사용해 버린 것으로 생각됩니다.

eval-2 (신규 기사 작성)

점수는 동률이었지만, 탈락한 항목이 달랐습니다.

skill이 없는 경우의 FAIL은 topics에 "Node.js"와 "GitHub Actions"를 사용한 것이었습니다.

마침표와 공백이 포함되어 있어 Zenn에 게시하면 에러가 발생하는, 실질적인 피해가 있는 문제였습니다.

skill이 있는 경우의 FAIL은 코드 블록 (code block)의 언어 지정 누락입니다.

다만 이는 skill의 설계라기보다는 실행 컨텍스트 (execution context)에 가까운 문제였습니다.

캐시 확인 로그를 자세히 작성하려다 보니, 일반 텍스트 (plain text) 블록이 생성되었습니다.

skill에는 터미널 출력의 언어 지정 (text / console)이 정의되어 있지 않아 대처할 수 없었습니다.

skill이 없는 경우는 짧은 기사를 작성했기에 우연히 PASS가 되었을 뿐, 같은 상황이 되면 동일하게 누락될 것이라고 생각합니다.

eval-3 (frontmatter 수정)

가장 차이가 크게 나타난 eval이었습니다.

skill이 없는 경우는 "보고된 문제(topics)는 수정했지만, 지시되지 않은 세부 사항(emoji와 type의 따옴표)은 놓쳤다"라는 결과가 나왔습니다.

# skill이 없는 출력 예시 (따옴표 없음)
emoji: 🔧
type: tech
...

둘 다 YAML로서는 동작하지만, Zenn의 공식 샘플은 따옴표를 붙이는 스타일을 채택하고 있습니다.

skill 기술 내용에 명시적으로 적혀 있었기 때문에, skill이 있는 경우는 부차적인 수정까지 커버했습니다.

skill의 개선 (iteration-1 → iteration-2)

iter-1의 결과로부터 다음 3가지를 수정했습니다.

1. frontmatter 템플릿을 skill 서두에 명시

따옴표 규칙이 skill 본문에 산재해 있었습니다.

title ・ emoji ・ type의 3개 필드에 더블 쿼트 (double quote)가 필수임을 강조하고, 정답 템플릿을 skill 서두에 집약했습니다.

2. topics 변환 패턴 표 확충

GitHub Actions → githubactions, CI/CD → cicd, VS Code → vscode 등, 공백이나 슬래시(/)를 포함하는 기술명 변환 규칙을 추가했습니다.

3. 로그 출력의 코드 블록 언어 지정 명기

터미널 출력 및 로그 표시에는 text 또는 console을 사용하도록 추가했습니다.

iteration-2의 결과

항목	iter-1 with	iter-2 with	iter-1 without	iter-2 without
종합 통과율	94.4%	100%	77.8%	83.3%
eval-1	5/5	5/5	4/5	4/5
eval-2	5/6	6/6	5/6	6/6
eval-3	7/7	7/7	5/7	5/7

skill이 있는 경우가 **전체 18개 어서션 (assertion)에서 만점 (100%)**을 달성했습니다.

skill이 없는 경우도 Eval 2가 5/6 → 6/6으로 개선되었지만, 이는 우연이라고 판단하고 있습니다.

iter-2에서는 topics를 올바른 형식으로 작성했지만, Markdown에서 "중요"를 굵게 표시하고 콜론(:)으로 끝내는 식의 강조가 남아 있었습니다.

이 어서션은 현재 eval 범위 밖이었기 때문에 PASS가 되었지만, 본래는 문제가 있는 출력입니다.

Eval 1과 Eval 3는 2회 연속으로 동일한 항목에서 탈락했습니다.

"topics의 대소문자", "emoji·type의 따옴표"는 모델이 자발적으로 학습하는 것이 아니라, skill에 적혀 있기 때문에 일관되게 지켜진다고 느꼈습니다.

비용은 iter-2에서 skill이 있을 때 약 +3,027 tokens, 처리 시간이 약 +7.4초로 미세하게 증가했습니다 (템플릿과 변환표를 추가한 분량입니다).

2. 이터레이션(Iteration)을 통한 깨달음

가설과의 대조

• 「frontmatter의 형식은 skill이 없어도 어느 정도 지킬 수 있다」 →
  절반은 정답입니다. 필수 필드의 유무는 지킬 수 있는 반면, 따옴표(quote) 스타일이나 topics의 소문자 규칙은 2 이터레이션 연속으로 놓쳤습니다.
• 「AI스러운 표현의 회피는 skill이 명시적으로 효과를 발휘한다」 →
  빗나갔습니다. AI 표현 배제는 둘 다 통과했으며, 이는 모델이 이미 가지고 있는 능력이라고 생각합니다.
• 「skill이 길어지면 제약이 약해질 가능성이 있다」 →
  현재로서는 부정적입니다. 템플릿을 서두에 집약함으로써 100%를 달성했습니다. 길이보다는 정리 방식이 효과가 있었을 가능성이 있습니다.

skill의 가치는 「Zenn 고유의 관습을 매번 확실하게 적용하는 것」에 있다

topics의 소문자 규칙, frontmatter의 따옴표 스타일은 일반적인 Markdown 지식만으로는 잡아낼 수 없습니다.

모델이 「어쩐지 맞을 것 같다」고 판단하는 표기와 Zenn이 요구하는 표기 사이에는 격차가 있습니다.

이 격차를 명문화한 것이 skill의 본질적인 가치였습니다.

benchmark에서 FAIL의 「성질」을 구분할 수 있다

iter-1의 Eval 2에서 skill이 있을 때 FAIL한 건은 「skill의 규칙 누락」이었습니다.

skill이 없는 FAIL은 「Zenn 사양을 모르는」 문제였습니다.

점수가 같은 5/6라도 대응해야 할 내용은 완전히 다릅니다.

benchmark는 이 구분을 가시화해 줍니다.

남은 개선 여지

• topics-lowercase
  어설션(Assertion)이 Eval 1 without_skill에서 2회 연속 FAIL했습니다. skill의 description 최적화를 통해 트리거 정밀도를 높일 여지가 있습니다.
• 「굵은 글씨의 『중요』 뒤에 콜론을 붙이는」 패턴이 현재 eval에서는 검출되지 않고 있습니다. no-ai-expressions의 검출 범위를 확장할 가치가 있습니다.

skill 평가를 습관화하는 것의 의미

skill은 작성하면 끝이 아닙니다.

모델의 버전이 바뀌면 동작도 바뀝니다.

프로젝트의 요구사항이 바뀌면 skill에 적힌 내용이 실정(actual situation)과 어긋날 수도 있습니다.

benchmark를 정기적으로 실행하는 습관을 들임으로써,

「어쩐지 쓰고 있는 skill」에서 「작동하고 있음을 알고 있는 skill」로 변합니다.

코드의 테스트(test)와 유사한 감각입니다.

diff를 보고 무엇이 변했는지 파악하는 것과 마찬가지로,

skill의 품질 변화도 추적할 수 있습니다.

요약

2 이터레이션 결과, skill이 있을 때는 94.4% → 100%, skill이 없을 때는 77.8% → 83.3%가 되었습니다.

둘 다 점수가 올랐지만 이유는 다릅니다.

skill이 있는 경우는 의도적인 개선(템플릿 정리, 변환표 추가)의 결과입니다.

skill이 없는 경우의 개선은 eval의 확률적인 변동(variation)이며, 2회 연속 떨어진 어설션은 변하지 않았습니다.

skill의 가치는 「모델이 모르는 것을 가르치는 것」보다, 「Zenn 고유의 관습을 매번 확실하게 적용시키는 것」 쪽에 있었습니다.

topics의 소문자 규칙, frontmatter의 따옴표 스타일은 모델이 자발적으로 지키는 경우가 드뭅니다.

「어쩐지 맞을 것 같은」 표기와 「Zenn이 요구하는 표기」 사이의 격차를 메우는 것이 skill의 역할이라고 정리했습니다.

benchmark는 「점수를 내기 위해서」라기보다, 「FAIL의 성질을 구분하기 위해서」 사용하는 것이라고 느꼈습니다.

점수가 같더라도 왜 떨어졌는지가 다르면 대응도 다릅니다.

이 구분 없이 skill을 개선하려고 하면 효과 없는 변경을 반복하기 쉽습니다.