52k 스타 리포지토리에 스킬 린터(Skill Linter)를 적용해 보았습니다. 84/100점의 결과는 이렇습니다.

당신이 작성하는 모든 AI 에이전트 스킬은 매 턴마다 컨텍스트 (Context)를 소모합니다.

단순히 스킬이 실행될 때뿐만이 아닙니다. 매 턴마다 그렇습니다. 에이전트는 각 스킬을 언제 호출해야 할지 알 수 있도록 스킬의 이름과 설명을 영구적으로 로드해 둡니다. 모호한 설명은 단순한 문서화의 문제가 아닙니다. 그것은 메시지당, 그리고 영원히 지불해야 하는 세금입니다.

이것이 바로 제가 skillscore를 만들어 해결하고자 했던 문제입니다.

addyosmani/agent-skills가 52,000개의 스타를 기록하며 GitHub 트렌딩 1위에 올랐을 때, 저에게는 벤치마크 대상이 생겼습니다. 분명히 전문가들이 작성한 24개의 프로덕션급 (Production-grade) 스킬들이 있었습니다. 만약 정적 린터 (Static linter)가 이 정도 수준에서 유의미한 말을 할 수 있다면, 바로 여기서 확인할 수 있을 것입니다.

그래서 실행해 보았습니다.

한 번의 명령. 24개의 스킬. 2초.

현재 skillscore 0.2.0이 할 수 있는 일은 다음과 같습니다:

skillscore /path/to/agent-skills/

단 한 번의 명령으로 트리 내의 모든 것을 점수화합니다. 출력 결과는 다음과 같습니다:

addyosmani/agent-skills의 스킬 3개가 한 번의 명령으로 점수화되었으며, 점수가 가장 낮은 스킬을 상세 분석한 결과입니다.

전체 결과

스킬 (Skill)	점수 (Score)	등급 (Grade)
spec-driven-development	91	A
...	...	...
평균: 84/100 (B)

분명히 말씀드리자면, 24개의 프로덕션 스킬 전체에서 84점을 기록한 것은 매우 훌륭한 결과입니다. 실패한 스킬도 없었고, D 등급도 없었습니다. 제가 테스트한 대부분의 스킬 라이브러리들은 이 점수에 근접하지 못했습니다. 이 스킬들 내부의 지시문 (Instruction) 콘텐츠는 진정으로 훌륭합니다. 린터가 찾아낸 문제점들은 핵심적인 부분이 아니라 가장자리에 있었습니다.

두 가지 격차. 다섯 개의 스킬. 모두 C 등급.

C 등급을 받은 다섯 개의 스킬을 상세히 분석했습니다. 모든 스킬에서 동일한 두 가지 발견 사항이 나타났습니다.

설명에 언제 멈춰야 하는지가 명시되어 있지 않음

모든 C 등급의 설명은 해당 스킬이 무엇을 하는지는 말해줍니다. 하지만 언제 사용하지 말아야 하는지는 말해주지 않습니다.

이것이 중요한 이유는 중단 조건 (Stop condition)이 없는 에이전트는 느슨하게 관련된 요청까지 처리하기 위해 스킬을 무리하게 확장하여 사용하기 때문입니다. 사용하지 말아야 할 때 호출하게 됩니다. 당신이 경계를 알려주지 않았기 때문에 에이전트는 어디가 경계인지 알지 못합니다.

해결책은 설명 끝에 한 문장을 추가하는 것입니다:

"이미 코드베이스에 이를 위한 확립된 패턴이 있는 경우에는 사용하지 마십시오."

그게 전부입니다. 단 한 문장입니다. 이 문장 하나로 해당 스킬이 잘못된 요청에 활성화될 가능성이 즉시 낮아집니다.

Safety 섹션이 없는 터미널 명령어

C등급 스킬 중 여러 개는 본문에 단계별 터미널 명령어를 포함하여 전달합니다. 하지만 그 중 어느 것도 ## Safety 섹션을 가지고 있지 않습니다.

Antigravity 작성 가이드에 따르면, 명령어를 실행하는 모든 스킬은 해당 명령어가 무엇을 건드리는지, 그리고 에이전트가 관리자 없이 실행해서는 안 되는 것이 무엇인지 문서화해야 합니다. 이 섹션이 없으면 린터(Linter)는 최대 8점의 감점을 적용합니다. 이유는 실무적입니다. 문서화되지 않은 명령어를 실행하는 에이전트는 그 영향 범위(Blast radius)에 대한 신호를 전혀 알 수 없기 때문입니다.

Safety 섹션은 다음과 같이 생겼습니다:

