alirezarezvani/claude-skills

skill-doctor

Use when the user wants their agent setup graded from real conversation history, asks which installed skills are actually working, or wants evidence-backed skill edits — scores recent local Claude Code / Codex sessions against efficiency and code-quality ru…

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/alirezarezvani/claude-skills --skill skill-doctor

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

skill-doctor — grade the agent setup from real sessions

Privacy is the contract. Everything runs locally. Transcripts are condensed, secret-redacted, chmod-0600, and never uploaded — the only shareable artifact is the report the user chooses to share.

Run from the repo being graded. Every artifact goes to one fresh scratch dir, never into the repo:

bash
RUN="$(mktemp -d "${TMPDIR:-/tmp}/skill-doctor-XXXXXXXX")"
python scripts/collect_sessions.py --out "$RUN"          # 1 — harvest + redact

1 — Collect. Scans Claude Code project-history JSONL and Codex rollouts, discovers repo skills (.claude/skills, .agents/skills, .codex/skills, plugin layouts), detects skill usage (Skill invocations, slash commands, SKILL.md paths), samples newest-first, and writes redacted transcripts. Read $RUN/inventory.json: if sessions_sampled is 0, tell the user there is nothing recent to score (suggest --days 90 or --repo) and stop. skills_found 0 is fine — the report becomes a case for creating skills.

2 — Score. python scripts/score_aggregator.py --inventory "$RUN/inventory.json" --emit-template > "$RUN/session_scores.json". Read each transcript in $RUN/transcripts/ and judge it against both rubrics — scorers/efficiency.md and scorers/code-quality.md. Fill the template with a label from the rubric's table and a 1–3 sentence reason citing transcript specifics. Never invent numeric scores — the aggregator derives them from labels. Use insufficient_evidence when a transcript shows no judgeable diff. Also write 1–5 top_findings: the most impactful cross-session patterns, concrete and specific.

3 — Draft edits. Follow references/skill_edit_governance.md (the filing bar: would a competent agent with the current instructions still fail this way?). For each suggestion that clears it, write the full improved SKILL.md to $RUN/proposed/<skill>/SKILL.md, produce diff -u <current> <proposed>, and record it in $RUN/suggestions.json citing the sampled session id(s) that motivated it. Zero suggestions is a valid success — say why per finding. Never modify the user's real skill files in this step.

4 — Aggregate (the gate). python scripts/score_aggregator.py --inventory "$RUN/inventory.json" --scores "$RUN/session_scores.json" --suggestions "$RUN/suggestions.json". It validates labels against the rubric tables, refuses scores for unsampled sessions, requires substantive reasons, rejects suggestions that cite no scored session, computes overall = 0.5·efficiency + 0.35·code_quality + 0.15·skill_coverage, and writes report.json. Exit 4 is a stop: fix what it names and re-run; never hand-edit report.json around it.

5 — Render + tell. python scripts/render_report.py --report "$RUN/report.json" → one self-contained report.html (no JS, no CDN, dark-mode + print-to-PDF). Then tell the user the grade and the top findings in text, link file://$RUN/report.html, and ask whether to apply the proposed diffs to their real skills — apply only on an explicit yes, skill by skill.

Hard rules

  1. Never upload transcripts, session files, or any excerpt. Local only.
  2. Labels only, from the rubric tables. The aggregator owns all arithmetic.
  3. Every suggestion traces to a scored session — or it is dropped. Generic best practice is not evidence.
  4. Zero suggestions is a success, not a failure to report around.
  5. Exit 4 from the aggregator is a stop, not an error to swallow or bypass.
  6. Never touch the user's real skill files without an explicit per-skill yes; proposed edits live under $RUN/proposed/.
  7. A proposed skill edit follows write-a-skill discipline — trigger phrase in the description, smallest change that expresses the rule, replace over append.

Scripts

ScriptRoleExit codes
scripts/collect_sessions.pyHarvest Claude Code + Codex sessions, redact secrets, sample, inventory0 · 3 bad input
scripts/score_aggregator.pyValidate labels/reasons/suggestions, compute grade, emit report.json0 · 2 warnings · 3 bad input · 4 validation failure
scripts/render_report.pyreport.json → single self-contained report.html0 · 3 bad input

All support --help, --output json, and --sample (no real history needed).

References and assets

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills