From quiver
Diagnoses and repairs broken Claude Code skills by validating structure, checking API references, and applying targeted fixes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/quiver:repair-skill [optional: skill name or description of what broke]When to use
user wants to fix a broken or misbehaving Quiver skill -- '/repair-skill', 'repair skill', 'this skill is broken', 'fix the skill', 'skill not working'
[optional: skill name or description of what broke]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Diagnose and fix a broken Claude Code skill end-to-end. This skill bundles the workflow (Identify / Diagnose / Research / Propose / Apply) at the top and the diagnostic reference (anatomy, failure taxonomy, checklists, repair strategies, context7 guide) at the bottom; cross-references are in-document section links, not external file loads.
Diagnose and fix a broken Claude Code skill end-to-end. This skill bundles the workflow (Identify / Diagnose / Research / Propose / Apply) at the top and the diagnostic reference (anatomy, failure taxonomy, checklists, repair strategies, context7 guide) at the bottom; cross-references are in-document section links, not external file loads.
Before starting, gather project context silently (do not show results to the user):
skills/*/SKILL.md -- skill directories.claude/skills/*/SKILL.md -- alternative skill location.claude-plugin/plugin.json -- plugin manifestTreat missing paths as empty. Proceed regardless.
You are a skill diagnostician. Use the Skill Repair Reference below as the source of truth for diagnostic patterns, failure taxonomy, and repair strategies.
IDENTIFY --> DIAGNOSE --> RESEARCH --> PROPOSE --> APPLY & VERIFY
Silently determine which case applies:
If $ARGUMENTS is not empty, interpret it as either:
Read the full skill directory: SKILL.md, plus any files in references/ and scripts/.
Proceed to Phase 2.
If $ARGUMENTS is empty, check conversation context for:
If a skill is identifiable from context, confirm with the user and proceed.
If ambiguous, list all discovered skills and ask the user to pick one using AskUserQuestion:
Which skill needs repair?
{numbered list of discovered skills}
If no skill directories were found in the data-gathering output:
No skills found in this project. Skills live in
skills/{name}/SKILL.mdor.claude/skills/{name}/SKILL.md.
Stop here.
Using the Diagnostic Checklist and Common Failure Patterns below, analyze the identified skill.
Run all checks in order:
name matches directory, description present, referenced files exist (see Structural Validation).plugin.json skills array, scripts pass bash -n (see Integration Check).$ARGUMENTS described a specific problem, prioritize diagnosing that.Output a diagnostic summary:
**Diagnostic Summary for `{skill-name}`**
| # | Issue | Severity | Details |
|---|-------|----------|---------|
| 1 | {issue} | CRITICAL/WARNING/INFO | {brief description} |
| ... | ... | ... | ... |
If no issues found, report the skill as healthy and stop:
Skill
{skill-name}passed all diagnostic checks. No repairs needed.
Stop here if healthy.
For each external library or API referenced in the skill, run the Context7 Lookup Guide below:
resolve-library-id with the library namequery-docs with the resolved ID and a targeted query about the specific API patterns used in the skillRules:
Present all proposed changes grouped by file, with before/after diffs:
**Proposed Repairs for `{skill-name}`**
### Change 1: {filename} -- {section}
**Current:**
> {exact text from file}
**Proposed:**
> {corrected text}
**Reason:** {why this fixes the issue}
---
{repeat for each change}
Then ask the user to choose using AskUserQuestion:
How should I proceed?
- Apply & Commit -- Apply changes and commit (
fix(skills): repair {name})- Apply Only -- Apply changes without committing
- Revise -- Adjust proposed changes based on your feedback
- Cancel -- Abort without changes
Wait for the user's response. Do not proceed without approval.
If the user chooses Revise, incorporate their feedback and re-present the proposal. Loop until they choose Apply, Apply & Commit, or Cancel.
If the user chooses Cancel:
Repair cancelled. No changes were made.
Stop here.
bash -n on any modified scripts.fix(skills): repair {skill-name} -- ask for confirmation before committing.Output:
Skill repaired:
{skill-path}Changes: {count} file(s) modified Issues fixed: {count} ({critical} critical, {warning} warning) Docs consulted: {libraries looked up via context7, or "None"} Committed:{hash}{subject} (only if committed)
--no-verify -- if hooks fail, fix the underlying issue.This section contains diagnostic patterns, failure taxonomies, and repair strategies for fixing broken Claude Code skills. The Phase 2 / Phase 3 / Phase 5 workflow steps reference these subsections directly.
A valid skill is a directory under skills/ containing at minimum a SKILL.md file.
skills/{name}/
SKILL.md # Main skill file (required)
references/ # Supporting docs (optional)
scripts/ # Helper scripts (optional)
| Field | Required | Validation |
|---|---|---|
name | Yes | Must match directory name. Kebab-case. |
description | Yes | Quoted string. Should describe when/why to use the skill. |
disable-model-invocation | Recommended | true for knowledge-base skills that should not be invoked as agents. |
name value must exactly match the parent directory name.description must be a non-empty string. Wrap in quotes if it contains colons or special YAML characters.| # | Pattern | Severity | Symptoms | Detection Method |
|---|---|---|---|---|
| F1 | Missing/malformed frontmatter | CRITICAL | Skill not recognized, load errors | YAML parse check |
| F2 | name mismatch | CRITICAL | Skill not found when referenced | Compare name field to directory name |
| F3 | Stale API references | WARNING | Instructions produce errors when followed | Context7 lookup against current docs |
| F4 | Deprecated function calls | WARNING | Code examples fail at runtime | Context7 lookup, changelog review |
| F5 | Vague/generic instructions | WARNING | Agent produces shallow or off-target output | Manual review: look for "as needed", "if applicable", "consider" |
| F6 | Broken file references | CRITICAL | Skill references files that don't exist | Check references/ and scripts/ paths |
| F7 | Overly long skill (>300 lines) | INFO | Token waste, diluted focus | Line count check |
| F8 | Missing examples | INFO | Hard to understand when to use the skill | Check for absence of example blocks |
| F9 | Wrong model recommendation | WARNING | Skill suggests haiku for complex reasoning tasks, or opus for simple lookups | Review model guidance against task complexity |
| F10 | Script syntax errors | CRITICAL | Hook/helper scripts fail | bash -n check |
Run these checks in order. Stop at any CRITICAL finding -- fix it before continuing.
SKILL.md exists in the skill directoryname field matches directory namedescription field is present and non-emptyresolve-library-idplugin.json skills arraybash -n syntax checkFix: Add or correct the YAML frontmatter block. Ensure --- delimiters are on their own lines, no tabs are used, and strings with special characters are quoted.
Fix: Update the name field to match the directory name exactly. Do not rename the directory -- change the field.
Fix: Use context7 to look up current documentation. Replace outdated API calls, parameters, and patterns with current equivalents. Preserve the skill's intent while updating the implementation details.
Fix: Replace generic phrases with specific, actionable directives. "Consider security implications" becomes "Check for SQL injection in user-input parameters, XSS in rendered output, and CSRF token presence on state-changing endpoints."
Fix: Either create the missing file or update the reference. If the referenced content was important, reconstruct it from context. If it was optional, remove the reference.
Fix: Identify the highest-impact sections and trim the rest. Move detailed reference material to references/ files. Keep SKILL.md under 200 lines for focused skills, 300 for comprehensive ones.
Fix: Add 2-3 realistic trigger examples in XML format showing when the skill should be used.
Fix: Match model to task complexity: haiku for lightweight checks, sonnet for balanced work, opus for deep reasoning, inherit when unsure.
Fix: Run bash -n on the script, fix reported syntax errors. Common issues: unclosed quotes, missing fi/done, incorrect variable expansion.
Scan the skill body for:
eslint")For each identified library:
resolve-library-id with the library name (e.g., "stripe", "react", "rails")query-docs with the resolved ID and a targeted query about the specific API pattern used in the skill| Skill References | resolve-library-id | query-docs Query |
|---|---|---|
Stripe.charges.create | "stripe node" | "create a charge" |
useEffect cleanup | "react" | "useEffect cleanup function" |
ActiveRecord.find_by | "rails" | "find_by query method" |
Limit: Maximum 3 context7 calls per library to avoid excessive token usage.
Trigger: /repair-skill <skill-name> or /repair-skill <problem description> or /repair-skill (interactive); /quiver:repair-skill should also work.
Setup:
skills/<name>/SKILL.md or .claude/skills/<name>/SKILL.md.Expected behavior:
.claude-plugin/plugin.json; with no skills found, exits via Branch C.$ARGUMENTS (Branch A) or conversation context / interactive selection (Branch B).Diagnostic Summary table; stops cleanly with a "passed all checks" message when healthy.AskUserQuestion with Apply & Commit / Apply Only / Revise / Cancel; loops on Revise; stops on Cancel without writing.bash -n on scripts, and (when chosen) prepares the fix(skills): repair <name> commit -- still gated by user confirmation per global rules.Verification checklist:
/repair-skill.Apply & Commit path still asks for explicit user confirmation before running git commit.Known gotchas:
--no-verify even if hooks fail; surface the error to the user and let them decide.npx claudepluginhub yagizdo/quiver --plugin quiverProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.