From quiver
Diagnose and fix a broken skill by analyzing its structure, verifying API references against current docs, and applying targeted repairs.
npx claudepluginhub yagizdo/quiver --plugin quiverThis skill uses the workspace's default tool permissions.
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.
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.
Checks Next.js compilation errors using a running Turbopack dev server after code edits. Fixes actionable issues before reporting complete. Replaces `next build`.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Share bugs, ideas, or general feedback.
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.