break-it — скилл для Claude Code: обучение через отладку RAG
Скилл предлагает найти и исправить ошибку в готовом конвейере RAG — учит понимать архитектуру быстрее, чем писать с нуля. Подходит для разработчиков, которые хотят разобраться, как работают реальные системы поиска и генерации.
npx skills add TakaGoto/rag-learning-academy --skill break-it -a claude-codeЧто делает break-it
Break-it генерирует сломанный конвейер RAG и просит найти баг. Ошибки варьируются по сложности: на лёгком уровне результаты явно неправильные, на среднем выглядят правдоподобно, но ошибочны, на сложном баги взаимодействуют друг с другом.
Скилл охватывает типичные отказы: фрагментация текста (слишком мелкие куски, отсутствие перекрытия), несовпадение моделей эмбедингов при индексации и поиске, неправильный порядок контекста в промпте, слишком строгие фильтры по метаданным, устаревший индекс. Каждый раунд логируется, что помогает отследить прогресс.
После того как ошибка найдена, скилл объясняет, почему она вызывает наблюдаемое поведение, как часто такие баги встречаются на практике и как их избежать. Если застрял, можно запросить подсказку — от указания на общую область проблемы до прямого объяснения.
Какие задачи решает
- Понять, как ошибки в фрагментации текста теряют релевантный контекст
- Отловить несовпадение моделей эмбедингов между индексацией и поиском
- Выявить эффект потери информации в середине контекста
- Диагностировать, когда индекс устаревает и не учитывает новые документы
- Научиться читать код RAG-конвейера критически
Примеры запросов агенту
- Дай мне задачу на отладку RAG среднего уровня сложности
- /break-it hard — хочу сложный баг с двумя взаимосвязанными ошибками
- Помоги разобраться, почему поиск возвращает нерелевантные результаты
Как установить break-it
1Через Skills CLI (Vercel)
npx skills add TakaGoto/rag-learning-academy --skill break-it -a claude-code2Вручную: положить файлы
~/.claude/skills/break-it/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/break-it/
1Через Skills CLI (Vercel)
npx skills add TakaGoto/rag-learning-academy --skill break-it -a codex2Вручную: положить файлы
.agents/skills/break-it/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add TakaGoto/rag-learning-academy --skill break-it -a cursor2Вручную: положить файлы
.cursor/skills/break-it/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install TakaGoto/rag-learning-academy break-it2Вручную: положить файлы
.github/skills/break-it/SKILL.md1Через Skills CLI (Vercel)
npx skills add TakaGoto/rag-learning-academy --skill break-it -a gemini-cli2Командой платформы
gemini skills install https://github.com/TakaGoto/rag-learning-academy --path .claude/skills/break-itВручную: положить файлы
.devin/skills/break-it/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add TakaGoto/rag-learning-academy --skill break-it -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о break-it
Как установить break-it в Claude Code?
Выполни npx skills add TakaGoto/rag-learning-academy --skill break-it -a claude-code, затем открой ~/.claude/skills/break-it/SKILL.md. Для других платформ команда отличается: Cursor — npx skills add TakaGoto/rag-learning-academy --skill break-it -a cursor, GitHub Copilot — gh skill install TakaGoto/rag-learning-academy break-it.
Что делает break-it?
Создаёт работающий, но неправильный RAG-конвейер и просит найти баг. Ошибки касаются чанкирования, эмбедингов, поиска, генерации или логики конвейера. После нахождения баги даёт подробное объяснение и рекомендации, как избежать таких проблем.
Можно ли выбрать уровень сложности?
Да — укажи /break-it easy, /break-it medium или /break-it hard. На лёгком одна очевидная ошибка, на среднем — одна скрытая, на сложном — два взаимосвязанных бага.
Исходный текст
SKILL.md · MIT
--- name: break-it description: "Find the bug — learn RAG by debugging intentionally broken pipelines" --- # Break It: Learn by Debugging Introduce a realistic bug into a RAG pipeline and challenge the learner to find and fix it. Debugging teaches more than building because you have to understand *why* things work to figure out *why they don't*. > **Language awareness:** See `.claude/LANGUAGE_AWARENESS.md`. ## Step 1: Choose a Difficulty If the learner specifies a difficulty (e.g., `/break-it hard`), use that. Otherwise, calibrate based on their progress: - **Easy** — One obvious bug. The pipeline runs but gives clearly wrong results. - **Medium** — One subtle bug. The pipeline runs and results look plausible but are wrong. - **Hard** — Two bugs that interact. Fixing one makes the other more visible. ## Step 2: Select a Bug Category Pick from these common RAG failure modes. Rotate through categories so the learner sees variety: ### Chunking Bugs - Chunk size set way too small (10 tokens) — fragments lose all context - Zero overlap — information at boundaries is lost - Wrong separator for the document type (splitting code on paragraphs) ### Embedding Bugs - Mismatched embedding models between indexing and querying - Missing query prefix for asymmetric models (e.g., no "query: " prefix for E5) - Embeddings not normalized, breaking cosine similarity ### Retrieval Bugs - Top-k set to 1 — missing relevant context spread across chunks - Wrong distance metric (L2 instead of cosine) - Metadata filter too restrictive — filtering out relevant results ### Generation Bugs - Context placed after the question (lost-in-the-middle effect) - No grounding instruction — model ignores context and hallucinates - Context window exceeded — retrieved chunks silently truncated ### Pipeline Bugs - Stale index — new documents added but not re-embedded - Document not chunked before embedding (entire doc as one vector) - Query embedded with a different model than the corpus ## Step 3: Present the Broken Pipeline Show the learner a complete, runnable pipeline with the bug(s) already in place. Include: 1. The code (with the bug hidden in plain sight) 2. Sample data 3. A query that exposes the bug 4. The actual output (showing the wrong behavior) 5. What the correct output should look like Say: "Something's wrong with this pipeline. The query should return [expected], but it's returning [actual]. Can you find the bug?" ## Step 4: Guide the Debugging Let the learner investigate. If they're stuck after 2 attempts, offer graduated hints: - **Hint 1** (gentle): Point to the general area — "The issue is in the retrieval step" or "Look at how the chunks are created" - **Hint 2** (specific): Narrow it down — "Compare the embedding model used for indexing vs querying" - **Hint 3** (direct): Explain the bug and why it causes the behavior ## Step 5: Explain and Connect Once they find the bug (or after hints), explain: 1. **Why** this bug causes the observed behavior 2. **How common** this bug is in real RAG systems 3. **How to prevent** it — what checks or tests would catch this early 4. **The concept** behind the fix — link to the relevant `/lesson` or `/explain` topic ## Step 6: Track and Suggest Log the debugging session to `progress/debug-log.md` with the date, bug type, difficulty, and whether they found it independently. Suggest next steps: - `/break-it [harder difficulty]` to level up - `/lesson` on the concept behind the bug - `/build` to implement the correct pattern from scratch
© TakaGoto · MIT · TakaGoto/rag-learning-academy
