Skill Checkup
모든 SKILL.md를 진단하고 개선합니다. 매뉴얼이 아닌 나침반 — 표준은 references/에 있습니다.
역할 — 전달 감사자. 스킬은 텍스트가 아닙니다. 각 규칙이 적용되는 순간 모델의 주의에 도달할 확률입니다. 모든 결과는 네 가지 관점을 통해 해당 수량을 측정합니다: harness (무엇이 언제 주입되는가: 설명은 매 턴, 본문은 트리거 시, 참조는 Read를 통해서만), model (편향 절약, 컨텍스트 소멸, 묵시적 건너뛰기), hard code (스크립트는 산문이 할 수 없는 것을 강제함), structure (라우팅, 로스터, 증명).
진단 흐름 (각 단계는 출력해야 함)
묵시적 단계는 건너뜁니다(Seleznov, 2026) — 단계당 하나의 확인 라인을 출력하세요. 자체 검토 플래그: 이 세션이 이미 대상 SKILL.md를 편집/작성했다면, 모든 skill-checkup 출력 라인 앞에
[self-review]를 붙이고, 새로운 하위 에이전트의 블라인드 재감사가 작업 완료 전에 반드시 실행되어야 합니다 — 명시적 파일 경로와 예상 결과 없이 생성하고(절차 + 다중 대상 확장:runtime-contract.md§4), 다음을 출력하세요:[skill-checkup] self-review re-check: <agent> → <verdict summary>실행할 수 없으면 명시적으로 말하고 작업을 미검증으로 표시하세요 — 침묵은 선택 사항이 아닙니다.
단계 1: 대상 읽기, 세 가지 검사기 실행
대상 SKILL.md를 전체 읽고, python3 <this-skill-dir>/scripts/… (경로를 인용하세요 — 공백이 흔합니다)를 통해 세 가지 검사기를 실행하세요: check_listing_budget.py "<project_root>" --target "<skill_name>", check_routes.py "<skill_dir>", check_script_safety.py "<skill_dir>". 세 가지 모두 매 감사마다 실행됩니다; compass-cap/dangling/orphan 적중 = P1. 다섯 줄을 출력하세요:
[skill-checkup] Auditing: <path> body=<N> lines description=<M> chars
[skill-checkup] Budget: <K> skills installed, descriptions <T> chars vs ≈<B> → <fits | OVERFLOW ×N.N>
[skill-checkup] Overlap: <clean | N pair(s), M with target>
[skill-checkup] Routes: <PASS | N issue(s): compass-over/dangling/orphan>
[skill-checkup] Safety: <clean | N hit(s): <classes>>
Budget 종료 코드 2 = 사용 불가 → 폴백 행. 계층화: 오버플로우 및 비대상 중복 = NOTICE만; 대상 중복 = P2 (description-templates.md §distinctness); 안전성 적중 = CRIT일 때 P0, 그 외 P1, 합법성 대기 (hard-code-vs-llm-judgment.md); 안전성 깨끗함 → 증명 행만, 보고 행은 절대 안 됨. 인구 통지(population notice)를 위해 감사 중인 스킬을 편집하지 마세요; 안전성 적중을 자동으로 삭제하지 마세요 (슬리밍 = 사용자 실행 전역 패스).
단계 2: 차원 로스터 작성 후, 한 번에 하나씩 읽기
python3 <this-skill-dir>/scripts/index.py "<skill_dir>" 실행 — 대상의 차원 로스터(FORCED / DEFAULT / SKIP + 이유)와 MODE= 라인을 측정하고 출력합니다. 스크립트가 발사 결정의 권위자입니다; references/index.md는 사람이 읽을 수 있는 미러입니다 — 산문에서 발사를 다시 판단하지 마세요.
MODE=inline → 반복문으로 로스터를 파일당 한 번씩 처리: 읽기 → 해당 차원에 대해서만 대상 판단 → 증명 출력 → 다음 파일. DEFAULT 스킵은 로스터의 출력된 스킵 조건을 인용해야 함. MODE=fanout → runtime-contract.md §4.
[skill-checkup] <dimension>: <N> findings
단계 2.5: 드라이런 워크스루 (ordered-steps=True이면 긍정 워크; 항상 부정 워크)
references/effect-dry-run.md에 따라, 설명이 약속하는 각 작업 형태(write / revise / check, 1–3개; 편집 스킬의 경우 작은 범위의 revise 프롬프트 필수)당 하나의 일반적인 프롬프트를 가져옵니다. 각각을 본문 단계를 통해 워크합니다: 입력/명령/출력 연결 및 해당 세분성에서 어떤 하드 게이트가 발사되는지 확인.
깨진 링크 / 모호함 / 일반적인 형태를 트리거하지 않는 게이트 → P0, 단계 3의 Code 레이어로 이동.
프롬프트당 한 줄 출력:
[skill-checkup] Dry-run "<prompt>" (shape: <write|revise|check>) broken links=<N> gates fired=<M>/<total>
순서화된 프로세스가 전혀 없음(순수 규칙 / 참조 스킬) → 출력:
[skill-checkup] Dry-run: positive walk skipped (no workflow)
항상(워크플로우 여부와 관계없이): 설명만으로 1–2개의 트리거되지 않아야 할 프롬프트를 판단합니다. effect-dry-run.md §negative 참조. 포착됨 → P2 [over-trigger]. 출력:
[skill-checkup] Dry-run negative: <K> prompts, false-fire=<J>
단계 2.6: 라이브 주입 확인 (대상이 이 세션의 범위에 있을 때)
대상이 이 세션의 사용 가능한 스킬 목록에 설명과 함께(이름만이 아닌) 나타납니까? 3가지 경우 + 인구 통지 규칙 → references/live-injection-check.md. 한 줄 출력:
[skill-checkup] Live-injection: <injected | DROPPED (name-only) | skipped (<reason>)>
단계 3: 진단 보고서 출력
references/output-format.md에 따라 제시 — lesstoken 스타일의 계층형 보고서, 사용자 응답 언어로: 판결 → 품질 점수 → Code 레이어 (P0→P3, file:line 증거) → Decision 레이어 분할 ✅ 지금 고쳐도 안전함 vs 🤔 결정이 필요함 → 마무리 질문.
레이어를 채우는 내용:
- 각 결과: 안정적인 ID (
P0-1…), 특정 라인/필드, 위험 🟢/🟡/🔴, P0→P3 순 (references/priority-tiers.md); 동일 위반이 N곳에 있으면 N개의 결과; 두 차원에서 동일 결함은 계층화 전에 하나로 중복 제거. - 해당되는 경우 실패 모드 이름 명명 —
predictability-glossary.md레이블:[no-op]/[sediment]/[premature-completion]/[weak-leading-word]/[duplication]/[sprawl]/[over-trigger]/[no-floor]/[gate-gap]/[missing-license]. 접두사 = 어떤 종류인지, P-계층 = 얼마나 나쁜지. - 각 🤔 항목은 메커니즘(현재 동작)과 결과(다음 LLM이 잘못하는 것)를 분리한 후, 옵션 + 권장 사항.
단계 4: 사용자 확인 후 편집 적용
절대 확인 없이 편집하지 마세요 — 사용자의 "고쳐줘"를 기다리세요.
행동 전: 크기 게이트 + 삭제 전 검사; 이후 루프 종료 — 절차는 references/apply-safety.md에 있습니다.
수정 후 한 줄 출력:
[skill-checkup] Applied <N> fixes to <path> body: <old>→<new> lines (<+X%>)
하드 규칙 빠른 참조
정량화된 하드 규칙(위반 = 오류) → references/hard-rules.md, 모든 감사 시 참조.
예외 폴백
경로 누락, YAML 파싱 실패, 또는 scripts/ 아래 번들 스크립트 누락 또는 종료 코드 2 발생 시 — references/exception-fallback.md에 따라 처리(권위 있는 스크립트 목록은 거기에 있음); 먼저 알리고, 절대 조용히 건너뛰지 마세요.
언어
기본값 영어; 부당한 비영어는 ⚠️ 플래그; 정책 + 2가지 예외 → references/language-policy.md.
범위 외
내용의 도메인 정확성(논리 버그, 형식이 아님 — 런타임 동작은 범위 내 → runtime-contract.md); 프로젝트 규칙(→ CLAUDE.md); 일회성 수정 스크립트.
존재 이유
LLM은 매뉴얼을 작성합니다; 기계적 대 판단 분할: references/rationale.md.