Tag: claude-code

The Seven Biggest Claude Skills Collections: What’s Inside, Which to Trust, and How to Use Them

English | Русский

The Seven Biggest Claude Skills Collections: What’s Inside, Which to Trust, and How to Use Them

TL;DR — if you only read this box:

  • Start here: anthropics/skills for a small, production-grade, vetted set. Add glebis/claude-skills (~90 tidy personal skills) if you want more, or obra/superpowers if you want a whole workflow, not a grab-bag. Use travisvn / jqueryscript as link indexes to discover the rest.
  • Do skills work? Yes, with a catch: they’re proven in production and show a real but conditional lift — a few skills that reliably match your task beat a hundred installed "just in case."
  • The one thing to avoid: don’t copy rohitg00‘s MCP configs blind — they point your agent at npm packages that don’t exist, under an official-looking @anthropic/ scope that isn’t Anthropic’s.
  • The habit that saves you: give any repo a 15-minute read before you trust it — npm info every package it names, grep for what runs automatically. A big star count is not a safety check.

If you’ve gone looking for ready-made "skills" for your Claude agent, you’ve seen the pattern: a dozen repositories called some variation of awesome-claude-skills, the biggest with more stars than most programming languages, each promising hundreds of drop-in capabilities. Which one do you pull from? And once you do, can you trust what you just dropped into a tool that runs with your permissions?

I went through the seven biggest so you don’t have to start from a star count. This is the field guide I wish I’d had: what a skill is and whether skills even work, what’s inside each collection and who it’s for, which ones survive a real security check, and how to use them so they help instead of just filling up your context window. Every repo name below links straight to its GitHub page, so any number I quote — starting with those eye-widening star counts — is one click to check.

First, one line of vocabulary, because the rest leans on it. A skill is a small folder — a Markdown file, sometimes a script or two — that you drop in to change how your agent behaves on a task ("when the user asks for a spreadsheet, do it this way"). An MCP config is its sibling: a little JSON file that tells the agent which external tools to install and run, usually with a line like npx -y some-package. Both install in seconds. That convenience is the whole reason to be a little careful.

Do skills actually work?

Yes — with a catch worth understanding before you install twenty of them.

The strongest evidence isn’t a benchmark — it’s production. Anthropic’s own document skills (the ones that build xlsx, docx, pptx, and pdf files) are, by their own README, the skills that power Claude’s document-creation feature in the actual product. That’s not a lab result; it’s a capability millions of people already use, implemented as exactly the kind of skill file you can install yourself.

For an independent number, one study put the format to the test — How Well Do Agentic Skills Work in the Wild — and found a genuine lift: on the Terminal-Bench 2.0 benchmark, adding skill retrieval moved pass rate from 57.7% to 65.5%. But the same paper is just as clear about the ceiling: as the test conditions got more realistic, the gains shrank back toward the no-skill baseline. Skills help most when the right skill reliably fires for the task in front of the agent.

💡 The catch is triggering, not capability. A skill only helps if the agent actually loads it at the right moment — and "skills that won’t trigger" is Anthropic’s own top troubleshooting note. Each skill also costs context to keep around. So a curated handful you know will fire beats a hundred you installed "just in case."

That single idea — targeted beats maximal — is the lens for reading the rest of this guide. The question isn’t "which repo has the most skills." It’s "which few match what I actually do."

The map: seven collections, and who each one is for

The star counts and the last-updated dates below are live GitHub readings from July 2, 2026, not numbers from a README. Both matter — a collection is only as good as the last time someone tended it, and here the freshness split is sharp: three are updated almost daily, one hasn’t been meaningfully touched in months.

Collection Stars Last update What it really is
obra/superpowers 243,958 Jul 1 · very active Skills plus an enforced end-to-end workflow
anthropics/skills 157,558 Jul 1 · near-daily Anthropic’s own first-party skills, auto-synced from internal
ComposioHQ/awesome-claude-skills 66,589 May 22 · stale Mostly a link index + one company’s platform skills
travisvn/awesome-claude-skills 13,870 Apr 28 · slowing A clean list of links
rohitg00/awesome-claude-code-toolkit 2,233 May 12 · abandoned* A real toolkit bolted to a dead link dump
jqueryscript/awesome-claude-code 453 Jun 29 · active The broadest map of the whole ecosystem
glebis/claude-skills 301 Jul 2 · active A tidy personal collection of ~90 skills

* last commit May 12, but 183 issues sit open and nothing’s been merged in ~7 weeks — the pushes stopped, the queue didn’t.

Here’s the one reason to reach for each — and the maintenance reality that should temper it:

  • anthropics/skills — pick it for trust. Anthropic’s own skills, mirrored from an internal source almost daily. The vetted place to start: the document skills that run in production, plus skill-creator (a skill that builds and tests skills), mcp-builder, webapp-testing, frontend-design. Small on purpose. If you install from nowhere else, install from here.
  • obra/superpowers — pick it for a whole workflow, not a pantry. The quarter-million-star one, and a different animal: an opinionated process that sequences skills — brainstorm, plan, human sign-off, build test-first, review with a fresh agent, finish the branch. Very actively developed, though by essentially one maintainer with no CI, so the quality gate is a single person.
  • glebis/claude-skills — pick it for a curated, human-sized set. Pushed the very day I looked. About 90 tidy personal skills — test-driven development, release automation, a small LLM command-line tool. If the big two feel like too much, this is the browsable middle.
  • jqueryscript/awesome-claude-code — pick it to see the whole territory. Recently updated, and the broadest census of the ecosystem — apps, tools, and skills, not just a skill list. A map, not a toolbox.
  • travisvn/awesome-claude-skills — pick it as a clean discovery list. A well-kept index of links, though the updates have slowed since late April. Good for finding, not a vetted install.
  • ComposioHQ/awesome-claude-skills — pick it only to browse. A link index padded with one company’s own platform skills, last touched in May. Its "1000+ production-ready" headline is really thirty to forty real skills; the rest is a platform integration count folded in.
  • rohitg00/awesome-claude-code-toolkit — mostly skip, mine for parts. The competent first-party bits are worth a look, but the repo is effectively abandoned (183 open issues, no merges in weeks) and its MCP configs are broken in a way that matters — see the caution below. Don’t install it wholesale.

One habit these last two teach: count the folder, not the banner. rohitg00‘s README claims 35 skills, 135 agents, 176+ plugins; its own marketplace.json says 120 plugins; the actual files say 40 skills and 16 MCP configs — three numbers for one repo, none matching.

How to install one

There are two paths, and neither takes more than a minute — which is why the vetting below matters.

A single skill, by hand. A skill is just a folder with a SKILL.md inside. Drop it in ~/.claude/skills/<name>/ and it’s available in every project; drop it in .claude/skills/<name>/ inside a repo and it ships with that project (and to your teammates via git). Claude Code picks it up live — no restart. So to grab one skill from any of these collections, you can literally clone the repo and copy the folder you want:

git clone https://github.com/glebis/claude-skills
cp -r claude-skills/skills/tdd ~/.claude/skills/tdd    # now available as a skill

A whole collection, via the plugin marketplace. The bigger repos ship as installable plugins. Add the repo as a marketplace, then install what you want from it — all inside Claude Code:

/plugin marketplace add anthropics/skills   # register the collection
/plugin                                      # browse and install from it

obra/superpowers is on Anthropic’s own official marketplace, so it installs the same way — open /plugin, find it, install. Use /plugin any time to see what’s installed or turn things off.

An MCP config (the tool bundles) is separate: you either run claude mcp add --transport http <name> <url> or drop a .mcp.json at your project root. This is the one to slow down on — it’s the rohitg00 case from earlier, where the config named packages that don’t exist. Run npm info on every package a config lists before you let it install anything.

Which ones to trust: what a real check turns up

Stars measure how far a project spread, not whether anyone vetted what it ships. So for the three collections that contain runnable code — anthropics/skills, superpowers, and the rohitg00 toolkit — I ran an actual security pass, not a glance. (The rest are link lists; nothing to run, nothing to check.) Two of the three came back clean, and even the alarming-looking one is mostly a false alarm.

