skill-fix — Skill Diagnostic & Repair Tool

Diagnoses and fixes quality issues in Claude Code skill definition files (SKILL.md).

Quick Start

One-Line Install (Agent-Friendly)

git clone https://github.com/napoler/skill-fix.git /tmp/skill-fix-install && \
bash /tmp/skill-fix-install/install.sh && \
rm -rf /tmp/skill-fix-install

For Codex CLI:

git clone https://github.com/napoler/skill-fix.git /tmp/skill-fix-install && \
bash /tmp/skill-fix-install/install.sh --codex && \
rm -rf /tmp/skill-fix-install

Manual Install

git clone https://github.com/napoler/skill-fix.git
cd skill-fix
bash install.sh
bash skills/skill-fix/scripts/verify.sh skills/skill-fix

Trigger Phrases

Say any of these in Claude Code to activate skill-fix:

• "fix skill" / "skill not working" / "diagnose this skill"
• "description too long" / "trim description" / "reduce skill context cost"
• "optimize description" / "context pollution"

Directory Structure

skills/skill-fix/
├── SKILL.md                    # Core definition (306 lines, 39 quality standards)
├── config.json                 # Externalized config (thresholds, model routing, triggers)
├── references/                 # 22 supporting docs (standards, templates, anti-fabrication)
├── scripts/
│   ├── verify.sh               # Integrity checker (bash)
│   ├── validate_skill.ts       # SKILL.md syntax validation
│   ├── detect_drift.ts         # Config drift detection
│   ├── completeness_checker.ts # Multi-file repair completeness check
│   ├── audit_externalized_config.ts # Hardcoded value audit
│   └── param_impact_scanner.ts # Parameter cross-file impact scan
├── evals/
│   └── evals.json              # 5 evaluation scenarios
└── tmp/                        # Diagnostic reports (gitignored)

Scripts

Script	Requires	Purpose
verify.sh	bash	Quick integrity check (frontmatter, references/, Path.cwd())
validate_skill.ts	Node >= 18 + tsx	SKILL.md syntax validation
detect_drift.ts	Node >= 18 + tsx	config.json vs SKILL.md consistency check
completeness_checker.ts	Node >= 18 + tsx	Multi-file repair completeness
audit_externalized_config.ts	Node >= 18 + tsx	Hardcoded value audit
param_impact_scanner.ts	Node >= 18 + tsx	Cross-file parameter impact scan

Run TypeScript scripts with tsx (zero-config, no tsc needed):

npx tsx scripts/detect_drift.ts <skill-path>
npx tsx scripts/param_impact_scanner.ts <skill-path>

Core Principles

• Anti-Fabrication (P0): Every claim must have evidence (path / size / mtime / sha256)
• Authorize Before Modifying: Executing a skill != modifying it. Read -> show diff -> user confirmation required
• Minimal Changes: Only fix what violates standards, no scope expansion
• config.json is Truth Source: Thresholds, model routing, triggers live in config.json only

39 Quality Standards Summary

Range	Standards	Priority
1-4	task() tracking / I-O contract / interrupt handling / tool compliance	P1-P2
5-10	Context management / file size / I-O triple / stable workdir / anti-fabrication / externalized config	P1-P0
11-14	Example-driven / subagent split / designated agent / task description	P1
15-18	Output templates / anti-hallucination / no authority hallucination / instruction priority	P1-P0
19-24	Single-load / benchmarking / CONTEXT / negative+alternative / constraint grading	P1
25-30	Trigger orthogonality / tool-as-prompt / self-correction / external anchoring / layered responsibility / prompt chaining	P1
31-36	Dynamic context injection / structured reflection / zero-intrusion improvement / model routing / anti-patterns / blind testing	P2
37-39	Fabrication risk / tool disclosure / subagent Skill() fallback	P1-P0

---

Primary documentation: README.md (Chinese)