## Safety

- `git push --force`를 관리자 없이 실행하지 마십시오. 먼저 사용자에게 확인을 받으십시오.
...

단 다섯 줄입니다. 8점을 되찾았습니다.

이 두 가지를 추가하면 이 데이터셋에 있는 모든 C등급 스킬은 B 또는 A 등급 영역으로 이동합니다. 지침의 품질은 이미 갖춰져 있었습니다. 메타데이터 레이어에는 단지 이 두 가지 신호가 필요했을 뿐입니다.

직접 실행해 보기

# 설치
dart pub global activate skillscore

...

--format sarif를 사용하면 발견된 사항을 GitHub 코드 스캐닝(Code scanning)으로 파이프라인 연결하여 풀 리퀘스트(Pull request)에 인라인 주석(Inline annotations)으로 나타나게 할 수 있습니다. 더 이상 "머지(Merge)하기 전에 스킬을 확인하는 것을 잊었다"는 말은 나오지 않을 것입니다.

만약 발견된 내용이 불분명하다면, skillscore explain <rule-id>를 통해 전체 근거와 해당 규칙이 나온 가이드를 출력할 수 있습니다. 모든 출력 줄에 규칙 ID(Rule ID)가 포함되어 있는 이유가 바로 이것 때문입니다.

완전 오프라인 방식입니다. API 키가 필요 없습니다. 결정론적(Deterministic)입니다. 동일한 입력은 항상 동일한 점수를 생성하며, 이는 CI 게이트(CI gate)에서 무언가를 사용하기 위한 유일한 방법입니다.

이 실험이 실제로 증명하는 것

C등급 스킬의 격차는 일반적인 리뷰에서는 보이지 않습니다. 만약 performance-optimization을 아무런 사전 정보 없이 읽는다면, 지침이 훌륭하기 때문에 아마도 좋다고 평가할 것입니다. 인간 리뷰어는 경계 조항(Boundary clause)의 부재를 지적하거나 Safety 섹션이 누락된 것을 알아차리지 못할 것입니다. 그들은 내용을 읽고 고개를 끄덕일 것입니다.

린터 (Linter)는 읽지 않습니다. 체크할 뿐입니다. 그리고 여기서 발견한 것은, 실제 환경의 에이전트 스킬 (Agent skills)에서 가장 흔하게 나타나는 품질 격차는 잘못된 지시 사항 (Instructions)이 아니라는 점입니다. 그것은 에이전트가 스킬을 언제, 그리고 호출할지 여부를 결정하기 위해 사용하는 두세 개의 구조적 신호 (Structural signals)입니다.

이것은 해결 가능한 문제입니다. 이제 여러분은 이를 측정할 수 있는 수치를 갖게 되었습니다.

직접 시도해 보세요:

• pub.dev/packages/skillscore
• github.com/sayed3li97/skillscore
• addyosmani/agent-skills — 이 포스트에서 사용된 라이브러리

공식 작성 가이드 (Official authoring guides)

이것들은 skillscore의 규칙이 추출된 주요 출처들입니다. 도구 출력 결과의 각 발견 사항은 이 중 하나를 인용합니다. 스킬을 정기적으로 작성한다면 한 번쯤 읽어볼 가치가 있습니다.

Anthropic — Agent Skills: Best Practices
Claude Code 스킬을 위한 표준 가이드입니다. 설명의 품질 (동사, when-clause), 간결성 (본문 500행 제한), 점진적 공개 (Progressive disclosure) 패턴, 스크립트 문서화, 그리고 효과적인 SKILL.md의 전반적인 구조를 다룹니다.
platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Google Antigravity — Authoring Antigravity Skills (Google Codelabs)
Google Antigravity 스킬을 위한 공식 실습 가이드입니다. 명령어를 실행하는 스킬에 대한 Safety 섹션 요구 사항, 경계 절 (Boundary clause, "...할 때는 사용하지 마세요"), 그리고 기본적인 라우팅 (Routing)부터 절차적 스크립트 실행 (Procedural script execution)에 이르는 네 가지 수준의 스킬 복잡도를 다룹니다.
codelabs.developers.google.com/getting-started-with-antigravity-skills

Agent Skills Open Standard — Specification
모든 에이전트(Claude Code, Codex, Antigravity, Gemini CLI, Cursor)가 구현하는 형식 규격(format specification)입니다. 프론트매터(frontmatter) 필드, 디렉토리 구조, 선택적 폴더, 그리고 점진적 공개(progressive disclosure) 원칙을 정의합니다.
agentskills.io/specification