skill-insp: 다른 스킬을 평가하는 스킬

Claude Code 스킬을 한동안 만들어 오셨다면, 아마 한 가지 패턴을 발견하셨을 것입니다. 모든 스킬 작성자는 처음 몇 번은 똑같은 실수를 반복한다는 점입니다. 트리거(Trigger)를 유도하지 못하는 모호한 설명, 파일이 누락되었을 때 무엇을 해야 할지 명시하지 않은 워크플로(Workflow), glob 제한 없이 Bash를 요청하는 allowed-tools, 그리고 스킬이 실제로 작동하는지 알 수 없게 만드는 평가(Eval) 시나리오의 부재 등이 그것입니다.

저는 이러한 실수들을 자동으로 잡아내기 위해 skill-insp를 만들었습니다. 이것은 다른 스킬을 검사하고, 8가지 차원에 걸쳐 점수를 매기며, 무엇을 수정해야 하는지 알려주는 스킬입니다.

출처: github.com/conanttu/skills

기능

SKILL.md가 포함된 폴더를 skill-insp로 지정하면 다음과 같은 결과물을 제공합니다:

1. 8가지 가중치 차원(구조(Structure), 트리거링(Triggering), 사용성(Usability), 완전성(Completeness), 점진적 공개(Progressive Disclosure), 테스트 가능성(Testability), 유지보수성(Maintainability), 안전 및 신뢰(Safety & Trust))에 따른 0–100점 점수
2. 파일:라인 참조가 포함된 우선순위가 지정된 발견 사항 목록(높음 / 중간 / 낮음)
3. 브라우저에서 열 수 있는 HTML 보고서
4. 자동 백업과 SHA-256 해시 검증을 통한 고우선순위 수정 사항 적용(Apply) 및 되돌리기(Revert) 기능
5. 스킬 자체의 로직을 검증하기 위해 피스처(Fixture) 스킬을 대상으로 서브 에이전트(Sub-agents)를 생성하는 기능적 평가 실행기(Functional eval runner)

✨ skill-insp ✨

Overall: my-skill scores 66/100 — risk low, readiness usable-with-improvements.
...

채점 기준 (Scoring Rubric)

100점의 점수는 실제로 실무에서 스킬을 망가뜨리는 요소들에 가중치를 두어 배정됩니다:

차원 (Dimension)	최대 점수 (Max)	중요성 (Why it matters)
구조 (Structure)	10	프론트매터 (Frontmatter)가 파싱되며, 폴더 레이아웃이 논리적임
...

**안전 및 신뢰 (Safety & Trust)**는 패턴 매칭 (pattern-matching) 도구들이 한계를 드러내는 차원이며, 따라서 skill-insp는 이 부분에서 의미론적 분석 (semantic analysis)을 수행합니다. 이 도구는 문서와 실행 가능한 코드 (executable code)를 구분합니다. 예를 들어, 안전 체크리스트에서 "rm -rf 사용 여부를 확인하십시오"라고 명시된 SKILL.md는 파괴적인 작업이 아닙니다. 반면, 실제로 rm -rf "$TEMP_DIR"를 실행하는 scripts/cleanup.sh는 파괴적인 작업이며, 파일:줄 (file:line) 참조와 함께 플래그(flag)가 지정됩니다.