Take superpowers, the assertive one. It installs a hook that fires before you type anything, injecting a block marked <EXTREMELY_IMPORTANT> that reads, verbatim, "IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE." That looks like a red flag. It isn’t: it’s disclosed, versioned, MIT-licensed text the project applies to its own agent in the open, and you can read every line before it runs. Underneath is a genuinely careful design — human approval before code gets written, a fresh sub-agent per task, an independent reviewer told not to trust the first agent’s word. anthropics/skills was clean too, down to its one shell=True call sitting in a browser-testing script the agent already had the keys to run.

The one caution in the whole set is worth stating plainly, because it’s the kind of thing a star count will never warn you about.

📌 Don’t copy rohitg00‘s MCP configs blind. They tell your agent to install npm packages under the @anthropic/ scope — mcp-ghidra, mcp-figma, mcp-server-figma — that do not exist (all 404), along with kubectl-mcp-app and mcp-terraform. Anthropic’s real scope is @anthropic-ai, not @anthropic. An official-looking, unclaimed namespace pointing at missing packages is a slot waiting to be filled: if someone registers it and publishes malware, the people who run it first are the ones who copied this config trusting the name.

Nobody there did this on purpose — these read like package names a model invented and no one ran npm info against. Which is exactly the habit worth borrowing, and it costs one command.

How to actually use skills well

Two halves: check what you install, then use less of it than you think.

Before you install anything — a fifteen-minute vet. None of this is hard, and it’s the same list regardless of the repo:

  • Read the actual files, not the README. The gap between the two is the whole point of this piece.
  • npm info every package a config names. A name that doesn’t resolve is a blank someone else can fill.
  • grep for ungated eval, exec, child_process, subprocess, shell=True. A hit isn’t automatically bad — it’s a thing to understand before you run it.
  • grep for curl … | bash and wget … | sh. Piping the internet straight into a shell is the classic install-script trap; it usually shows up for linked third-party projects, not the repo’s own code.
  • grep the hooks for network calls. Hooks run automatically every session — that’s where a phone-home would hide.
  • Skim the git log. Two commits on day one and nothing since (the rohitg00 story) tells you no one’s minding it.

Then use fewer skills than you want to. Because triggering is the bottleneck, not capability, the winning move is a small set matched to your real work:

  • The description is the skill’s on-switch. Skills undertrigger; a vague description means it never loads and never helps. Prefer skills whose descriptions clearly name when they apply — and sharpen your own.
  • Keep each skill small. The best ones use "progressive disclosure" — a one-line summary always loaded, the full instructions pulled in only when triggered, heavy references fetched on demand. Bloated skills cost context for nothing.
  • Don’t install everything. A hundred dormant skills is a hundred descriptions competing for the agent’s attention and your token budget. Curate to the handful you’ll actually hit.
  • Prefer disclosed and maintained. superpowers is loud but transparent; a silent, unmaintained repo with a big number is the worse bet.

The one-line takeaway

The star count told me almost nothing. The cleanest collection in the set had 244,000 stars; the one with the namespace hole had 2,233; the tidy, careful personal set had 301. Popularity tracked reach, not whether anyone had looked inside.

So if you’re shopping for skills: start with anthropics/skills for things known to work, add glebis or superpowers if you want more or want a whole workflow, use the link indexes to discover the rest — and give anything a fifteen-minute read before you trust it. That’s less time than you’ll spend picking which skills to install, and it’s the difference between a tool you understand and a number you hoped was fine.

Топ-7 коллекций скиллов для Claude: что внутри, каким доверять и как ими пользоваться

Коротко — если дальше не читать:

  • С чего начать: anthropics/skills — небольшой проверенный набор от самой Anthropic. Мало — добавьте glebis/claude-skills (аккуратные ~90 личных скиллов); хотите не набор, а целый рабочий процесс — obra/superpowers. Каталоги travisvn и jqueryscript — чтобы осмотреться, что вообще есть.
  • Скиллы вообще работают? Да, но с оговоркой: польза доказана в проде и реальна, только не безусловна — пара скиллов, которые точно подходят под вашу задачу, полезнее сотни, поставленных «на всякий случай».
  • Чего не делать: не копируйте MCP-конфиги из rohitg00 вслепую — они шлют вашего агента ставить npm-пакеты, которых не существует, под похожим на официальный scope @anthropic/, который Anthropic не принадлежит.
  • Привычка, которая выручает: прежде чем довериться репозиторию, потратьте на него 15 минут — проверьте npm info каждый пакет, grep-ните то, что запускается само. Куча звёзд — это не проверка.

Если вы искали готовые «скиллы» для своего агента на Claude, картина знакома: десяток репозиториев с названиями вроде awesome-claude-skills, у самых крупных звёзд больше, чем у иных языков программирования, и каждый обещает сотни готовых умений. Из какого брать? И можно ли доверять тому, что вы только что скормили инструменту, который дальше действует от вашего имени?

Я прошёл семь крупнейших, чтобы вам не пришлось начинать с числа звёзд. Это путеводитель, которого мне самому не хватало: что такое скилл и работают ли скиллы вообще, что лежит внутри каждой коллекции и кому она подойдёт, какие выдерживают настоящую проверку на безопасность и как всем этим пользоваться, чтобы помогало, а не просто забивало контекст. Каждое имя репозитория ниже — ссылка прямо на GitHub, так что любую цифру — хоть эти ошеломляющие звёзды — можно проверить одним кликом.

Сначала одна строчка про слова — дальше без них никак. Скилл — это маленькая папка (файл Markdown, иногда пара скриптов), которую подкладывают агенту, чтобы он иначе вёл себя в работе («просят таблицу — делай вот так»). MCP-конфиг — его сосед: небольшой файл JSON, который говорит агенту, какие внешние инструменты поставить и запустить, обычно строкой вроде npx -y некий-пакет. И то, и другое ставится за секунды. Вот из-за этой лёгкости и стоит держать ухо востро — к этому вернёмся.

Скиллы вообще работают?

Если коротко — да, но с оговоркой, которую стоит понять, прежде чем ставить их два десятка.

Сильнее всего убеждает не бенчмарк, а прод. Собственные скиллы Anthropic для документов — те, что собирают xlsx, docx, pptx и pdf, — по их же README и есть те самые, на которых держится функция создания документов в самом Claude. Это не лабораторный результат, а возможность, которой уже пользуются миллионы, — и сделана она ровно таким же файлом-скиллом, какой можете поставить и вы.

Есть и независимая цифра. Одно исследование прогнало этот формат через испытания — How Well Do Agentic Skills Work in the Wild — и нашло реальный прирост: на бенчмарке Terminal-Bench 2.0 добавление скиллов подняло долю решённых задач с 57,7% до 65,5%. Но там же ясно сказано и про потолок: чем ближе условия к реальным, тем сильнее прирост сходил на нет, возвращаясь к уровню «вообще без скиллов». Скиллы помогают больше всего, когда нужный из них надёжно срабатывает на задаче, которая сейчас перед агентом.

💡 Загвоздка не в возможностях, а в срабатывании. Скилл помогает, только если агент действительно подхватит его в нужный момент, — а «скилл не срабатывает» стоит первым пунктом в собственной шпаргалке Anthropic по разбору проблем. Каждый скилл к тому же занимает контекст. Так что горстка, про которую вы знаете, что она сработает, лучше сотни, поставленной впрок.

Эта мысль — точечное бьёт максимальное — и есть та оптика, с которой стоит читать дальше. Вопрос не в том, «в каком репозитории скиллов больше», а в том, «какие несколько подходят именно под мою работу».

Карта: семь коллекций и кому какая

И звёзды, и даты последнего обновления ниже — живые цифры из GitHub на 2 июля 2026 года, а не то, что написано в README. Важно и то, и другое: коллекция хороша ровно настолько, насколько недавно её кто-то трогал, — а разрыв тут резкий: три обновляются почти каждый день, одну не трогали месяцами.

