Claude Code / Agent SDK 기술에 대한 정적 분석. 감사 SKILL.md 10 QA는 기술이 방아쇠를 확인하고 LLM을 통해 올바르게 실행되도록 확인합니다. (Claude, GPT, Gemini).

119개의 생산 기술 감사에서 건축하는 (score는 5.9 → 10.0/10에서 갔습니다).

---

왜 이 존재

Claude pre-4.5에 대한 작성된 기술은 저자의 상황에만 작업합니다. — 그들은 얇은 설명, vague 작업 흐름, 부정적인 경계 없음, evals. 당신이 그들을 실행하려고 할 때 :

• 클로드 4.6+ (완전한 방아쇠 heuristics)
• GPT-5/GPT-4o (다른 방아쇠 semantics)
• Gemini Pro (범죄 언어에 대한 제한)
• 외부 대리인 기구

…이 기술은 조용히 방아쇠에 실패, 또는 잘못된 상황에 트리거.

skill-audit 배송하기 전에 이러한 문제를 진단합니다.

---

설치

파이썬 3.8+가 필요합니다. 의존성 없음 (stdlib 전용).

또는 Claude Code 기술로 설치하십시오:

또는 gh skill를 통해 (당신의 CLI가 그것을 지원할 때):

---

사용법

단일 기술 감사

전체 폴더 감사 (recursive)

JSON 출력 (공구용)

---

산출

markdown 보고서는 다음을 포함합니다:

• 점수 분배
• 주파수에 의해 순위
• 기술 순위 최악 → 최고
• 상세한 per-skill 고장

---

skill-audit

Static analysis for Claude Code / Agent SDK skills. Audits SKILL.md against 10 QA checks to verify a skill will trigger and execute correctly across LLMs (Claude, GPT, Gemini).

Built from an audit of 119 production skills (score went from 5.9 → 10.0/10).

---

Why this exists

Skills written for Claude pre-4.5 often work only in the author’s context — they have thin descriptions, vague workflows, no negative boundaries, no evals. When you try to run them in:

• Claude 4.6+ (tighter trigger heuristics)
• GPT-5 / GPT-4o (different trigger semantics)
• Gemini Pro (stricter about imperative language)
• External agent frameworks

…the skill silently fails to trigger, or triggers in wrong contexts.

skill-audit diagnoses these issues before you ship.

---

Install

Requires Python 3.8+. No dependencies (stdlib only).

git clone https://github.com/okjpg/skill-audit
cd skill-audit

Or install as a Claude Code skill:

cp -r skill-audit ~/.claude/skills/

Or via gh skill (when your CLI supports it):

gh skill install okjpg/skill-audit

---

Usage

Audit a single skill

python3 scripts/audit.py ./my-skill/SKILL.md

Audit a whole folder (recursive)

python3 scripts/audit.py ~/.claude/skills/

JSON output (for tooling)

python3 scripts/audit.py ~/.claude/skills/ --json -o audit.json

---

Output

skill-audit: 12 skills analisadas
  Score médio: 7.1/10
  Passing (≥7): 4/12 (33%)

Report: audit-results.md

The markdown report includes:

• Score distribution
• Issues ranked by frequency
• Skills ranked worst → best
• Detailed per-skill breakdown

---

The 10 QA checks

1. Name in kebab-case matching folder name
2. Description with 50+ words, third person, 5+ trigger phrases, negative boundaries
3. Workflow steps are single, imperative, unambiguous
4. 2+ examples with real input → real output
5. Edge cases covered (3+ conditions with specific action)
6. Output format explicitly defined
7. Zero vague language (handle appropriately, as needed, etc — banned)
8. Negative boundaries in body (## When NOT to Use)
9. Zero hardcoded secrets (API keys, tokens)
10. evals/evals.json with 2+ cases

Full spec: references/qa-checklist.md.

---

Before / After

See examples/before.md (score 3/10) vs examples/after.md (score 10/10) — same skill, same behavior, but one triggers reliably in any LLM.

---

Template

templates/SKILL-TEMPLATE.md — copy-paste skeleton for new V3-compliant skills.

---

When NOT to use skill-audit

• Creating a skill from scratch — use criar-skill instead
• Executing the skill being audited — run it directly
• Security audit (OWASP, production secrets) — this tool is for structural quality, not security posture