구축 방식 (How It's Built)

이 스킬은 "모델이 분석기이다 (model is the analyzer)" 패턴을 따릅니다. YAML을 파싱하거나 글자 수를 세는 Python 또는 Node 스크립트는 존재하지 않습니다. 대신 다음과 같은 구조를 가집니다:

skill-insp/
├── SKILL.md                       # 워크플로우 (Workflow) + 4가지 모드 (default, detailed, apply, revert) + 평가 실행 (Run Evals)
├── README.md
...

결정론적 (deterministic)이어야 하는 부분은 두 개의 결정론적 스크립트가 처리합니다:

• render-html.js: JSON 분석 결과를 독립형 HTML 보고서로 변환합니다. 템플릿은 테마 설정을 위한 CSS 사용자 정의 속성 (CSS custom properties), 원뿔형 그라데이션 (conic-gradient) 점수 링, 그리고 자동으로 숨겨지는 평가 결과 섹션을 사용합니다.
• run-evals.js: cache/_fixtures/<id>/에 피스처 (fixture) 스킬을 생성하고, 하위 에이전트 (sub-agents)가 <this-skill> 참조를 해석할 수 있도록 skill-insp 자체의 스냅샷을 _skill_home/으로 복사하며, 독립형 하위 에이전트 프롬프트 (sub-agent prompt)를 출력합니다.

그 외의 모든 작업 — 파일 읽기, YAML 파싱, 채점 기준 (rubric) 평가, 문서와 코드의 구분 — 은 모델에 의해 수행됩니다. 이는 파서 (parser)보다 느리게 느껴질 수 있지만, 사실 이를 올바르게 수행할 수 있는 유일한 방법입니다. 정규 표현식 (regex)은 "플래그를 지정할 예시"라고 라벨링된 마크다운 코드 펜스 (markdown code fence) 내부의 rm -rf가 실행 가능한 스크립트 내부의 rm -rf와 같지 않다는 것을 알지 못합니다.

실전에서의 점진적 공개 (Progressive Disclosure in Practice)

이전 버전의 skill-insp는 전체 채점 기준을 인라인 (inline)으로 포함한 300줄짜리 SKILL.md를 가지고 있었습니다. 이는 컨텍스트 예산 (context budget)에 큰 부담을 주었고 스킬을 편집하기 어렵게 만들었습니다. 현재의 레이아웃은 세부 사항을 참조 (references)로 밀어냅니다:

• SKILL.md는 워크플로우 (workflow)와 모드 진입점 (mode entry points)을 담고 있습니다. 약 150줄 분량입니다.
• rubric.md는 채점 차원 (scoring dimensions), 우선순위 레벨 (priority levels), 압축 규칙 (compactness rules), 그리고 안전 가이드라인 (safety guidance)을 담고 있습니다. 스킬이 실제로 무언가를 채점할 때만 로드됩니다.
• output-format.md는 JSON 스키마 (JSON schema)를 담고 있습니다. analysis.json을 작성할 때만 로드됩니다.

결과적으로: SKILL.md는 한 번에 읽기에 충분할 만큼 작으며, 모델은 채점을 하기 직전에만 루브릭 (rubric)을 로드합니다.

Eval Runner (평가 실행기)

이 부분은 가장 많은 반복 (iteration)이 필요했던 부분입니다. 아이디어는 간단합니다: skill-insp는 evals/evals.json에 8개의 평가 시나리오 (eval scenarios)를 포함하며, 각 시나리오는 사용자 프롬프트 (user prompt), 생성할 피스처 파일 (fixture files), 그리고 검증할 기대 사항 (expectations)을 설명합니다. 이를 실행하려면:

node scripts/run-evals.js <skill-path> list
node scripts/run-evals.js <skill-path> setup <id>

setup은 피스처 디렉토리 (fixture directory)를 생성하고, 피스처 파일들을 작성하며, skill-insp 자체 리소스를 _skill_home/으로 복사하고, sub_agent_prompt를 포함하는 JSON 페이로드 (JSON payload)를 출력합니다. 상위 에이전트 (parent agent)는 해당 JSON을 읽고, 해당 프롬프트로 서브 에이전트 (sub-agent)를 생성하며, 서브 에이전트가 완료된 후 각 기대 사항을 확인합니다:

• 파일 기대 사항 (File expectations) ("analysis.json이 작성됨") → 피스처 디렉토리에 대해 find 실행.
• 내용 기대 사항 (Content expectations) ("높은 우선순위의 결과가 보고됨") → 출력 파일들을 읽음.
• 행동 기대 사항 (Behavioral expectations) ("모델이 에러를 보고하고 중단함") → 서브 에이전트의 텍스트 출력으로부터 판단.

샌드박스 주의사항 (The Sandbox Gotcha)

첫 번째 버전에서는 피스처가 os.tmpdir() 아래에 생성되었습니다. 제가 수동으로 실행할 때는 잘 작동했지만, 하네스 (harness)에 의해 생성된 서브 에이전트들은 프로젝트 루트 (project root)로 샌드박스 (sandboxed) 처리되어 있었습니다. 이로 인해 /var/folders/.../T/eval-skill-insp-*에 대한 모든 Read 및 Bash 호출에서

해결 방법은 단 한 줄의 변경이었습니다. fixtures를 프로젝트 내부의 cache/_fixtures/<id>/로 이동하는 것이었습니다. 이제 하위 에이전트 (sub-agents)는 프로젝트의 파일 시스템 권한 (filesystem permissions)을 상속받으며, 캐시 디렉토리는 .gitignore에 등록되어 커밋 (commits)을 오염시키지 않습니다. 변경 후, 8개의 모든 평가 (evals)가 깔끔하게 실행되었습니다.

기억할 만한 교훈: 하위 에이전트 (sub-agents)를 생성할 계획이라면, 그들의 작업 디렉토리 (working directory)를 부모의 샌드박스 (sandbox) 내부에 유지하세요. 프로젝트 트리 외부의 임시 디렉토리 (Temp directories)는 깔끔한 선택처럼 보이지만, 더 엄격한 권한 정책 (permission policies) 하에서는 작동하지 않습니다.

적용 및 되돌리기 (Apply and Revert)

skill-insp에서 "권장 사항 적용 (apply recommendations)"이라고 말하면 다음과 같이 동작합니다:

1. 대상 파일들을 다시 읽습니다 (점검 이후 상태가 변경되었을 수 있습니다).
2. 수정하려는 각 파일을 <cache_dir>/last-apply/로 복사합니다.
3. 수정 전후의 SHA-256 해시 (hashes)를 계산하여 manifest.json에 기록합니다.
4. 최소한의 편집 (minimal edits)을 수행합니다.
5. 분석을 다시 실행하여 새로운 점수를 확인할 수 있게 합니다.

매니페스트 (manifest)는 다음과 같은 형태입니다:

{
  "applied_at": "2026-05-25T23:16:00Z",
  "recommendations_applied": [
...

되돌리기 (Revert) 작업은 이의 역과정입니다: 매니페스트를 읽고, 현재 파일의 해시가 기록된 after_sha256과 일치하는지 확인합니다 (적용 이후에 이루어진 편집을 날려버리지 않기 위함입니다). 그 다음 백업에서 복구합니다. 만약 해시가 일치하지 않으면, skill-insp는 덮어쓰는 대신 충돌 (conflict)을 보고합니다. 이 과정에서 git reset --hard나 git checkout --를 사용하지 않습니다. 그러한 명령들은 복구 경로에 포함되어서는 안 되는, 영향 범위 (blast-radius)가 너무 큰 작업이기 때문입니다.

자기 점검 (Self-Inspection)

skill-insp는 그 자체로 하나의 스킬 (skill)이기 때문에, 스스로를 점수 매길 수 있습니다:

You: 评估 .claude/skills/skill-insp
Claude: ✨ skill-insp ✨
        Overall: skill-insp scores 94/100 — risk low, readiness ready.
...

처음 이 작업을 수행했을 때, 보고서는 제가 이미 절반 정도 눈치챘지만 굳이 수정하지 않았던 부분들을 지적했습니다. 캐시 슬러그(cache slug) 유도 규칙은 예시 없이 너무 복잡했고, 설명(description)에는 트리거로서 "fix"나 "improve"라는 단어가 언급되지 않았으며, 문서화된 Node.js 버전 하한선도 없었습니다. 이 모든 것들은 Low/Medium 권장 사항(recommendations)이 되었고, 이를 적용하자 점수가 올라갔습니다.

이것은 제가 스킬 작성(skill authoring)을 위해 찾아낸 가장 유용한 피드백 루프입니다. 스킬을 작성하고, skill-insp를 실행하고, 우선순위가 높은 권장 사항을 적용한 뒤, 이를 반복하는 것입니다. 그런 다음 평가 스위트(eval suite)를 통해 워크플로우가 여전히 엔드 투 엔드(end-to-end)로 작동하는지 검증합니다.

사용하지 말아야 할 때

skill-insp의 설명에는 **"일반적인 코드 리뷰용이 아님"**이라고 명시되어 있습니다. 임의의 Python이나 TypeScript를 위한 린터(linter)가 아닙니다. 이 도구는 Claude Code 스킬의 구조와 관례에 특화되어 튜닝되었습니다:

• YAML 프론트매터(frontmatter)가 포함된 SKILL.md를 기대합니다.
• 스킬 전용 루브릭(rubric)을 기준으로 점수를 매깁니다.
• 안전성 분석(safety analysis)이 스킬에 맞춰 조정되어 있습니다 (권한 범위 지정(permission scoping), 스크립트 내 미공개 네트워크 액세스, 지침 내 프롬프트 인젝션(prompt injection)).

만약 일반적인 소스 트리(source tree)를 대상으로 지정하면, SKILL.md가 없기 때문에 점수를 매기기를 거부할 것입니다. 이는 버그가 아니라 의도된 동작입니다.

사용해 보기

리포지토리(repo)를 클론(clone)하고 폴더를 Claude Code 스킬 디렉토리에 넣으세요:

git clone https://github.com/conanttu/skills.git
ln -s "$(pwd)/skills/skill-insp" ~/.claude/skills/skill-insp

그 다음, 어떤 Claude Code 세션에서든 다음과 같이 입력합니다:

inspect the skill at ./my-skill

또는 중국어로:

评估 ./my-skill

트리거 문구(trigger phrases)가 설명에 나열되어 있으므로 스킬이 자동으로 호출됩니다. 검사(inspection) 후에는 다음 번호가 매겨진 프롬프트를 따르세요:

1. detailed mode: 근거를 확장하여 상세히 보기
2. apply recommendations: 우선순위가 높은 발견 사항을 자동 수정하기
3. run evals: 평가 시나리오로 스킬 검증하기
4. revert: 마지막 적용 사항 취소하기

다음 단계

현재 버전은 1.0.0입니다. 제가 추가하고 싶은 몇 가지 사항은 다음과 같습니다:

• HTML 리포트 내 Diff view (차이점 보기): apply가 실제로 무엇을 변경했는지 보여줍니다.
• 교차 스킬 일관성 검사 (Cross-skill consistency checks): 여러 개의 스킬을 배포하는 리포지토리(repos)를 위한 기능입니다.
• 선택적 스키마 검증 (Optional schema validation): evals.json 및 analysis.json에 대한 검증 기능입니다.

만약 스킬을 정기적으로 빌드하신다면, 직접 사용해 보시고 어떤 부분이 제대로 작동하지 않는지(falls over) 알려주세요. evals/evals.json에 있는 평가 시나리오(eval scenarios)는 기능을 확장하고 싶을 때 시작하기 좋은 지점입니다. 새로운 시나리오를 추가하는 것은 프롬프트(prompt), 피스처 파일(fixture files), 그리고 기대 결과(expectations)가 포함된 JSON 항목을 추가하는 것만으로 충분합니다.

출처: github.com/conanttu/skills