Коллекция Звёзды Обновлено Что это на самом деле
obra/superpowers 243 958 1 июл · живой Скиллы плюс навязанный сквозной рабочий процесс
anthropics/skills 157 558 1 июл · почти ежедневно Скиллы самой Anthropic, приходят из внутреннего репозитория
ComposioHQ/awesome-claude-skills 66 589 22 мая · застой В основном каталог ссылок + скиллы одной платформы
travisvn/awesome-claude-skills 13 870 28 апр · замедляется Аккуратный список ссылок
rohitg00/awesome-claude-code-toolkit 2 233 12 мая · заброшен* Реальный тулкит, приклеенный к мёртвой свалке ссылок
jqueryscript/awesome-claude-code 453 29 июн · живой Самая широкая карта всей экосистемы
glebis/claude-skills 301 2 июл · живой Аккуратная личная коллекция из ~90 скиллов

* последний коммит 12 мая, но 183 issue висят открытыми и за ~7 недель ничего не влито — коммиты прекратились, а очередь нет.

Вот одна причина взять каждую — и та правда о поддержке, которая эту причину остужает:

  • anthropics/skills — берут за доверие. Скиллы самой Anthropic — их почти каждый день выкладывают из внутреннего репозитория. Проверенная точка старта: те самые скиллы для документов, что крутятся в проде, плюс skill-creator (скилл, который собирает и тестирует скиллы), mcp-builder, webapp-testing, frontend-design. Небольшая намеренно. Если ставить только откуда-то одного — отсюда.
  • obra/superpowers — берут не за набор, а за целый процесс. Тот самый на четверть миллиона звёзд, и это другой зверь: не мешок скиллов, а продуманный порядок работы — обдумать, составить план, взять подпись человека, писать через тесты, ревью свежим агентом, закрыть ветку. Развивается очень активно, но по сути одним автором и без CI — то есть весь контроль качества держится на одном человеке.
  • glebis/claude-skills — берут за курированный человеческий набор. Обновлён в тот самый день, когда я смотрел. Около 90 аккуратных личных скиллов — разработка через тесты, автоматизация релизов, маленькая консольная утилита для LLM. Если два гиганта — перебор, вот золотая середина.
  • jqueryscript/awesome-claude-code — берут, чтобы увидеть всю территорию. Недавно обновлён и даёт самую широкую перепись экосистемы — приложения, инструменты и скиллы, не только скиллы. Карта, а не ящик с инструментами.
  • travisvn/awesome-claude-skills — берут как чистый список для поиска. Опрятный указатель ссылок, хотя с конца апреля обновления замедлились. Хорош, чтобы находить, но это не проверенная установка.
  • ComposioHQ/awesome-claude-skills — берут только чтобы полистать. Каталог ссылок, разбавленный скиллами собственной платформы, последний раз тронут в мае. Заголовок «1000+ готовых к проду» на деле — тридцать-сорок реальных скиллов; остальное — число интеграций платформы, подмешанное в цифру.
  • rohitg00/awesome-claude-code-toolkit — скорее пропустить, разобрать на детали. Толковые собственные куски глянуть стоит, но репозиторий фактически заброшен (183 открытых issue, недели без вливаний), а его MCP-конфиги сломаны так, что это важно, — см. предупреждение ниже. Целиком не ставьте.

Эти двое учат одному наверняка: считать папку, а не баннер. README у rohitg00 заявляет 35 скиллов, 135 агентов, 176+ плагинов; его же marketplace.json — 120 плагинов; а сами файлы — 40 скиллов и 16 MCP-конфигов. Три числа на один репозиторий, и ни одно не сходится.

Как это вообще поставить

Есть два пути, и ни один не займёт больше минуты — потому-то проверка ниже и важна.

Один скилл, руками. Скилл — это просто папка с файлом SKILL.md внутри. Положите её в ~/.claude/skills/<имя>/ — и она доступна во всех проектах; положите в .claude/skills/<имя>/ внутри репозитория — и она поедет вместе с проектом (и к коллегам через git). Claude Code подхватывает её на лету, без перезапуска. Так что взять один скилл из любой коллекции можно буквально клонированием и копированием нужной папки:

git clone https://github.com/glebis/claude-skills
cp -r claude-skills/skills/tdd ~/.claude/skills/tdd    # теперь доступен как скилл

Целую коллекцию — через маркетплейс плагинов. Репозитории покрупнее ставятся как плагины. Добавляете репозиторий как маркетплейс, потом ставите из него нужное — всё прямо в Claude Code:

/plugin marketplace add anthropics/skills   # подключить коллекцию
/plugin                                      # смотреть и ставить из неё

obra/superpowers лежит в собственном официальном маркетплейсе Anthropic, так что ставится так же: открываете /plugin, находите, ставите. Через /plugin в любой момент видно, что установлено, и что можно отключить.

MCP-конфиг (те самые связки инструментов) — отдельная история: либо claude mcp add --transport http <имя> <url>, либо файл .mcp.json в корне проекта. Вот тут стоит притормозить — это как раз случай rohitg00, где конфиг называл несуществующие пакеты. Прогоните npm info по каждому пакету из конфига до того, как дадите ему что-то ставить.

Каким доверять: что показывает настоящая проверка

Звёзды меряют, как далеко разошёлся проект, а не проверял ли кто-нибудь, что он несёт. Поэтому три коллекции, где есть исполняемый код, — anthropics/skills, superpowers и тулкит rohitg00 — я прогнал через настоящую проверку на безопасность, не бегло. (Остальные — списки ссылок: запускать нечего, значит и проверять нечего.) Сначала хорошее: две из трёх чисты, и даже пугающая на вид — по большей части ложная тревога.

Возьмём superpowers, самый напористый. Он ставит хук, который срабатывает раньше, чем вы что-либо наберёте, и вставляет блок с пометкой <EXTREMELY_IMPORTANT>, где дословно сказано: «ЕСЛИ СКИЛЛ ПОДХОДИТ К ТВОЕЙ ЗАДАЧЕ, У ТЕБЯ НЕТ ВЫБОРА». Выглядит как красный флаг. Но нет: это раскрытый, версионируемый текст под лицензией MIT, который проект открыто применяет к собственному агенту, — и каждую строчку можно прочитать до запуска. А под ней — по-настоящему аккуратная схема: подпись человека до того, как написан код, свежий подагент на каждую задачу, независимый ревьюер, которому велено не верить словам первого агента. anthropics/skills тоже чист — вплоть до единственного вызова shell=True, и тот сидит в скрипте тестирования веб-приложений, куда агент и так имел доступ.

Единственное предостережение на весь набор стоит сказать прямо — как раз о том, о чём число звёзд никогда не предупредит.

📌 Не копируйте MCP-конфиги из rohitg00 вслепую. Они велят агенту поставить npm-пакеты под scope @anthropic/ — mcp-ghidra, mcp-figma, mcp-server-figma, — которых не существует (все 404), плюс kubectl-mcp-app и mcp-terraform. Настоящий scope у Anthropic — @anthropic-ai, не @anthropic. Похожий на официальный, но никем не занятый scope, указывающий на несуществующие пакеты, — это пустая ячейка, ждущая, кто её займёт: зарегистрируй кто-нибудь этот scope и опубликуй вредонос — первыми его запустят те, кто скопировал конфиг, доверившись имени.

Никто там не делал этого нарочно — имена читаются так, будто их выдумала модель, а npm info против них никто не прогнал. Что и есть та самая привычка, которую стоит перенять, и стоит она одной команды.

Как со скиллами работать по уму

Две половины: проверяйте, что ставите, — и ставьте меньше, чем хочется.

