skillassay 정적 분석기

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

skillassay는 Agent가 사용자 입력 전에 자동으로 로드하는 지침 파일과 Skill의 컨텍스트 비용을 harness와 작업 디렉터리 범위에 맞춰 계산하는 TypeScript/Node 정적 검사 도구입니다. CLAUDE.md, AGENTS.md, GEMINI.md와 Skill 관련 경로를 찾아 실제로 함께 로드되는 항목만 합산하며, `cl100k_base` 수치는 Claude 전용 tokenizer가 없는 한계를 반영해 proxy로 표시합니다. 1,029개 `SKILL.md`를 검사한 결과 37개의 사양 위반과 58개의 trigger clause 부재가 확인됐고, 전수 대조 기준 false-positive rate는 9.0%였습니다. 반면 33개 저장소의 중앙값 절감량은 0 tokens였으며, TF-IDF cosine 기반 trigger-overlap precision도 약 62%라 해당 검사는 기본값에서 꺼져 있습니다.

합의점 vs 논쟁점

논쟁점

trigger-overlap을 기본 검사로 켤 수 있는지는 아직 불확실합니다. 현재 TF-IDF cosine 방식의 precision이 약 62%라 오탐을 줄이기 전에는 자동 차단에 부적합합니다. 작성자는 같은 trigger를 두고 경쟁하는 Skill을 구분할 더 나은 유사도 지표가 있는지 피드백을 요청했습니다.
정적 비용 측정에서 어떤 토크나이저를 기준으로 삼을지는 한계가 남습니다. Claude 전용 오프라인 토크나이저가 없어 `cl100k_base` 수치를 사용하지만, 이를 실제 Claude 비용으로 간주하면 fabrication이 됩니다. 도구는 이 차이를 모든 count에 method와 proxy 표기로 붙여 제한을 명시합니다.

실용적 조언

Agent context 비용을 계산할 때 저장소 안의 모든 지침 파일을 합치지 말고, 동일한 harness와 작업 디렉터리에서 한 세션에 실제로 함께 로드되는 파일만 묶어야 합니다. 이 범위를 잘못 잡으면 123,567 tokens처럼 실제 상시 비용보다 큰 수치가 나올 수 있습니다. skillassay는 이 로딩 관계를 자동으로 찾는 방식으로 측정 대상을 좁힙니다.
토큰 수를 보고할 때는 사용한 tokenizer와 측정 방법을 함께 기록해야 합니다. Claude 전용 tokenizer가 없는 환경에서 `cl100k_base`로 얻은 값은 proxy로 표시해야 하며, 정확한 Claude 토큰 수라고 부르면 안 됩니다. 이 도구는 코드 전반에 계산 방법을 부착해 수치의 성격을 구분합니다.
trigger-overlap 결과는 현재 기본 차단 규칙으로 사용하지 않는 편이 안전합니다. TF-IDF cosine과 보정 threshold의 precision이 약 62%이므로 opt-in 검사로 실행하고, 실제 라벨 데이터로 threshold를 다시 보정해야 합니다. stale-path와 영어 전용 trigger clause 감지 역시 각각 측정 범위와 언어 제약을 함께 고려해야 합니다.

섹션별 상세

skillassay는 사용자가 입력하기 전 Agent가 자동으로 불러오는 지침과 Skill의 컨텍스트 비용을 측정하는 Apache-2.0 라이선스 정적 검사 도구입니다. CLAUDE.md, AGENTS.md, GEMINI.md, `.claude/skills/**`, `.agents/skills/**`, `.mcp.json`을 찾은 뒤 같은 harness와 작업 디렉터리에서 실제로 함께 로드되는 파일만 합산합니다. 모든 파일을 무차별적으로 더하면 123,567 tokens가 나오지만 실제 상시 비용은 21,086 tokens였다는 사례가 있어, 작성자는 로딩 범위가 측정의 핵심이라고 봅니다.

GitHub 저장소 `rakib-nyc/skillassay`가 AI coding-agent context용 정적 analyzer이자 Agent Skill로 소개된 화면입니다. — Screenshot화면에는 저장소 이름과 함께 Agent가 실행할 수 있는 Agent Skill이라는 설명이 표시되어 있습니다. 본문에서 제시한 도구의 목적과 일치하며, 저장소가 공개 GitHub 프로젝트로 배포되고 있음을 뒷받침합니다.

