Community라이팅 & 에디팅github.com

Zane456/skill-checkup

클로드 코드 스킬에 대한 건강 진단 도구입니다. skill-checkup은 SKILL.md가 신뢰성 있게 트리거되지 않는 이유를 진단하고, 워크플로우의 드라이런을 수행하며, 패키지를 재구성합니다. 4개의 결정론적 스크립트와 런타임 의존성이 없습니다.

skill-checkup란 무엇인가요?

skill-checkup은 AI 어시스턴트(특히 Claude Code)의 스킬 파일(SKILL.md)이 의도한 대로 동작하는지 체계적으로 진단하고 개선하는 감사(audit) 도구입니다. 이 스킬은 스킬의 텍스트 자체보다는 각 규칙이 적절한 순간에 모델의 주의를 받을 확률에 초점을 맞춥니다. harness(주입 방식), model(편향 및 컨텍스트 소멸), hard code(스크립트 기반 강제), structure(라우팅 및 구조)의 네 가지 관점을 통해 분석하며, 4개의 Python 스크립트로 검증을 자동화하여 별도의 런타임 의존성 없이 작동합니다. 진단 프로세스는 SKILL.md 읽기, 3가지 검사기 실행(리스팅 예산, 경로, 스크립트 안전성), 차원 로스터 분석, 드라이런 워크스루, 라이브 주입 확인, 계층형 보고서 출력, 사용자 확인 후 수정 적용의 단계로 구성됩니다. 이 도구는 AI 에이전트 개발자와 고급 사용자에게 특히 유용하며, 스킬의 예측 가능성과 신뢰성을 확보하는 데 핵심적인 역할을 합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add Zane456/skill-checkup

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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.

관련 스킬