Перед установкой — проверка на пятнадцать минут. Ничего сложного, и список один и тот же, из какого бы репозитория вы ни брали:

  • Читайте сами файлы, а не README. Разрыв между ними — вся суть этой статьи.
  • Прогоните npm info по каждому пакету из конфига. Имя, которое не находится, — это пустая ячейка, которую займёт кто-то другой.
  • grep-ните ничем не огороженные eval, exec, child_process, subprocess, shell=True. Попадание — не приговор, а повод разобраться, прежде чем запускать.
  • grep-ните curl … | bash и wget … | sh. Загонять интернет прямо в оболочку — классическая ловушка установочных скриптов; обычно это всплывает у чужих, приклеенных ссылками проектов, а не в коде самого репозитория.
  • grep-ните хуки на сетевые вызовы. Хуки запускаются сами каждую сессию — там и спрятался бы «звонок домой».
  • Пробегите историю коммитов. Два коммита в первый день и тишина потом (история rohitg00) говорят, что за репозиторием никто не следит.

А дальше ставьте меньше скиллов, чем тянет. Раз всё упирается в срабатывание, а не в возможности, выигрывает небольшой набор под вашу настоящую работу:

  • Описание — это выключатель скилла. Скиллы и так частенько не включаются; а с размытым описанием скилл не подхватится вообще — и не поможет. Берите те, у которых в описании ясно сказано, когда они к месту, — и затачивайте свои.
  • Держите каждый скилл маленьким. Лучшие устроены по принципу «раскрытие по мере надобности»: одна строка-сводка всегда в памяти, полные инструкции подтягиваются только при срабатывании, тяжёлые справочники — по запросу. Раздутый скилл занимает контекст впустую.
  • Не ставьте всё подряд. Сотня спящих скиллов — это сотня описаний, которые борются за внимание агента и ваш бюджет токенов. Оставьте горстку, которой и правда будете пользоваться.
  • Предпочитайте раскрытое и поддерживаемое. superpowers громкий, но прозрачный; молчаливый заброшенный репозиторий с большим числом — ставка хуже.

Одна мысль на вынос

Число звёзд не сказало мне почти ничего. У самой чистой коллекции в наборе — 244 тысячи звёзд, у той, что с дырой в пакетах, — 2233, у аккуратного личного набора — 301. Популярность мерила охват, а не то, заглянул ли кто внутрь.

Так что если подбираете себе скиллы: начните с anthropics/skills ради того, что точно работает, добавьте glebis или superpowers, если хочется больше или нужен целый процесс, а каталогами пользуйтесь, чтобы найти остальное, — и дайте любому репозиторию пятнадцать минут чтения, прежде чем довериться. Это меньше времени, чем вы потратите на выбор скиллов, — и это разница между инструментом, который вы понимаете, и числом, на которое понадеялись.

How to Organize a Repository for an LLM Agent

English | Русский

How to Organize a Repository for an LLM Agent

More complex is better? I don’t think so. Five tiers of repository organization:

  • Tier 0 — flat files. Everything in context. Prototypes, configs, small projects under 20 files.
  • Tier 1 — text search + CLAUDE.md. How every AI coding agent works. Code projects up to 500 files.
  • Tier 2 — docs-as-code. Structured documentation for teams. Stripe, Kubernetes, Django — no RAG needed.
  • Tier 3 — LLM wiki, the Karpathy method. An LLM compiles a wiki from raw sources. Hundreds of documents.
  • Tier 4 — wiki + RAG + knowledge graph. Semantic search and entity relationships. 500+ sources.

Don’t move to the next tier if the current one works.

LLM agents today solve radically different problems. One writes code in a ten-thousand-file repository. Another researches five hundred scientific papers. A third maintains documentation for two hundred people. Applying the same knowledge organization approach to all of these is overkill. I went through all five tiers on my own project — a university course on AI with hundreds of sources, dozens of artifacts, and a single author — and below I’ll explain what works at which scale.

In 2024–2025, while the industry was building complex RAG pipelines and knowledge graphs, Cursor soared to $100M ARR with an approach built on an embedding index and text search over code. Not because text search is better than RAG — but because for code, it’s the right tool. Specifically for code.

In the world of knowledge organization for agents, people make two symmetrical mistakes. Some underinvest: 500 documents plus text search equals chaos — nothing gets found. Others overinvest: as Paul Hoke described, a developer deleted 2,000 lines of RAG code and accuracy jumped to 94%.

There is no “best” way to organize knowledge for an LLM agent. There are five tiers, each the best answer for its type of task and scale. Move to the next one only when the current tier breaks on a specific pain point. Context windows of all major models in 2026 have reached a million tokens and beyond — Gemini, Claude, Llama, GPT — and this shifts the threshold at which search infrastructure is even justified.

Tier 0: Everything Fits in Context — and That’s Great

Google NotebookLM lets you upload up to 50 sources and ask questions about them. Claude Projects from Anthropic is a feature where you add files to a “project” and the agent works with them in their entirety. Tens of millions of users. No RAG, no vector indexes. Just files in context. This isn’t an MVP — it’s a production architecture.

The Core Idea

All files are loaded entirely into the LLM’s context window. No search, no indexing. With 20 files of 200 lines each, that’s roughly 16,000 tokens — 1.6% of Claude’s window. As the Ahoi Kapptn team writes: “If your knowledge base is under 200K tokens (~500 pages), include it entirely in the prompt.”

Where this works perfectly: load 10 articles and ask questions — get synthesis with zero minutes of setup. A prototype with 5 files — the agent sees everything, accuracy is maximal. 15 infrastructure project configs — full context, zero latency. My AI course started exactly this way: two dozen files, everything fit in context, and the agent found what it needed instantly.

Example Structure

my-project/
  notes.md                 # notes, ideas, drafts
  data-analysis.py         # all code — 3-5 files
  config.yaml
  research-paper-1.pdf     # all sources right in the root
  research-paper-2.pdf

When to Move On

One day you notice the agent starting to “forget” information. Research from Stanford and UC Berkeley (Liu et al., 2023) demonstrated the lost-in-the-middle effect: accuracy drops by 30% or more when relevant information lands in the middle of the context. Another study found that the effective context of all models on complex tasks turned out to be far smaller than advertised. The boundary: roughly 20 files or 50,000 tokens. If you feel this pain — time for the next tier. If not — stay put, you’re in the right place.

Pattern Anti-pattern
All files in one folder, no nesting Setting up RAG for 5 documents
Maximally flat structure Dumping 100 files into context “just in case”
Zero infrastructure, zero setup Creating a folder hierarchy for 10 files

Tier 1: Text Search + CLAUDE.md — How Every AI Coding Agent Works

Cursor. Claude Code. Windsurf. None of them require developers to spin up a vector database. All use text search as their core infrastructure. As BuildMVPFast writes: “Text search has quietly become the load-bearing infrastructure for how AI writes code.”

The Core Idea

At this tier, the project has a CLAUDE.md (or AGENTS.md, .cursorrules) that explains the codebase structure and conventions to the agent. The agent reads CLAUDE.md and understands the lay of the land — which directories are responsible for what, what naming conventions are in use. When a task arrives, the agent searches by keywords, finds the right files, then reads them in full for complete context. The directory structure itself becomes a navigation map.

At Tier 0, the agent sees everything but doesn’t know what matters. CLAUDE.md provides priorities. Search lets the agent read only the files it needs rather than loading all 500 into context. AGENTS.md is already standardized by the Linux Foundation, supported by OpenAI, Anthropic, Google, AWS, and Bloomberg. Over 60,000 repositories include it. As HumanLayer notes: “A CLAUDE.md written in 30 minutes gives the agent 80% of the context it needs.” To get started — create a CLAUDE.md and describe the architecture, key conventions, and how to run and test the project.

Text search objectively outperforms semantic search for exact matches. As ast-grep notes: ERROR_4532 in vector space is indistinguishable from ERROR_4533 — yet these are completely different errors. My AI course moved to this tier when sources exceeded twenty — search over exported documents was fast and accurate.

Example Structure

my-repo/
  CLAUDE.md              # ← instructions for the agent: architecture, conventions
  AGENTS.md              # standardized rules (can be used instead of CLAUDE.md)
  src/                   # project code
  tests/                 # tests alongside the code
  docs/
    architecture.md      # keep documentation next to the code
    adr/
      001-use-postgres.md  # architectural decisions in ADR format

When to Move On

