From plugin-doctor
마켓플레이스 내 모든 플러그인을 Claude Code 공식 표준에 맞게 점검·수정·개선합니다. 자기 자신(plugin-doctor)도 점검 대상에 포함됩니다. "플러그인 점검", "plugin doctor", "플러그인 검증", "plugin validate", "플러그인 수정", "plugin fix", "마켓플레이스 검증", "플러그인 건강 검진" 등의 요청 시 사용하세요.
How this skill is triggered — by the user, by Claude, or both
Slash command
/plugin-doctor:fixerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
마켓플레이스 내 모든 플러그인을 Claude Code 공식 표준에 맞게 진단하고, 자동 수정 가능한 문제는 즉시 수정한다. 자기 자신(plugin-doctor)도 점검 대상에 포함된다.
마켓플레이스 내 모든 플러그인을 Claude Code 공식 표준에 맞게 진단하고, 자동 수정 가능한 문제는 즉시 수정한다. 자기 자신(plugin-doctor)도 점검 대상에 포함된다.
검증 기준은 references/official-spec.md에 정리되어 있다. Stage 0에서 자동 갱신된다.
$ARGUMENTS 없음 → 전체 마켓플레이스 점검$ARGUMENTS에 플러그인 이름 → 해당 플러그인만 점검--update-spec → Stage 0 강제 실행--update-spec 인자가 있거나 references/official-spec.md의 Last updated 날짜가 30일 이상 경과한 경우에만 실행한다.
references/official-spec.md를 읽어 Last updated 날짜를 확인https://docs.anthropic.com/en/docs/claude-code/pluginshttps://docs.anthropic.com/en/docs/claude-code/skillshttps://docs.anthropic.com/en/docs/claude-code/agentshttps://docs.anthropic.com/en/docs/claude-code/hooksreferences/official-spec.md를 업데이트하고 Last updated 갱신.claude-plugin/marketplace.json을 검증한다.
검증 항목:
name, owner.nameversion 필드 SemVer 형식 검증 (정규식: ^\d+\.\d+\.\d+$)plugins[] 배열 내 각 엔트리:
name 필드 존재 + kebab-case 검증 (정규식: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$)source 필드 존재./로 시작하는지 확인각 플러그인의 .claude-plugin/plugin.json을 검증한다.
검증 항목:
name 필드: 존재 + kebab-caseversion 필드: 존재 (없으면 Warning) + SemVer 형식description 필드: 존재 (없으면 Info)author 필드: 존재 (없으면 Info)각 플러그인의 skills/*/SKILL.md를 검증한다.
검증 항목:
name 필드: kebab-case, 최대 64자description 필드: 존재 여부 (없으면 Warning)
allowed-tools 필드:
mcp__* 패턴model 필드: 유효값 (sonnet, haiku, opus, 또는 전체 모델 ID)effort 필드: 유효값 (low, medium, high, max)context 필드: fork 사용 시 agent 필드도 설정되었는지 확인commands/ 디렉토리가 존재하면 Critical + skills 승격 가이드 제공각 플러그인의 agents/*.md를 검증한다.
검증 항목:
name (kebab-case), descriptiontools 필드: 도구 이름 유효성 (Stage 3과 동일 기준)model 필드: 유효값 (sonnet, haiku, opus, inherit)maxTurns 필드: 양의 정수인지 확인hooks, mcpServers, permissionMode 필드가 있으면 Warning (플러그인 에이전트에서 무시됨)whenToUse 필드: <example> 태그가 포함되어 있는지 확인 (없으면 Info)color 필드: 존재 여부 (없으면 Info)각 플러그인의 hooks/hooks.json 또는 plugin.json 내 hooks 필드를 검증한다.
검증 항목:
SessionStart, InstructionsLoaded, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, TeammateIdle, Stop, StopFailure, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, SessionEndcommand, http, prompt, agent 중 하나인지 확인command 타입 훅:
$CLAUDE_PLUGIN_ROOT 사용이 올바른지 확인timeout 필드: 양의 정수인지 확인각 플러그인의 전체 디렉토리 구조를 검증한다.
검증 항목:
README.md 존재 여부 (없으면 Warning)commands/, agents/, skills/ 등 (Warning)reference/ vs references/ 디렉토리가 동일 스킬 내 공존하면 Warning.claude-plugin/ 디렉토리 내에 plugin.json 외 다른 컴포넌트(commands, agents 등)가 있으면 Critical (잘못된 위치)../ 포함 여부 (경로 탈출 감지)plugin-doctor 자체를 Stage 1~6과 동일한 기준으로 검증한다.
추가 검증:
references/official-spec.md가 존재하고 내용이 비어있지 않은지 확인allowed-tools에 WebFetch, WebSearch가 포함되어 있는지 확인 (Stage 0 실행에 필요)official-spec.md와 일치하는지 확인모든 진단 결과를 종합하여 리포트를 생성한다.
심각도 분류:
자동 수정 가능 항목 (사용자 확인 후 실행):
commands/ 디렉토리 삭제version 필드 추가 (marketplace.json에서 가져옴)allowed-tools 콤마 구분 문자열 → YAML 리스트 변환리포트 출력 형식:
# Plugin Doctor Report
## 스펙 상태
- official-spec.md: [날짜] ([갱신 여부])
## 요약
| 플러그인 | Critical | Warning | Info | 상태 |
|----------|----------|---------|------|------|
| plugin-a | 0 | 1 | 2 | 🟡 |
| plugin-b | 1 | 0 | 0 | 🔴 |
| plugin-doctor (self) | 0 | 0 | 0 | 🟢 |
## 상세 진단
### plugin-a
| 심각도 | Stage | 항목 | 현재 상태 | 권장 조치 |
|--------|-------|------|----------|----------|
| ⚠️ | 6 | README.md | 누락 | 생성 필요 |
| ℹ️ | 4 | agent color | 미설정 | color 필드 추가 권장 |
## 자동 수정 제안
다음 항목을 자동 수정할까요?
- [ ] plugin-a/commands/ 빈 디렉토리 삭제
- [ ] plugin-b/.claude-plugin/plugin.json에 version: "1.0.0" 추가
## 수동 조치 필요
1. [Critical] plugin-b: ...
사용자가 자동 수정을 승인하면 해당 항목을 즉시 수정한다.
Codex 스킬이 사용 가능하고, 승인된 auto-fixable 항목이 3건 이상이면, /codex:rescue에 일부를 병렬 위임하여 수정 속도를 높일 수 있습니다.
codex:codex-rescue 서브에이전트 디스패치 (--write):
/codex:result로 Codex 수정 결과 수집가드레일:
official-spec.md, severity rubric, revalidation score는 fixer가 source of truth입니다. Codex가 기준 완화나 finding 삭제를 하면 해당 수정을 reject합니다. Codex 스킬 미설치 시 또는 auto-fixable 항목이 3건 미만이면 기존 방식으로 직접 수정합니다.
프로토콜 참조:
references/evaluation-protocol.md원칙: Generator-Evaluator 역할 분리 + 회의적 평가 (Anthropic Harness Design 블로그)
자동 수정을 시작하기 전에 완료 기준을 명확히 정의한다:
## Sprint Contract
- 자동 수정 대상: [Critical/Warning 중 자동 수정 가능한 항목 목록]
- CLEAN 기준: Critical + Warning findings = 0
- 수동 조치 항목: [자동 수정 불가능한 항목 → 리포트에만 표시]
- 수정이 아닌 것: findings 삭제, 심각도 하향, 기준 완화
이 사전 합의가 있어야 재검증 시 일관된 기준을 유지할 수 있다.
사용자 승인 후 자동 수정 항목을 실행한다.
수정 후, 별도의 회의적 평가자 역할로 전환하여 재검증한다.
회의적 평가 관점 (자기평가 함정 회피):
2축 다차원 평가:
| 축 | 가중치 | 설명 |
|---|---|---|
| 표준 준수 (Standard Compliance) | 60% | official-spec.md 기준 필드/값 형식 준수 |
| 구조 건전성 (Structural Health) | 40% | 파일 경로, 네이밍, 참조 무결성 |
점수 캘리브레이션:
| 구간 | 표준 준수 | 구조 건전성 |
|---|---|---|
| 9-10 | official-spec 100% 준수 | 경로/네이밍 정상 + README 존재 |
| 7-8 | 경미한 불일치 1-2건 | 경미한 구조 이슈 1건 |
| 5-6 | Warning급 불일치 다수 | 빈 디렉토리, 네이밍 불일치 |
| 3-4 | Critical 존재 | 잘못된 위치에 파일 배치 |
| 1-2 | 필수 필드 다수 누락 | 기본 구조 부재 |
판정: 가중 평균 ≥7 PASS / 4-6 PARTIAL / <4 FAIL
fixer 도메인 안티패턴 (자동 감점):
| 안티패턴 | 축 | 감점 |
|---|---|---|
| commands/ 디렉토리 잔존 | 구조 건전성 | -3 (Critical) |
| plugin.json ↔ marketplace.json version 불일치 | 표준 준수 | -3 (Critical) |
| SKILL.md frontmatter 파싱 실패 | 표준 준수 | -3 (Critical) |
| README.md 누락 | 구조 건전성 | -1 (Warning) |
| 빈 skills/ 또는 agents/ 디렉토리 | 구조 건전성 | -1 (Warning) |
| allowed-tools 콤마 구분 문자열 | 표준 준수 | -1 (Warning) |
재검증 범위: 수정한 항목의 Stage만 재실행한다:
Round 1: Sprint Contract 정의 → Stage 1~8 (진단) → 자동 수정
Round 2: 회의적 재검증 (수정 항목 관련 Stage만)
→ CLEAN → 완료
→ 잔여 findings → 추가 수정 + Round 3
Round 3: 회의적 재검증 (최종)
→ CLEAN → 완료
→ 잔여 → "수동 조치 필요" 리포트 출력 후 종료
종료 조건 (하나라도 충족 시):
산출물 생성 (2라운드 이상 시 필수):
각 라운드 종료 시 .claude/doctor/ 디렉토리에 기록한다:
verify-round-{N}.md: 2축 점수, 안티패턴 탐지 결과, 수정 지침# Verify Round {N} — Plugin Doctor
## 플러그인별 평가
### {plugin-name}
| 축 | 가중치 | 점수 | 근거 |
|----|--------|------|------|
| 표준 준수 | 60% | {N}/10 | {구체적 근거} |
| 구조 건전성 | 40% | {N}/10 | {구체적 근거} |
| **가중 평균** | | **{N.N}** | **{PASS/PARTIAL/FAIL}** |
## 안티패턴 탐지
| 플러그인 | 안티패턴 | 축 | 감점 |
|----------|----------|-----|------|
## 종합 판정: {CLEAN/CONTINUE/CONVERGED/MAX_ROUNDS}
최종 리포트에 루프 이력 추가:
## 검증 루프 이력
| 라운드 | Sprint Contract | findings | 수정 | 잔여 | 가중평균 | 판정 |
|--------|----------------|----------|------|------|---------|------|
| 1 | Critical+Warning=0 | 5 | 4 | 1 | 6.2 | CONTINUE |
| 2 | Critical+Warning=0 | 1 | 1 | 0 | 8.4 | CLEAN |
npx claudepluginhub oozoofrog/oozoofrog-plugins --plugin plugin-doctorAudits Claude Code plugins for structure validation, frontmatter quality, deprecations, feature adoption, security patterns, and documentation. Ensures changelog compatibility and best practices for releases.
Validates and auto-fixes claude-code-plugin marketplace structure: JSON validity, skill dirs, frontmatter, plugin.json consistency, invalid keys, unregistered skills. Local CI equivalent.
Orchestrates Claude Code plugin lifecycle: create new plugins from concepts, improve existing via assessment, research, design, creation, debugging, optimization, verification.