agentleFS
TakaGotoTakaGoto/rag-learning-academy/.claude/skills/fix/SKILL.md

fix

Skill24 starsChanged 19 days agoMITView on GitHub

Diagnose and fix your RAG pipeline — skip the teaching, get to the answer

87 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use feature, frontend-code-review and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • bradtraversySkill

    feature

    Manage current feature workflow - start, review, explain or complete

    Also in 10 projects that use this

  • chendongqiSkill

    frontend-code-review

    Trigger when the user requests a review of frontend files (e.g., `.tsx`, `.ts`, `.js`). Support both pending-change reviews and focused file reviews while applying the checklist rules.

    Also in 4 projects that use this

  • GoogleSkill

    pr-creator

    Also in 4 projects that use this

  • PJuniszewskiSkill

    cook

    Feature development with guardrails. Plan → Review → Code → Ship.

    Also in 3 projects that use this

  • vbrevikSkill

    work

    Use when the user says 'plan', 'todo', 'copy plan', 'append plan', 'resume plan', 'priorities', or 'what's next'.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    test

    Also in 12 projects that use this

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 80 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask one question: "What's going wrong?"

    line 16
  2. Very specific:

    Ask the learner to point you to their pipeline code.

    line 30
  3. Distinctive:

    If you're not certain, rank the top 2-3 most likely causes and explain how to verify each.

    line 48
  4. Distinctive:

    If the fix requires multiple changes, prioritize: "Fix this first, then we'll check if the other issues resolve."

    line 54
  5. Distinctive:

    If still broken, go back to Step 3 with the new information

    line 61
  6. Very specific:

    After the fix works, offer (don't push): "Want to understand why this happened?

    line 65

“Common” is measured: kept by at least 6 in 10 of the 80 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Fix: Fast-Track RAG Diagnosis

Scope: This skill diagnoses and fixes an existing pipeline with no teaching. For guided debugging that explains common failure modes, use /debug-rag.

For learners who already have a RAG pipeline and just need help fixing it. No curriculum, no lessons — straight to diagnosis and solutions.

Language awareness: See .claude/LANGUAGE_AWARENESS.md.

Step 1: Get the Symptom

Ask one question: "What's going wrong?"

Common symptoms and what to probe for:

SymptomFollow-up
"Bad retrieval results"Ask for a sample query + what it returns vs what it should return
"Hallucinating"Ask if context is being passed, and what the prompt looks like
"Slow"Ask about data size, embedding model, vector DB, and whether they're batching
"No results"Ask if data is indexed, and check the collection exists
"Works sometimes"Ask for a working query and a failing query — compare them

Step 2: Read Their Code

Ask the learner to point you to their pipeline code. Read the files in src/ or wherever they indicate. Look at:

  1. Chunking — strategy, size, overlap
  2. Embedding — model, dimensions, normalization
  3. Storage — vector DB config, distance metric
  4. Retrieval — top-k, filters, search type
  5. Generation — prompt template, context injection, grounding instructions

Step 3: Diagnose

Identify the likely root cause. Present it clearly:

Diagnosis: [one-line summary]
Root cause: [what's actually happening]
Evidence: [what in their code/output points to this]

If you're not certain, rank the top 2-3 most likely causes and explain how to verify each.

Step 4: Fix It

Provide the specific code change needed. Show a before/after diff if possible. Explain why the fix works in 1-2 sentences — enough to understand, not a lecture.

If the fix requires multiple changes, prioritize: "Fix this first, then we'll check if the other issues resolve."

Step 5: Verify

Help them test the fix:

  1. Re-run the failing query
  2. Compare the output to what they expected
  3. If still broken, go back to Step 3 with the new information

Step 6: Optional Learning

After the fix works, offer (don't push): "Want to understand why this happened? /explain [relevant concept] goes deeper on this."

Log the fix to progress/debug-log.md if the file exists.

Suggest next steps:

  • /lesson on the concept behind the issue
  • /build to implement the correct pattern from scratch
  • /roadmap to see your overall progress

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.