You have 300 code files and search works great. Then a task comes in: find all GDPR requirements across research notes, legal documents, and meeting transcripts. Searching for the word “GDPR” finds 5 out of 20 relevant documents — the rest talk about “personal data”, “privacy regulation”, “data processing”. This is the polysemy problem: one concept, dozens of names. You don’t need a better search engine — you need structured navigation. The boundary: roughly 500 files, predominantly code. For non-code knowledge — PDFs, regulations, research — this model doesn’t work.

Pattern Anti-pattern
CLAUDE.md with architecture and conventions Hoping the agent will “figure it out”
Consistent naming conventions Different styles in different parts of the project
AGENTS.md + separate .md files per subdirectory One giant 2,000-line CLAUDE.md
Text search for code and identifiers Text search for concepts in prose

Tier 2: Docs-as-Code — Structured Documentation for Teams

This tier is for projects where documentation is created by people for people, and the AI agent gets quality navigation for free. Stripe docs, Kubernetes (3,000+ pages), Django, Terraform — they serve millions of developers without RAG and have no plans to switch. As Mintlify notes: “At Stripe, a feature isn’t considered shipped until the documentation is written.”

The Core Idea

Documentation is organized by content type. The Diataxis framework divides it into 4 types — tutorials, how-to guides, reference, and explanation. When search finds the word “authentication” in 15 files, an agent without content typing has to read all 15. With Diataxis, it goes straight to how-to/configure-oauth.md. The framework is adopted by Cloudflare, Ubuntu, Django, and Gatsby.

The key advantage is a dual audience. A new team member reads the same documents as the AI agent. At Tier 3, the wiki is also human-readable but optimized for agent navigation. Here, there’s a single source of truth for both audiences. Plus, documentation gets indexed by search engines — a wiki behind an LLM or a RAG system is invisible to Google. To get started: sort your documents into the 4 Diataxis types and add a navigational index.md. One day for an average project.

Example Structure

docs/
  index.md                 # ← navigation hub, start here
  tutorials/
    getting-started.md     # learning material for newcomers
  how-to/
    configure-auth.md      # instructions: "how to do X"
  reference/
    api/                   # reference docs, often generated from code
  explanation/
    architecture.md        # explanations: "why we chose X"
  adr/
    001-use-postgres.md    # architectural decisions in ADR format

When to Move On

Maintenance cost — that’s what breaks this tier. At 200+ documents, classification becomes the bottleneck, and heterogeneous sources — scientific papers, transcripts, regulatory documents — don’t fit into neat templates.

Pattern Anti-pattern
Diataxis: 4 content types A flat docs/ folder with no typing
Build-time link validation Manually checking “did we break any links”
ADRs for architectural decisions Decisions in chat, lost within a month

Tier 3: The Karpathy Method — LLM as Librarian

According to ussumant/llm-wiki-compiler, 383 files became 13 articles — 81x compression. 130 meeting transcripts became a single 244-line digest — 503x compression. And this isn’t lossy summarization: the LLM finds connections between sources that a human would miss. As Karpathy wrote: “With ~100 articles and ~400K words, the LLM’s ability to navigate through summaries and index files is more than sufficient.”

The Core Idea

Three-layer architecture (Andrej Karpathy, April 2026): raw/ — immutable sources (PDFs, transcripts, notes), append-only, no editing; wiki/ — LLM-generated and LLM-maintained pages; index.md — a catalog of all wiki pages with one-line descriptions. The index is the search mechanism: the LLM scans it, finds the right page, reads it.

Three operations: Ingest — read a source, write a wiki page, update the index, update 10–15 related pages. Query — find an answer by scanning the index, save good answers as new pages. Lint — detect contradictions, orphaned pages, and outdated claims.

This is paradise for the solo researcher. One person plus one LLM replaces a documentation team. My AI course moved to this tier when sources reached the hundreds — a single maintainer manages the entire knowledge base through a wiki. Lint proactively detects outdated claims — unlike Tier 2 documentation, which goes stale silently. The entire “stack” is markdown in git. According to ussumant/llm-wiki-compiler, the agent starts a session with a compact index (~7.7K tokens) instead of hundreds of files (~47K) — an 84% reduction.

Karpathy’s gist garnered millions of views — it struck a nerve. Full implementations have already appeared: ussumant/llm-wiki-compiler (Claude Code plugin), atomicmemory/llm-wiki-compiler (TypeScript, concept extraction), xoai/sage-wiki (Go, hybrid text + vector search). As MindStudio notes: “If your knowledge base is under 50,000–100,000 tokens, there’s no technical reason to use RAG.”

If you need semantic search over heterogeneous sources but without wiki compilation, you can simply load documents into a local RAG system and get meaning-based search in a single evening. To start with a wiki: create raw/ and wiki/, add a CLAUDE.md with conventions from Karpathy’s gist. Ingest 10–20 documents per session — the wiki grows organically.

Example Structure

knowledge-base/
  CLAUDE.md                # ← schema and conventions from Karpathy's gist
  index.md                 # catalog: one line per wiki page
  log.md                   # operations log (append-only)
  raw/                     # immutable sources
    paper-attention-2017.pdf
    meeting-2026-03-15.txt
    regulation-gdpr.md
  wiki/                    # LLM-generated pages (flat structure)
    transformer-architectures.md
    gdpr-compliance.md     # ← the LLM found a connection to three sources
    team-decisions-q1.md
    # wiki is flat: LLM navigates via index.md, no subdirectories needed

When to Move On

You’re running a research project: 200 papers, 50 meeting transcripts, 30 regulatory documents. The wiki handles it beautifully. Then a request comes in: “find everything related to model fairness evaluation.” But in wiki pages, this topic is called “fairness metrics”; in source files, “bias evaluation”; in regulatory documents, “equity assessment.” The index is a precision tool: it finds what’s listed. Semantic discovery is not its job. At 500+ sources, the index itself exceeds 50,000 tokens and no longer fits in context.

Pattern Anti-pattern
raw/ append-only, wiki/ maintained by LLM Editing the wiki by hand (breaks on recompilation)
One index.md with one-line descriptions Nested indexes “for the future” with fewer than 100 pages
Incremental compilation Full recompilation of 500 sources every time
Lint after every Ingest Accumulating 100 sources and compiling them all at once

Tier 4: When the Index Doesn’t Fit in Context — Add Semantics

In my AI course, the Karpathy-method wiki delivered a 7.6x reduction in tool calls and 9 out of 9 on completeness scores. But when I needed to find “everything about AI agents” across Russian-language documents, the wiki index didn’t help. The topic appeared under five different names in fifteen different places. Only semantic search found what text search and the index missed.

The Core Idea

At this tier, the wiki (Tier 3) is supplemented with one or two layers. RAG (vector search) — semantic search via embeddings, finds “equity measures” when you search for “fairness metrics.” Knowledge graph (ontology) — structured relationships between entities: “paper X cites method Y, applied in domain Z.” The wiki remains the foundation — readable, navigable, in git. RAG and the graph are additional search layers on top, with results combined via Reciprocal Rank Fusion.

The cost isn’t necessarily high. In my course, I use local free tools: Oxigraph (an RDF store for the knowledge graph), mcp-local-rag (local semantic search with no external services) — everything lives in a single git repository, infrastructure cost is zero. For larger-scale tasks, LazyGraphRAG from Microsoft promises order-of-magnitude reductions in indexing costs. LightRAG delivers 70–90% of the quality at a hundredth of the cost.

Research library — the wiki compiles literature reviews, RAG finds papers by meaning, the graph tracks citation chains. Agent knowledge base — in my course: wiki for navigation, RAG for bilingual search (Russian and English), ontology on Oxigraph for traceability: “requirement -> lecture -> seminar -> assessment.” Team knowledge base — three years of accumulated experience: meeting transcripts, project documents, post-mortems; the wiki provides topic overviews, RAG finds “that time we already solved a similar problem.” Start with RAG on top of an existing wiki — one evening. Add the graph only when specific relational queries appear.

Example Structure

