skill-audit은(는) 무엇을 하나요?
SKILL.md의 V3 표준(LLM 친화적)에 대한 정적 감사입니다. 10가지 QA 검사를 수행하여 기계적, 의미적 문제를 탐지하고 우선순위가 매겨진 보고서를 제공합니다. 특히 Claude pre-4.5에서 마이그레이션한 사용자에게 유용합니다. 예전 스킬은 종종 작성자 컨텍스트에서만 작동하고 외부 에이전트에서는 작동하지 않습니다.
사용 시점
다음과 같은 경우에 사용합니다:
- 사용자가 "트리거되지 않거나" "제대로 실행되지 않는" 스킬을 가지고 있을 때
- Claude 3.x / 4.0에서 4.6+로 마이그레이션했는데 동작이 깨졌을 때
- 스킬을 GPT-5, Gemini 또는 Claude가 아닌 다른 LLM에서 실행하고 싶을 때
- 대량으로 스킬을 생성 중일 때 (예: 학생, 팀, 커뮤니티 대상)
- 컬렉션에서 어떤 스킬을 먼저 수정할지 우선순위를 정하고 싶을 때
메시지 예시:
- "skills/my-skill/SKILL.md에 skill-audit 실행해줘"
- "내 스킬이 GPT에서 트리거되지 않아"
- "이 스킬 폴더를 감사해줘"
- "skill-audit ./skills"
- "왜 이 스킬은 Claude에서는 작동하는데 Gemini에서는 안 될까?"
사용하지 말아야 할 시점
다음 경우에는 사용하지 않습니다:
- 사용자가 스킬을 처음부터 생성하려는 경우 →
criar-skill또는skill-creator사용 - 사용자가 감사된 스킬을 실행하려는 경우 → 스킬을 직접 실행
- 사용자가 보안 감사(OWASP, 프로덕션 시크릿)를 원하는 경우 → 다른 도구 사용
- 대상 파일이
SKILL.md가 아닌 경우 (예: Python 스크립트, README) → 일반 리팩토링
입력
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
| path | string | ✅ | SKILL.md 파일의 경로 또는 SKILL.md가 포함된 하위 폴더를 포함한 디렉토리 (재귀적) |
| format | string | ❌ | markdown (기본값) 또는 json — 보고서 형식 |
출력
| 필드 | 유형 | 설명 |
|---|---|---|
| score | int 0-10 | 스킬이 통과한 10가지 QA 검사 개수 |
| issues | array | 우선순위가 매겨진 문제 목록 (예: desc_no_triggers, examples_too_few) |
| by_category | object | 스킬 카테고리별 평균 점수 및 통과율 |
| report | markdown | 순위 및 스킬별 상세 정보가 포함된 전체 보고서 |
전달 형식: ./audit-results.md 마크다운 파일 + 터미널 요약.
워크플로우
- 입력 검증 — 경로가 존재합니까?
.md파일 또는 디렉토리입니까? - SKILL.md 파일 수집
- 경로가
.md파일을 가리키면 → 단일 목록 - 그렇지 않으면 → 디렉토리에서 재귀적으로
**/SKILL.mdglob
- 경로가
- 각 SKILL.md에 대해:
- YAML 프론트매터 파싱 (
---...---) - 본문을 H2 섹션으로 분할 (코드 펜스 ``` 또는 ~~~ 내부의 H2는 무시)
- 10가지 QA 검사 실행
- 점수 + 이슈 + 카운트 기록
- YAML 프론트매터 파싱 (
- 결과 집계 — 평균 점수, 분포, 가장 흔한 이슈
./audit-results.md에 마크다운 보고서 생성:- 전체 요약
- 점수 분포
- 빈도별 이슈
- 가장 수정이 필요한 상위 30개 스킬
- 스킬별 상세 정보
- 터미널에 요약 출력 — 총 스킬 수, 평균 점수, 통과(≥7) 비율
10가지 QA 검사
- 이름이 kebab-case이고 폴더명과 일치하는가
- 설명: 50단어 이상, 3인칭, 5개 이상의 트리거 구문, 부정 경계 포함
- 워크플로우의 각 단계는 단일 동작, 명령형, 모호하지 않음
- 2개 이상의 구체적인 예제 (실제 입력 → 실제 출력)
- 엣지 케이스가 3개 이상 포함되었는가
- 출력 형식이 명시적으로 정의되었는가
- 모호한 언어가 전혀 없는가 (금지 단어 목록은
references/qa-checklist.md참조) ## When NOT to Use섹션에 부정 경계가 있는가- 하드코딩된 자격 증명(시크릿, API 키, 토큰)이 전혀 없는가
evals/evals.json폴더가 존재하고 2개 이상의 테스트 케이스가 있는가
엣지 케이스
- 경로가 존재하지 않는 경우 → exit 1, 메시지 "Path não encontrado: {path}"
- 디렉토리가 비어 있는 경우 (0 SKILL.md) → exit 0, 메시지 "Nenhum SKILL.md encontrado em {path}"
- SKILL.md에 YAML 프론트매터가 없는 경우 → 점수 0, 이슈
missing_frontmatter - YAML이 유효하지 않은 경우 → 점수 0, 이슈
yaml_parse_error evals/폴더는 있지만evals.json이 없는 경우 → 이슈no_evals_folder- SKILL.md가 너무 큰 경우 (>350줄) → 경고
long, 콘텐츠를references/로 이동 권장 - 마크다운 링크에 플레이스홀더 ref (
link,url,path)가 있는 경우 → 무시 (깨진 참조로 계산하지 않음)
예제
예제 1 — 단일 스킬 감사
실제 입력: skill-audit ./my-skill/SKILL.md
실행된 워크플로우:
./my-skill/SKILL.md가 존재하는지 확인- YAML 파싱 —
name: my-skill발견, 설명 32단어 - 본문 분할:
## When to Use있음,## When NOT to Use없음 - 10가지 검사 실행: 설명 짧음(32w<50), 부정 경계 없음, evals 폴더 없음, 예제 1개뿐
- 보고서 생성
실제 출력:
skill-audit: 1 skill analisada
my-skill — 6/10 (232L, 32w desc, 4 triggers, 1 ex, 4 edge, evals ✗)
Issues: desc_too_short(32w), desc_no_negatives, examples_too_few(1), no_evals_folder
Report: ./audit-results.md
예제 2 — 전체 폴더 감사 (엣지: 여러 스킬)
실제 입력: skill-audit ~/my-claude-skills/
실행된 워크플로우:
~/my-claude-skills/가 디렉토리인지 확인- Glob으로 12개의
SKILL.md발견 - 각각에 대해: 파싱 + 검사 + 점수
- 집계: 평균 점수 7.1, 4/12 통과 ≥7
- 우선순위 보고서: 최악 순서
실제 출력:
skill-audit: 12 skills analisadas
Score médio: 7.1/10
Passing (≥7): 4/12 (33%)
Top 3 issues mais comuns:
desc_no_negatives (12, 100%)
no_evals_folder (9, 75%)
desc_too_short (7, 58%)
Worst offenders:
1. legacy-skill-x — 3/10
2. migrated-from-gpt — 4/10
3. old-claude35-skill — 5/10
Report: ./audit-results.md
종속성
- 런타임: Python 3.8+
- 라이브러리: stdlib만 사용 (re, json, pathlib, argparse, collections)
- API: 없음 — 100% 정적/오프라인
- 파일:
templates/SKILL-TEMPLATE.md+references/qa-checklist.md(읽기 전용) - 다른 스킬: 없음 — 독립형 도구
오류 및 복구
| 오류 | 예상 원인 | 해결 방법 |
|---|---|---|
Path não encontrado | 잘못된 경로 또는 오타 | 절대 경로 확인; ls {path}로 확인 |
yaml.YAMLError | 프론트매터 형식 오류 | SKILL.md 열어서 들여쓰기 및 --- 종료 확인 |
UnicodeDecodeError | SKILL.md가 UTF-8이 아닌 인코딩 | 편집기에서 UTF-8로 저장 |
ModuleNotFoundError: yaml | PyYAML 없음 | pip3 install pyyaml |
| 보고서가 생성되지 않음 | ./audit-results.md 쓰기 권한 없음 | 쓰기 권한이 있는 디렉토리에서 실행 |
참고 사항
점수에 관하여: 7/10은 스킬을 외부 LLM에서 "트리거 신뢰 가능"으로 간주하는 최소 허용 점수입니다. 10/10이 이상적입니다. 7 미만은 일반적으로 스킬이 실행 가능한 계약(executable contract)이 아닌 자유 형식의 산문(free prose)으로 작성되었음을 의미하며, 이는 pre-V3 스킬에서 흔한 형식입니다.
evals.json에 관하여: 검사 10은 evals의 내용을 검증하지 않으며, 파일 존재 여부와 최소 구조(prompt 및 expected_output을 포함한 2개 이상의 테스트 케이스)만 확인합니다. evals의 품질은 스킬 작성자의 몫이며, 감사 대상이 아닙니다.
알려진 제한 사항:
- 워크플로우의 의미적 품질(단계가 도메인에 적합한지)을 감사하지 않음
- 스킬을 실행하지 않음 (정적 분석만 수행)
- 트리거 구문 휴리스틱은 기술적으로 밀도가 높은 설명에서 거짓 양성을 생성할 수 있음 — 점수가 경계선(6-7)일 때는 이슈를 수동으로 검토하세요
변경 내역
- v1.0 (2026-04-19): 초기 버전. V3 표준 기반 10가지 QA 검사. Amora 워크스페이스의 119개 스킬 감사에서 파생됨 (평균 점수 5.9 → 10.0).