Agent Skills 사양 검사는 Skill의 이름 길이와 표기, 부모 디렉터리와의 이름 일치, description 길이를 기준으로 수행합니다. 11개 공개 저장소의 고정 커밋에서 가져온 `SKILL.md` 1,029개 중 1,022개가 파싱됐고, 37개에서 사양 위반이 확인됐습니다. 위반은 부모 디렉터리와 맞지 않는 `name:` 26개, 잘못된 문자나 대소문자 8개, description 제한 초과 3개로 나뉘며, 58개에는 감지 가능한 trigger clause가 없었습니다.

측정값은 Claude 전용 오프라인 토크나이저가 없다는 한계를 반영해 `cl100k_base`와 `js-tiktoken`으로 계산되고, 코드 전체에서 계산 방식과 함께 proxy로 표시됩니다. 기본 검사 결과 100개를 전수 수작업으로 대조한 false-positive rate는 9.0%였고, 종료 코드에 영향을 주는 규칙만 보면 6.1%였습니다. 따라서 토큰 수를 Claude의 정확한 실제 비용으로 포장하지 않고 사용한 토크나이저를 함께 기록하는 방식이 채택됐습니다.

trigger-overlap 검사는 정규화한 description text에 TF-IDF cosine similarity를 적용하고 보정된 threshold를 사용합니다. 보정된 기준의 precision은 약 62%라서 기본값에서 꺼져 있으며, stale-path 검사는 측정된 precision이 3/6이라 `info` 수준으로만 제공됩니다. trigger clause 감지는 영어만 지원하고, threshold는 임의의 수치가 아니라 라벨이 붙은 쌍 데이터와 calibration script로 산출됩니다.

작성자는 대부분의 저장소에서 비용 절감 효과가 작다는 점을 제한 사항으로 남겼습니다. 실제 저장소 33개의 중앙값 절감량은 0 tokens였고 18개는 삭제할 항목이 없었으며, 도구의 실용성이 application repo보다 Skill 작성자에게 더 크다고 판단했습니다. 또한 사양 적합성은 conforming client가 Skill을 거부할 권리를 뜻할 뿐 특정 client가 모든 조항을 실제로 강제한다는 증거는 아니라고 선을 그었습니다.

용어 해설

컨텍스트 윈도(Context Window): — AI agent가 작업 중 참고할 수 있는 입력 토큰 공간입니다. skillassay는 사용자가 입력하기 전 자동으로 로드되는 지침 파일과 Skill의 토큰 비용을 이 공간의 상시 비용으로 계산합니다.
하네스·작업 디렉터리 범위(Harness Scope): — 같은 Agent harness와 작업 디렉터리에서 실제로 함께 로드되는 파일만 하나의 세션 비용으로 묶는 기준입니다. 디스크 전체의 지침 파일을 단순 합산하는 오류를 줄이는 핵심 범위 설정입니다.
cl100k_base 토크나이저(cl100k_base): — OpenAI 계열 모델에서 널리 쓰이는 토큰화 기준 중 하나입니다. 이 도구는 Claude 전용 오프라인 토크나이저가 없기 때문에 cl100k_base로 센 값을 정확한 Claude 토큰 수가 아닌 proxy로 표시합니다.
TF-IDF 코사인 유사도(TF-IDF cosine): — 문서에서 단어의 중요도를 TF-IDF로 표현한 뒤 두 벡터의 방향 유사도를 계산하는 방법입니다. skillassay는 Skill description을 정규화한 뒤 이 값으로 동일한 trigger를 겨냥하는 Skill 간 겹침을 추정합니다.

언급된 도구

skillassay추천링크

Agent가 자동으로 불러오는 지침과 Agent Skills의 컨텍스트 비용 및 사양 적합성을 검사합니다.

js-tiktoken중립

`cl100k_base` 기준으로 지침 파일과 Skill의 토큰 수를 계산합니다.

TypeScript/Node중립

skillassay를 구현하고 실행하는 개발 환경입니다.

언급된 리소스

GitHubrakib-nyc/skillassay