knowledge-base/
  CLAUDE.md
  index.md                 # wiki index (Tier 3)
  raw/                     # sources
    papers/
      by-topic/            # grouped by topic for convenience
    meeting-notes/
    regulations/
  wiki/                    # LLM-compiled pages
  index/                   # ← RAG index, add this first
  ontology/                # knowledge graph, add when you need relationships
    schema.ttl             # classes and properties (I use Oxigraph)
    store.ttl              # data
    queries/               # SPARQL queries for common questions

When You Need This

You need RAG when You need a knowledge graph when
Bilingual search (RU and EN) Multi-hop queries (“papers by author X -> method Y -> domain Z”)
“Find something similar” (fuzzy discovery) Traceability (requirement -> test -> coverage)
Wiki index exceeds 50,000 tokens Aggregation (“all papers with no citations”)
Heterogeneous sources Taxonomies and classifications
Pattern Anti-pattern
Wiki as foundation + RAG/graph as layers RAG instead of wiki (you lose navigation)
Local free tools (Oxigraph, local-rag) Paying $200/mo for a vector DB to index 100 documents
Adding layers one at a time Building the entire infrastructure upfront “for growth”
Graph for specific relational queries Graph “because it looks cool” with no clear use cases

How I Walked This Path

My AI course — hundreds of sources, dozens of artifacts, one maintainer.

I started at Tier 0: two dozen files, everything in context. Quickly outgrew it into Tier 1: search over exported documents. Tried RAG — got 10% precision on Russian-language queries. Tried an ontology — a beautiful schema, zero data.

I implemented Tier 3 — the Karpathy-method wiki: 7.6x reduction in tool calls, 9 out of 9 on completeness across test scenarios. Added RAG for semantic search on bilingual queries — but only after the wiki was working.

The key lesson: I tried to jump from Tier 1 to Tier 4 — and got beautifully empty infrastructure. Only when I went back to Tier 3 as the foundation and layered search on top did the system start working.

How to Determine the Right Structure

The entire selection framework boils down to two questions:

  1. How many sources do you have? (fewer than 20 / 20 to 500 / more than 500)
  2. What is it — code or documentation? (code / documentation for people / research, papers, heterogeneous sources)
Scale \ Content Code Documentation for people Research, heterogeneous
Fewer than 20 files Tier 0 Tier 0 Tier 0
20–500 Tier 1 (search + CLAUDE.md) Tier 2 (docs-as-code) Tier 3 (LLM wiki)
More than 500 Tier 1 + indexed search Tier 2 (scales to 3,000+) Tier 3 + 4 (RAG/graph)

Hybrid situations are the norm. “200 code files + 50 research papers” means code at Tier 1 (search + CLAUDE.md), papers at Tier 3 (wiki). Tiers aren’t mutually exclusive — they’re about content type.

Most of You Are at Tier 1. And That’s Fine

Entrepreneur Vamshi Reddy wrote to Karpathy: “Every business has a raw/ directory. Nobody has compiled it yet. There’s the product.”

I myself spent a sprint on a four-layer system with an ontology and SPARQL queries. Beautiful architecture. Graphs, relationships, validation. Then I opened the knowledge graph and discovered it was empty. Zero data. Right next to it sat a 40-line CLAUDE.md through which the agent had already been finding everything it needed for a week.

The right answer depends on the task. Tier 0 remains the best for small projects — NotebookLM serves millions of users without a single vector index. Tier 1 is for code. Stripe isn’t switching to RAG for their documentation, and they see no reason to. The Karpathy-method wiki is for researchers with hundreds of heterogeneous sources. And hybrid Tier 4 is justified where the cost of unfound information is measured in lost revenue or patients.

Each tier is not a step on a ladder but the right tool for its scale. A simple rule: if you’re not experiencing a specific pain point at your current tier — you’re in the right place.

Как организовать репозиторий для LLM-агента

Чем сложнее, тем лучше? Не думаю. Пять уровней организации репозитория:

  • Уровень 0 — плоские файлы. Всё в контексте. Прототипы, конфиги, малые проекты до 20 файлов.
  • Уровень 1 — текстовый поиск + CLAUDE.md. Так работают все AI-кодинг-агенты. Кодовые проекты до 500 файлов.
  • Уровень 2 — docs-as-code. Структурированная документация для команд. Stripe, Kubernetes, Django — без RAG.
  • Уровень 3 — LLM-вики по методу Карпати. LLM компилирует вики из сырых источников. Сотни документов.
  • Уровень 4 — вики + RAG + граф знаний. Семантический поиск и связи. 500+ источников.

Не переходите на следующий, если хватает текущего.

LLM-агенты сегодня решают радикально разные задачи. Один агент пишет код в репозитории на десять тысяч файлов. Другой исследует пятьсот научных публикаций. Третий поддерживает документацию для двухсот человек. Применять один и тот же подход к организации знаний для всех этих задач — это слишком. Я прошёл все пять уровней на собственном проекте — учебном курсе по AI с сотнями источников, десятками артефактов и одним автором — и дальше расскажу, что работает на каком масштабе.

В 2024–2025 годах, пока индустрия строила сложные RAG-пайплайны и графы знаний, Cursor взлетел до $100M ARR с подходом, в основе которого — индекс эмбеддингов и текстовый поиск по коду. Не потому что текстовый поиск лучше RAG. А потому что для кода это правильный инструмент. Именно для кода.

В мире организации знаний для агентов люди совершают две симметричные ошибки. Одни недоинвестируют: 500 документов и текстовый поиск — хаос, ничего не находится. Другие переинвестируют: как описал Пол Хоук, разработчик удалил 2000 строк RAG-кода, и точность подскочила до 94%.

Нет «лучшего» способа организовать знания для LLM-агента. Есть пять уровней, каждый из которых — лучший ответ для своего типа задачи и масштаба. Переходить на следующий стоит только когда текущий ломается на конкретной болевой точке. Контекстные окна всех основных моделей в 2026 году достигли миллиона токенов и больше — Gemini, Claude, Llama, GPT — и это сдвигает порог, на котором инфраструктура поиска вообще оправдана.

Уровень 0: Всё помещается в контекст — и это прекрасно

Google NotebookLM позволяет загрузить до 50 источников и задавать вопросы по ним. Claude Projects от Anthropic — функция, где вы добавляете файлы в «проект» и агент работает с ними целиком. Десятки миллионов пользователей. Никакого RAG, никаких векторных индексов. Просто файлы в контексте. Это не MVP — это рабочая архитектура.

Суть подхода

Все файлы целиком загружаются в контекстное окно LLM. Никакого поиска, никакой индексации. При 20 файлах по 200 строк это около 16 тысяч токенов — 1.6% окна Claude. Как пишет команда Ahoi Kapptn: «Если ваша база знаний меньше 200 тысяч токенов (около 500 страниц), включите её целиком в промпт».

Где это работает идеально: загрузили 10 статей — задавайте вопросы, получайте синтез за ноль минут настройки. Прототип на 5 файлов — агент видит всё, точность максимальна. 15 конфигов инфраструктурного проекта — полный контекст, нулевая задержка. Мой курс по AI начинался именно так: два десятка файлов, всё помещалось в контекст, и агент находил нужное мгновенно.

Пример структуры

my-project/
  notes.md                 # заметки, идеи, черновики
  data-analysis.py         # весь код — 3-5 файлов
  config.yaml
  research-paper-1.pdf     # все источники прямо в корне
  research-paper-2.pdf

Когда переезжать

Однажды вы замечаете, что агент начинает «забывать» информацию. Исследование Stanford и UC Berkeley (Liu et al., 2023) показало эффект «потери в середине»: точность падает на 30% и больше, когда нужная информация оказывается в середине контекста. Другая работа зафиксировала, что эффективный контекст всех моделей на сложных задачах оказался гораздо меньше рекламируемого. Граница: примерно 20 файлов или 50 тысяч токенов. Если чувствуете эту боль — пора на следующий уровень. Если нет — оставайтесь, вы на правильном месте.

Паттерн Антипаттерн
Все файлы в одной папке, без вложенности Настраивать RAG для 5 документов
Максимально плоская структура Складывать 100 файлов в контекст «про запас»
Ноль инфраструктуры, ноль настройки Создавать иерархию папок для 10 файлов

Уровень 1: Текстовый поиск + CLAUDE.md — так работают все AI-кодинг-агенты

Cursor. Claude Code. Windsurf. Ни один из них не требует от разработчика поднимать векторную базу данных. Все используют текстовый поиск как основную инфраструктуру. Как пишет BuildMVPFast: «Текстовый поиск тихо стал несущей инфраструктурой для того, как AI пишет код».

Суть подхода

На этом уровне проект имеет CLAUDE.md (или AGENTS.md, .cursorrules), который объясняет агенту структуру и конвенции кодовой базы. Агент читает CLAUDE.md и понимает, где что лежит — какие директории за что отвечают, какие конвенции именования используются. Когда приходит задача, агент ищет по ключевым словам, находит подходящие файлы, а затем зачитывает их целиком, чтобы получить полный контекст. Структура директорий сама по себе становится навигационной картой.

На уровне 0 агент видит всё — но не знает, что важно. CLAUDE.md даёт приоритеты. Поиск позволяет агенту читать только нужные файлы, а не загружать все 500 в контекст. AGENTS.md уже стандартизирован Linux Foundation, поддерживается OpenAI, Anthropic, Google, AWS, Bloomberg. Более 60 тысяч репозиториев включают его. Как отмечает HumanLayer: «CLAUDE.md за 30 минут даёт агенту 80% нужного контекста». Чтобы начать — создайте CLAUDE.md и опишите архитектуру, ключевые конвенции, как запустить и протестировать проект.

Текстовый поиск объективно превосходит семантический для точных совпадений. Как отмечает ast-grep: ERROR_4532 в векторном пространстве неотличим от ERROR_4533 — а это совершенно разные ошибки. Мой курс по AI перешёл на этот уровень, когда источников стало больше двадцати — поиск по экспортированным документам работал быстро и точно.

Пример структуры

my-repo/
  CLAUDE.md              # ← инструкции агенту: архитектура, конвенции
  AGENTS.md              # стандартизованные правила (можно вместо CLAUDE.md)
  src/                   # код проекта
  tests/                 # тесты рядом с кодом
  docs/
    architecture.md      # держите документацию рядом с кодом
    adr/
      001-use-postgres.md  # архитектурные решения в формате ADR

Когда переезжать

У вас 300 файлов кода и поиск работает отлично. Потом приходит задача: найти все требования GDPR в исследовательских заметках, юридических документах и протоколах встреч. Поиск по слову «GDPR» находит 5 из 20 релевантных документов — остальные говорят о «персональных данных», «privacy regulation», «обработке ПДн». Это проблема полисемии: одно понятие, десятки названий. Вам нужна не лучшая поисковая система, а структурированная навигация. Граница: примерно 500 файлов, преимущественно код. Для не-кодовых знаний — PDF, нормативные документы, исследования — эта модель не работает.

Паттерн Антипаттерн
CLAUDE.md с архитектурой и конвенциями Надеяться, что агент «сам разберётся»
Единообразные правила именования Разные стили в разных частях проекта
AGENTS.md + отдельные .md по поддиректориям Один гигантский CLAUDE.md на 2000 строк
Текстовый поиск для кода и идентификаторов Текстовый поиск для концепций в прозе

Уровень 2: Docs-as-code — структурированная документация для команд

Этот уровень — для проектов, где документация создаётся людьми для людей, а AI-агент получает качественную навигацию бесплатно. Stripe docs, Kubernetes (3000+ страниц), Django, Terraform — обслуживают миллионы разработчиков без RAG и не собираются переходить. Как отмечает Mintlify: «В Stripe фича не считается выпущенной, пока не написана документация».

Суть подхода

Документация организована по типу контента. Фреймворк Diátaxis делит её на 4 типа — обучение, инструкции, справочник, объяснение. Когда поиск находит слово «authentication» в 15 файлах, агент без типизации вынужден читать все 15. С Diátaxis — сразу идёт в how-to/configure-oauth.md. Фреймворк принят Cloudflare, Ubuntu, Django, Gatsby.

Главное преимущество — двойная аудитория. Новый член команды читает те же документы, что и AI-агент. На уровне 3 вики тоже читаема, но оптимизирована под навигацию агента. Здесь — один источник правды для обеих аудиторий. Плюс документация индексируется поисковиками — вики за LLM или RAG-система для Google невидимы. Чтобы начать: рассортируйте документы по 4 типам Diátaxis, добавьте навигационный index.md. Один день для среднего проекта.

Пример структуры

docs/
  index.md                 # ← навигационный хаб, начните здесь
  tutorials/
    getting-started.md     # обучение для новичков
  how-to/
    configure-auth.md      # инструкции: «как сделать X»
  reference/
    api/                   # справочник, часто генерируется из кода
  explanation/
    architecture.md        # объяснения: «почему мы выбрали X»
  adr/
    001-use-postgres.md    # архитектурные решения в формате ADR

Когда переезжать

Стоимость поддержания — вот что ломает этот уровень. При 200+ документах классификация становится узким местом, а разнородные источники — научные публикации, транскрипты, нормативные документы — не укладываются в аккуратные шаблоны.

Паттерн Антипаттерн
Diátaxis: 4 типа контента Плоская папка docs/ без типизации
Валидация ссылок при сборке Ручная проверка «не сломали ли ссылки»
ADR для архитектурных решений Решения в чатах, потерянные через месяц

Уровень 3: Метод Карпати — LLM как библиотекарь

По данным ussumant/llm-wiki-compiler, 383 файла превратились в 13 статей — 81-кратная компрессия. 130 транскриптов совещаний стали одним дайджестом на 244 строки — 503-кратное сжатие. И это не выжимка с потерями: LLM находит связи между источниками, которые человек бы пропустил. Как написал Карпати: «При ~100 статьях и ~400K слов способности LLM навигировать через саммари и индексные файлы более чем достаточно».

Суть подхода

Трёхслойная архитектура (Andrej Karpathy, апрель 2026): raw/ — неизменяемые источники (PDF, транскрипты, заметки), только добавление, без редактирования; wiki/ — LLM-сгенерированные и LLM-поддерживаемые страницы; index.md — каталог всех вики-страниц с однострочными описаниями. Индекс — это и есть механизм поиска: LLM сканирует его, находит нужную страницу, читает.

Три операции: Ingest — прочитать источник, написать вики-страницу, обновить индекс, обновить 10–15 связанных страниц. Query — найти ответ через сканирование индекса, сохранить хорошие ответы как новые страницы. Lint — обнаружить противоречия, осиротевшие страницы, устаревшие утверждения.

Это рай для соло-исследователя. Один человек плюс один LLM заменяют документационную команду. Мой курс по AI перешёл на этот уровень, когда источников стало сотни — один мейнтейнер управляет всей базой знаний через вики. Lint обнаруживает устаревшие утверждения проактивно — в отличие от документации уровня 2, которая устаревает молча. Весь «стек» — markdown в git. По данным ussumant/llm-wiki-compiler, агент начинает сессию с компактного индекса (~7.7K токенов) вместо сотен файлов (~47K) — сокращение на 84%.

Гист Карпати набрал миллионы просмотров — он попал в нерв. Уже появились полноценные реализации: ussumant/llm-wiki-compiler (плагин для Claude Code), atomicmemory/llm-wiki-compiler (TypeScript, извлечение концепций), xoai/sage-wiki (Go, гибридный текстовый + векторный поиск). Как отмечает MindStudio: «Если ваша база знаний меньше 50–100 тысяч токенов, нет технической причины использовать RAG».

Если вам нужен семантический поиск по разнородным источникам, но без вики-компиляции — можно просто загрузить документы в локальный RAG и получить поиск по смыслу за один вечер. Чтобы начать с вики: создайте raw/ и wiki/, добавьте CLAUDE.md с конвенциями из гиста Карпати. Загружайте по 10–20 документов за сессию — вики растёт органически.

Пример структуры

knowledge-base/
  CLAUDE.md                # ← схема и конвенции из гиста Карпати
  index.md                 # каталог: одна строка — одна вики-страница
  log.md                   # журнал операций (только дополнение)
  raw/                     # неизменяемые источники
    paper-attention-2017.pdf
    meeting-2026-03-15.txt
    regulation-gdpr.md
  wiki/                    # LLM-сгенерированные страницы (плоская структура)
    transformer-architectures.md
    gdpr-compliance.md     # ← LLM нашёл связь с тремя источниками
    team-decisions-q1.md
    # вики плоская: LLM навигирует через index.md, подпапки не нужны

Когда переезжать

Вы ведёте исследовательский проект: 200 публикаций, 50 протоколов встреч, 30 нормативных документов. Вики отлично справляется. Потом приходит запрос: «найди всё связанное с оценкой справедливости моделей». Но в вики-страницах эта тема называется «метрики справедливости», в исходниках — «bias evaluation», в нормативных документах — «оценка корректности». Индекс — точный инструмент: он находит то, что перечислено. Семантическое обнаружение — не его задача. При 500+ источниках сам индекс превышает 50 тысяч токенов и перестаёт помещаться в контекст.

Паттерн Антипаттерн
raw/ только дополнение, wiki/ поддерживается LLM Редактировать вики руками (сломается при перекомпиляции)
Один index.md с однострочными описаниями Вложенные индексы «на будущее» при менее 100 страниц
Инкрементальная компиляция Полная перекомпиляция 500 источников каждый раз
Lint после каждого Ingest Копить 100 источников и потом компилировать разом

Уровень 4: Когда индекс не помещается в контекст — добавляем семантику

В моём курсе по AI вики по методу Карпати дала 7.6-кратное сокращение обращений к инструментам и 9 из 9 по полноте ответов. Но когда понадобилось найти «всё про AI-агентов» по русскоязычным документам — вики-индекс не помог. Тема упоминалась под пятью разными названиями в пятнадцати разных местах. Только семантический поиск нашёл то, что текстовый поиск и индекс пропустили.

Суть подхода

На этом уровне вики (уровень 3) дополняется одним или двумя слоями. RAG (векторный поиск) — семантический поиск по векторным представлениям, находит «equity measures» когда ищешь «метрики справедливости». Граф знаний (онтология) — структурированные связи между сущностями: «статья X цитирует метод Y, применённый в домене Z». Вики остаётся основой — читаемой, навигируемой, в git. RAG и граф — дополнительные слои поиска поверх неё, результаты объединяются через Reciprocal Rank Fusion.

Стоимость не обязательно высокая. В моём курсе я использую локальные бесплатные инструменты: Oxigraph (RDF-хранилище для графа знаний), mcp-local-rag (локальный семантический поиск без внешних сервисов) — всё живёт в одном git-репозитории, стоимость инфраструктуры равна нулю. Для более масштабных задач LazyGraphRAG от Microsoft обещает снижение стоимости индексации на порядки. LightRAG даёт 70–90% качества за сотую долю цены.

Научная библиотека — вики компилирует литературные обзоры, RAG находит публикации по смыслу, граф отслеживает цепочки цитирования. Агентская база знаний — в моём курсе: вики для навигации, RAG для двуязычного поиска (русский и английский), онтология на Oxigraph для трассировки «требование → лекция → семинар → оценка». Командная база знаний — три года накопленного опыта: протоколы встреч, проектные документы, пост-мортемы; вики даёт обзоры по темам, RAG находит «тот случай, когда мы уже решали похожую проблему». Начните с RAG поверх существующей вики — один вечер. Граф добавляйте только когда появятся конкретные запросы на связи.

Пример структуры

knowledge-base/
  CLAUDE.md
  index.md                 # вики-индекс (уровень 3)
  raw/                     # источники
    papers/
      by-topic/            # группировка по темам для удобства
    meeting-notes/
    regulations/
  wiki/                    # LLM-компилированные страницы
  index/                   # ← RAG-индекс, добавьте первым
  ontology/                # граф знаний, добавьте когда нужны связи
    schema.ttl             # классы и свойства (я использую Oxigraph)
    store.ttl              # данные
    queries/               # SPARQL-запросы для типовых вопросов

Когда это нужно

Нужен RAG когда Нужен граф знаний когда
Двуязычный поиск (RU и EN) Многошаговые запросы («публикации автора X → метод Y → домен Z»)
«Найди похожее» (нечёткое обнаружение) Трассировка (требование → тест → покрытие)
Индекс вики больше 50 тысяч токенов Агрегация («все публикации без цитирований»)
Разнородные источники Таксономии и классификации
Паттерн Антипаттерн
Вики как основа + RAG/граф как слои RAG вместо вики (теряете навигацию)
Локальные бесплатные инструменты (Oxigraph, local-rag) Платная векторная БД за $200/мес для 100 документов
Добавлять слои по одному Строить всю инфраструктуру сразу «на вырост»
Граф для конкретных запросов на связи Граф «потому что красиво» без чётких задач

Как я прошёл этот путь

Мой курс по AI — сотни источников, десятки артефактов, один мейнтейнер.

Начинал с уровня 0: два десятка файлов, всё в контексте. Быстро перерос в уровень 1: поиск по экспортированным документам. Попробовал RAG — получил 10% точности на русскоязычных запросах. Попробовал онтологию — красивая схема, ноль данных.

Реализовал уровень 3 — вики по методу Карпати: 7.6-кратное сокращение обращений к инструментам, 9 из 9 по полноте на тестовых сценариях. Добавил RAG для семантического поиска по двуязычным запросам — но только после того, как вики заработала.

Ключевой урок: я попробовал перепрыгнуть с уровня 1 на уровень 4 — и получил красивую пустую инфраструктуру. Только когда вернулся к уровню 3 как базе и добавил слои поиска сверху — система заработала.

Как определить нужную структуру

Весь фреймворк выбора сводится к двум вопросам:

  1. Сколько у вас источников? (менее 20 / от 20 до 500 / более 500)
  2. Что это — код или документация? (код / документация для людей / исследования, публикации, разнородные источники)
Масштаб \ Контент Код Документация для людей Исследования, разнородные
Менее 20 файлов Уровень 0 Уровень 0 Уровень 0
20–500 Уровень 1 (поиск + CLAUDE.md) Уровень 2 (docs-as-code) Уровень 3 (LLM-вики)
Более 500 Уровень 1 + индексированный поиск Уровень 2 (до 3000+) Уровень 3 + 4 (RAG/граф)

Гибридные ситуации — норма. «200 файлов кода + 50 научных публикаций» — код на уровне 1 (поиск + CLAUDE.md), публикации на уровне 3 (вики). Уровни не монопольны, они про тип контента.

Большинство из вас на уровне 1. И это нормально

Предприниматель Вамши Редди написал Карпати: «У каждого бизнеса есть директория raw/. Никто её ещё не скомпилировал. Вот и продукт».

Я сам потратил спринт на четырёхслойную систему с онтологией и SPARQL-запросами. Красивая архитектура. Графы, связи, валидация. А потом открыл граф знаний и обнаружил, что он пуст. Ноль данных. Рядом лежал CLAUDE.md на 40 строк, через который агент уже неделю находил всё нужное.

Правильный ответ зависит от задачи. Уровень 0 пока остаётся лучшим для малых проектов — NotebookLM обслуживает миллионы пользователей без единого векторного индекса. Уровень 1 — для кода. Stripe пока не переходит на RAG для своей документации, и пока не видит причин. Вики по методу Карпати — для исследователей с сотнями разнородных источников. А гибридный уровень 4 оправдан там, где стоимость ненайденной информации измеряется в потерянных деньгах или пациентах.

Каждый уровень — не ступенька лестницы, а правильный инструмент для своего масштаба. Простое правило: если не испытываете конкретную боль текущего уровня — вы на правильном месте.