Atlas
magidbugazia/atlas
Transforma pesquisa espalhada em wiki estruturada e consultável
Ver no GitHubSkill para Claude que transforma material de pesquisa disperso em uma wiki estruturada e interconectada, mantida por IA. Implementa o fluxo de Karpathy (ingest → compile → query → lint) com indexação hierárquica, registro de aliases, verificação de fontes e controle de versão automático via git.
Instalação
npx convez-ai magidbugazia/atlas1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consolidar notas de pesquisa em base de conhecimento interconectada
- Manter wiki técnica ou conceitual que cresce organicamente
- Detectar contradições entre fontes e verificar citações automaticamente
Veredito

Atlas é uma implementação sólida do workflow de base de conhecimento LLM, com engenharia real para crescimento escalável (indexação 2-tier, deduplicação, verificação de fontes). Excelente para pesquisadores que precisam compilar conhecimento distribuído em artefatos consultáveis; requer familiaridade com CLI e pensamento estruturado.
README
A tradução para o português deste README ainda está na fila.
Atlas
A Claude Code skill that turns scattered research material into a structured, interconnected wiki maintained by an LLM. Based on Andrej Karpathy's LLM Knowledge Bases workflow (April 2, 2026), which describes the ingest → compile → query → lint loop that Atlas implements as a skill.
You collect raw sources. Atlas organizes them into concept pages with summaries, cross-links, and a two-tier hierarchical index. You query it, and the LLM researches answers from the wiki and writes them as files that feed back into the knowledge base. The knowledge compounds over time.
What Atlas adds beyond the original workflow. Karpathy describes the shape of the loop (ingest → compile → query → lint). Atlas is the implementation that handles the engineering problems a real knowledge base hits as it grows: two-tier hierarchical indexing that prevents context rot past ~150 concepts, an alias registry that stops duplicate pages, a Source Verifier that audits wiki claims against their raw sources, scale-adaptive query routing, git-backed auto-commits on every operation, and a clean split with the companion Mentor skill so external curation (what belongs) and internal organization (where it goes) are separate concerns.
Quick Start
/atlas init "my research topic" # Create KB structure
/atlas ingest <URL or file> # Add a source
/atlas compile # Build the wiki
/atlas query "your question" # Research against the wiki
/atlas lint # Health check with fix suggestions
Your wiki lives in wiki/. Entry point: wiki/INDEX.md. Concept pages: wiki/concepts/. The LLM maintains everything — you rarely edit directly. Git auto-commits on every operation, so rollback is cheap.
The Mental Model (read this once, confusion ends)
Atlas manages two kinds of pages, and only one of them ever asks anything of you.
Concept pages (wiki/concepts/, one file per idea) are the knowledge. Each carries a status in its frontmatter:
draft— compile created it, you haven't personally read it. Purely informational. Ignorable forever.reviewed— signed off.review_pending— the only actionable flag in the entire skill. Compile sets it when a newly ingested source contradicts what a page already says, or materially shifts its framing. It means "two of your sources disagree; the synthesis needs a check."
That one flag has one producer, one resolver, and three announcers:
compile ──sets──▶ review_pending ──cleared by──▶ /atlas verify pending
│ ▲
└── compile's output, /atlas status, and lint's ────────┘
Review Queue all print this exact command when the queue is non-empty
Verify spawns agents that spot-check each flagged page's claims against the raw sources: clean pages auto-clear, small drifts become corrections you approve, real problems stay flagged with the failing claim quoted. You never have to remember the command — every surface that can see the queue prints it.
Reports (wiki/reports/, one file per question you asked /atlas query) are dated snapshots: cached answers computed from the concept pages at one point in time. They have no lifecycle. Nothing flags them, nothing needs clearing. When the wiki grows past a report (a cited concept's last_updated becomes newer than the report's), that's not a defect, just age. Lint's Stale-by-Content section lists aged reports, each with a ready-to-paste Refresh: command quoting the report's exact title — pasting it re-runs the same report in place (title match reuses the slug; no duplicate is created). Refresh a report when you actually want it current, never as a chore.
Command tiers — nine commands sounds like a lot until you see how rarely most run:
| Tier | Commands | Cadence |
|---|---|---|
| Daily loop | ingest, compile, query | This is the skill. Everything else is upkeep around it. |
| When prompted | verify pending | Only when compile/status/lint tell you the review queue is non-empty (rare: requires sources that genuinely contradict) |
| Occasional | lint, status | Checkup and dashboard. Lint every handful of compiles (compile reminds you); status whenever curious |
| Rare | search, export, init | Quick lookup, HTML rendering, one-time setup |
The whole system in three sentences: compile builds the wiki and flags real contradictions; verify clears them; reports are dated answers you re-ask when you care. Every command that discovers work prints the exact command that does the work.
Commands
See SKILL.md for full operational details.
| Command | What it does | Reads | Creates / Updates |
|---|---|---|---|
init <subject> | Scaffold a new KB | nothing | KB.md, .atlas/*, raw/ dirs, wiki/INDEX.md |
ingest <source> | Add a file, URL, or directory to raw | source file/URL | raw/[type]/, KB.md (hashes are written only by compile, after a source is actually processed) |
compile | Full rebuild of wiki from all raw material | raw/*, .atlas/* | wiki/concepts/, wiki/summaries/, wiki/indexes/, wiki/INDEX.md, .atlas/concepts.json, KB.md |
compile --incremental | Rebuild only new/changed sources | raw/*, .atlas/hashes.json | same as compile, only changed files |
query "question" | Research answer from wiki | wiki/INDEX.md, wiki/indexes/, wiki/concepts/ | wiki/reports/ |
search "term" | Full-text search with alias expansion | .atlas/concepts.json, wiki/concepts/, wiki/reports/ | nothing (display only) |
lint | Health check and hallucination audit | all wiki/ files, raw/, .atlas/concepts.json | wiki/lint/lint-YYYY-MM-DD.md, structural fixes if approved, KB.md |
verify [pending | <slug>] | Spot-check flagged concept pages against raw sources; auto-clear clean ones | flagged wiki/concepts/ pages, cited raw/ files | concept frontmatter (status, revision_note), approved corrections |
status | Quick stats | KB.md, .atlas/*, wiki/INDEX.md | nothing (display only) |
export <report-slug> | Render an existing report as an interactive HTML guide via code-fluent | wiki/reports/<slug>.md, KB.md | wiki/reports/<slug>-guide.html |
The Problem It Solves
You research a topic deeply. You read 50 articles, 20 papers, browse 10 repos. The knowledge ends up scattered across browser tabs, PDFs in Downloads, and your unreliable memory. Or you write everything into one massive file that becomes unnavigable past 2000 lines.
Atlas solves both. Raw material goes into one directory. The LLM compiles it into a structured, navigable, queryable wiki. The LLM maintains the wiki. You rarely edit it directly.
Why Not Just Obsidian or Notion?
Those are editing tools — you write, they store. Atlas is automation on top of markdown: the LLM does the writing, you curate what goes in. Atlas plays nicely with Obsidian as a frontend (Karpathy uses it that way) — it just replaces the "manually organize my notes" step with "the LLM compiles them."
Compared to RAG frameworks (LangChain, LlamaIndex): Atlas stays local, produces plain markdown you can read and grep, and keeps you portable. No vector store, no vendor lock-in. If Claude goes away tomorrow, you still have the .md files.
Key Design Decisions
One file per concept, not per source. If three articles discuss "prompt engineering," they become ONE concept page that synthesizes all three. Knowledge converges into concepts, not sources.
Two-tier hierarchical indexing. INDEX.md lists categories (kept under 60 lines). Each category has its own sub-index in wiki/indexes/ with detailed concept summaries. The LLM never reads more than ~30 summaries at once, even at 500+ concepts. At small scale (under 15 concepts), a single sub-index is used.
Scale-adaptive query. Small wikis: direct concept reads. Medium wikis: single research agent. Large wikis (150+ concepts): parallel agents per category, each scoped to its own sub-index. Prevents context rot at any scale.
Dual indexing: navigation vs. lookup. INDEX.md is the human-readable table of contents, organized by category for browsing in Obsidian. .atlas/concepts.json is the machine-parseable registry mapping every concept slug to its display name and aliases. They can't be collapsed into one: INDEX.md is organized by theme (useless for answering "does a page for RAG already exist?"), and concepts.json is a flat key-value map (useless for browsing). During compile, agents check concepts.json to avoid creating duplicate pages. During search and query, it expands aliases. INDEX.md handles everything else.
Alias-aware search. The concept registry (.atlas/concepts.json) maps every concept to its canonical name and known aliases. Searching for "RAG" finds "Retrieval-Augmented Generation." Used by query, search, and export.
Source traceability. Every claim in the wiki cites the raw source it came from. Lint includes a Source Verifier agent that spot-checks claims against cited sources to catch hallucinations introduced during compilation.
Git-backed operations. Every compile, query filing, and lint fix auto-commits if the knowledge base is in a git repo. Rollback, history, and diffable changes.
Outputs as files, not chat. Answers get written as markdown files in the wiki. You can file them back in to enrich future queries. Each question makes the wiki more complete.
Directory Structure
After init, ingest, and compile, your repo looks like this:
./
├── KB.md # KB metadata (subject, scope, compile stats)
├── .atlas/ # Internal machinery (gitignored, regenerable via compile)
│ ├── hashes.json # SHA-256 per raw file — incremental compile change detection
│ ├── concepts.json # Slug/name/alias registry — dedup, alias search, compile coordination
│ └── splits/ # Temp working copies when large files get split for compile
├── raw/ # Append-only archive of source material
│ ├── articles/ # .md files (ingested articles, guides)
│ ├── papers/ # .pdf files
│ ├── repos/ # Code files (.py, .js, .ts)
│ ├── datasets/ # .csv, .parquet, .jsonl, .xlsx
│ ├── images/ # .png, .jpg, .svg
│ └── notes/ # Everything else
└── wiki/ # Compiled output — the part you read
├── INDEX.md # Entry point. Lists categories, links to sub-indexes. Under 60 lines.
├── indexes/ # Navigation — answers "what concepts exist in category Y?"
├── concepts/ # Knowledge — answers "what is X?" One file per concept.
├── summaries/ # Provenance — answers "what did source Z contribute?"
├── reports/ # Query answers plus rendered HTML guides from export.
└── lint/ # Saved lint reports with actionable follow-up commands.
Navigation flow: INDEX.md → indexes/[category].md → concepts/[topic].md → cross-links to related concepts. summaries/ is the reverse lookup: raw source → which concepts it contributed to.
.atlas/ vs wiki/: .atlas/ is machine state (hashes, registry, temp splits). wiki/ is the human-readable output. The naming overlap between concepts.json (lookup table) and concepts/ (wiki pages) is intentional — one is a flat registry for dedup and alias search, the other is the actual content.
Example: What a Compiled Concept Page Looks Like
Here's a trimmed excerpt of wiki/concepts/retrieval-augmented-generation.md after compile synthesized it from three raw sources:
---
title: Retrieval-Augmented Generation
created: 2026-03-02
last_updated: 2026-04-14
source_count: 3
status: reviewed
---
# Retrieval-Augmented Generation
RAG augments an LLM's context window with relevant documents fetched from
an external store at query time, rather than relying on parametric memory
alone. This addresses two failure modes of vanilla LLMs: outdated training
data and hallucination on long-tail facts.[^1]
## Core Loop
1. **Embed the query** into a dense vector ([[embeddings]])
2. **Retrieve** top-k similar chunks from a [[vector-database]]
3. **Augment** the prompt with retrieved context
4. **Generate** the answer conditioned on both query and context
## When RAG Beats Fine-Tuning
Gao et al. find RAG is preferable when the knowledge base changes frequently
or when source attribution matters for the end user.[^3] See also
[[fine-tuning-vs-rag]] for the decision framework.
## Related Concepts
- [[chunking-strategies]] — how source documents get split before embedding
- [[reranking]] — second-stage filtering of retrieved candidates
- [[hybrid-search]] — combining dense and sparse retrieval
[^1]: raw/articles/lewis-2020-rag-paper.md
[^3]: raw/papers/gao-2023-rag-survey.pdf
Three things to notice: aliases live in .atlas/concepts.json (so /atlas search "RAG" finds this page), every factual claim cites back to a raw source file (so lint's Source Verifier and /atlas verify can audit it), and the frontmatter status is the review lifecycle (draft → reviewed, with review_pending set by compile on contradictions and cleared by verify).
Pairing with Mentor
Atlas organizes knowledge. It does not judge whether a source is worth including before ingest — that's /mentor evaluate in the companion Mentor skill.
| Job | Tool |
|---|---|
| Filter what's worth ingesting | /mentor evaluate |
| Organize what passes evaluation | /atlas ingest + /atlas compile |
| Internal consistency and hallucination audit | /atlas lint (surfaces /mentor evaluate candidates in its report) |
Atlas works standalone (lint still saves reports, leads chased manually). Mentor is domain-specific and can be adapted to any field — see the mentor skill README for the rewrite template.
Pairing with Code Fluent
Atlas produces markdown. It does not produce interactive HTML — that's the companion Code Fluent skill. /atlas export <slug> delegates rendering to code-fluent via a subagent, which means any improvement to code-fluent's doc-path automatically improves atlas's exports.
| Job | Tool |
|---|---|
| Research a question against the wiki, save a markdown answer | /atlas query "question" |
| Render an existing report as an interactive HTML guide | /atlas export <report-slug> |
| Render any directory of docs or code that isn't a KB | code-fluent directly — cd to the dir, say "explain this project" / "break this down" / "document this research" |
How /atlas export works. It takes a report slug (filename without .md), not a file path. Atlas must find a KB.md in the current directory (or up to 3 parents) to locate the knowledge base. Typical use:
cd "/Users/you/Documents/AI Engineer Roadmap"
/atlas query "What are the tradeoffs between RAG and fine-tuning?"
# atlas writes wiki/reports/rag-vs-fine-tuning.md
/atlas export rag-vs-fine-tuning
# atlas produces wiki/reports/rag-vs-fine-tuning-guide.html
/atlas export is KB-only. It does not render arbitrary markdown files. If you want to turn a standalone .md file (or a doc directory that isn't an atlas KB) into an HTML guide, invoke code-fluent directly in that directory instead.
Under the hood. Export copies the report plus KB.md (renamed to README.md) into a slug-scoped temp directory at /tmp/claude_scratch_atlas_export_<slug>/, then spawns a subagent that runs code-fluent against that directory. The KB.md → README.md rename is how atlas hands project context (subject, categories, scope) to code-fluent without modifying code-fluent — it scans for a README.md at the root, and now finds one. See references/commands/export.md for the full rationale.
Atlas works standalone (skip /atlas export if code-fluent isn't installed — the markdown reports from /atlas query are still readable in any editor). Code-fluent works standalone too (it operates on any directory, not just atlas KBs).
Two Ingest Paths: Fidelity vs. Convenience
Atlas ingest has two paths for web content, and you should pick based on how you'll use the source.
Fidelity = how closely the stored content matches the original word-for-word. High fidelity preserves the author's exact wording (safe to quote directly, cite publicly, or rely on for exact terminology). Low fidelity captures the gist but may paraphrase through an LLM pass.
| Path | Fidelity | When to use |
|---|---|---|
Clip locally → /atlas ingest <path> | High (verbatim) | Material you'll quote directly, cite publicly (LinkedIn, interviews, research), or depend on exact wording. Also any source behind auth, paywalls, or known to change (company blogs, docs). |
/atlas ingest <URL> directly | Best-effort verbatim via LLM prompt | Routine topical coverage where you just need the concepts logged. Small skill cost for the convenience of one-command ingestion. |
The clip-then-ingest workflow (recommended for fidelity)
Pick any tool that saves a web page as markdown or HTML to local disk:
- Obsidian Web Clipper (browser extension). Outputs clean markdown; Karpathy's recommendation. Best if you already use Obsidian.
- SingleFile / SingleFile Lite (browser extension). Saves the complete page as a single HTML file. Language-agnostic; works for anyone.
- MarkDownload (browser extension). Specifically outputs markdown with YAML frontmatter.
- Browser's native "Save Page As..." (HTML or webpage complete). Zero install, works everywhere. Atlas ingests
.htmlas a file and preserves it verbatim. - Reader mode → print to PDF. Useful for long articles with heavy formatting. Atlas ingests PDFs and extracts text via the Read tool.
Save the file anywhere (Downloads, Desktop, a dedicated ~/clippings/ folder — it doesn't matter), then run /atlas ingest <saved file path>. Atlas moves the file into raw/, runs dedup checks, downloads referenced images locally, and updates .atlas/hashes.json and KB.md. No LLM interpretation of the source content happens at ingest.
Why not drop files directly into raw/articles/ yourself? You skip atlas's bookkeeping (dedup by URL, image downloading, hash registration, raw_count increment). The file becomes orphaned from atlas state. Always go through /atlas ingest.
Direct URL ingest (convenience path)
/atlas ingest https://... uses WebFetch with a verbatim-preservation prompt. Atlas warns you at invocation time that this path is LLM-mediated and offers the clip-then-ingest alternative. If you proceed, the fidelity is best-effort — the prompt asks the model to preserve every sentence exactly, but an LLM pass is still an LLM pass.
The extraction_method frontmatter field
Every ingested file gets an extraction_method field in its frontmatter so compile, lint, and future you can judge fidelity:
| Value | Meaning |
|---|---|
file-copy | Verbatim copy of a local file. Highest fidelity. |
web-clipper | File from a browser clipper (Obsidian Web Clipper, SingleFile, MarkDownload). Verbatim. |
webfetch-verbatim-prompt | URL ingested directly via WebFetch with a preservation prompt. Best-effort verbatim but LLM-mediated. |
pdf-extract | Text extracted from a PDF. Depends on PDF quality. |
dataset-schema | Schema summary only, not the full data. |
manual-drop | File placed directly in raw/, metadata backfilled during compile. Unknown fidelity. |
If you later audit a wiki claim and suspect compile hallucinated or compressed something important, check the source file's extraction_method. Anything other than file-copy or web-clipper is worth re-verifying against the original.
What to Expect
Image handling. When you ingest a URL, Atlas downloads significant images from the article and saves them to raw/images/. Decorative images (logos, avatars, icons, tracking pixels, anything under 5KB) are skipped. Markdown image references in the saved article are rewritten to point to the local copies. During compile, image references carry through into concept pages automatically. If a download fails, the original remote URL is kept.
Dataset ingestion. When you ingest a .csv, .parquet, .jsonl, or .xlsx file, Atlas saves it to raw/datasets/ and creates a companion -schema.md file with column names, row count, and the first 3 rows. Compile agents read the schema file, not the raw data (they cannot parse binary formats directly).
Duplicate detection. Before adding a new raw source, Atlas checks if the same URL or filename already exists in raw/. If it finds a match, it asks whether to update, duplicate, or skip.
Manual drops. You can place files directly into raw/ (file explorer, drag-and-drop, or by saving a clipper's output to raw/articles/ directly). During compile, Atlas detects files without frontmatter, adds minimal metadata (title from filename, date from file timestamp, extraction_method: manual-drop), and includes them in the compile. Note: manual drops skip atlas's ingest bookkeeping (dedup check, image downloading, hash registration) — prefer /atlas ingest <path> whenever possible.
Query filing. After answering a query, Atlas offers to extract new concepts from the answer back into the wiki. Accepting this creates or updates concept pages, enriching future queries.
Lint health scores. Lint produces a health rating: HEALTHY (0 critical issues, under 3 important, 0 unsupported claims), NEEDS ATTENTION (1-3 critical or 5+ important), or DEGRADED (4+ critical, contradictions, or 3+ unsupported claims from the hallucination audit).
Web search quarantine. If a query requires web search, Atlas always asks first. Web results are saved to raw/ and compiled through the normal pipeline. They are never injected directly into wiki pages.
Lint-Driven Improvement
Running /atlas lint produces a health report saved to wiki/lint/lint-YYYY-MM-DD.md. The report identifies issues, suggests improvements, and includes ready-to-run commands for follow-up. Nothing is lost between sessions.
The lint report's sections, each with a different follow-up path:
| Lint Section | What it finds | How to act on it |
|---|---|---|
| Issues | Broken links, orphan pages, contradictions, registry drift | Accept auto-fix when prompted, or fix manually |
| Review Queue | Concept pages in review_pending | Run the printed /atlas verify pending command |
| Source Verification | Claims that don't match the cited source (hallucination audit) | Edit the concept page to match what the source actually says |
| Suggested Connections | Concept pairs that should cross-link but don't | Add links manually, or wait for next compile |
| New Article Candidates | Topics referenced by many pages but with no page of their own | Run the /mentor evaluate command in the report (includes --context paths to relevant wiki pages) |
| Research Questions | Gaps the wiki almost answers but doesn't fully cover | Run the /atlas query command in the report |
| Stale-by-Content Reports | Reports whose cited concepts changed after they were written (informational only — nothing is flagged) | Paste any entry's Refresh: command when you want that report current |
The key design: atlas finds the gaps and prepares the commands. Mentor evaluates whether to fill them. Atlas organizes the result. The user decides what to pursue.
Atlas works without mentor. Lint still saves reports and auto-fixes structural issues. The /mentor evaluate commands in the report are suggestions, not dependencies. If mentor isn't installed, chase the leads manually.
Limitations
- Requires Claude Code. Atlas runs as a Claude Code skill. It doesn't work standalone, in other IDEs, or with other model providers.
- Scale ceiling around 500-1000 concepts. The two-tier hierarchical index stays performant up to roughly that range. Past that, index structure needs re-architecture (deeper category hierarchy, sharded sub-indexes) that Atlas doesn't currently support.
- Compile time scales with source count. A full rebuild on 100 sources takes minutes; 500+ takes tens of minutes. Use
compile --incrementalfor day-to-day work — it only rebuilds changed sources. - Hand-edits to wiki files get overwritten. The wiki is regenerated from
raw/. If you editwiki/concepts/X.mddirectly, the next compile may blow your changes away. Edit sources inraw/instead, or accept that wiki edits are ephemeral. - Single-user. Atlas assumes one person writing to one repo. No multi-user sync, no concurrent-edit resolution, no real-time collaboration.
- No source evaluation built in. Atlas ingests whatever you give it. Garbage sources in → garbage concept pages out. Use
/mentor evaluateto filter before ingesting, and/atlas lintto catch hallucinations after.
Deferred Features
Features that were considered, scoped, and explicitly not built. Each is deferred rather than rejected — the triggers for revisiting them are documented so future-you knows when to pick them up.
Browse-mode view (--view)
A non-linear interactive HTML exploration surface for a whole KB. Left sidebar lists every concept (searchable, filterable by category). Center shows a force-directed cross-reference graph. Click a concept to render it in a right panel. Top bar filters by category or tag.
Today's atlas outputs (/atlas query, /atlas export) are all teach-paradigm — synthesized answers meant to be read top to bottom. Browse-paradigm is fundamentally different: exploration, not reading. For a curated personal KB whose owner already roughly knows the contents, teach is the 90% path. Browse is the 10% insight-discovery path, mostly served today by wiki/INDEX.md + /atlas search + grep.
Reserved naming. The flag name --view is reserved for this feature. Do not use it for anything else. If it ever gets built, /atlas view or /atlas export --view <slug> is the semantically correct invocation.
When to revisit:
- You start wishing you could "see everything laid out" more than once a week.
- KB grows past ~200 concepts and teach outputs can't show enough graph structure.
- You want to present or demo the KB to someone else — browse view adds real value there.
Source of idea. Inspired by an X post on 2026-04-02 about dynamic research paper visualizations.
Always-On Setup (Optional)
By default, atlas only acts when you explicitly invoke /atlas <command>. If you want atlas to surface itself automatically whenever you grep or glob inside a KB directory, install the PreToolUse hook. With the hook installed, every time Claude is about to call Glob or Grep in a directory containing a KB.md (in cwd or up to 3 parent directories), Claude sees an injected notification telling it the KB exists and to consider /atlas search or /atlas query first. The hook never blocks; it only adds context.
This turns atlas from "tool you have to remember to invoke" into an always-on context layer. Especially useful inside large KBs where grepping raw files would miss the synthesized concept pages atlas already built.
Installation
The hook ships with atlas at ~/.claude/hooks/atlas-kb-context.py. To enable it, add the following entry to the PreToolUse array in ~/.claude/settings.json:
{
"matcher": "Glob|Grep",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/atlas-kb-context.py"
}
]
}
Place this entry alongside any other PreToolUse hooks you already have. Restart your Claude Code session for the new hook to take effect.
How it works
The hook reads the session's working directory from stdin, walks up at most 3 parent directories looking for KB.md, and if found:
- Extracts the KB's
subjectfrom the KB.md frontmatter (best effort) - Builds a context message naming the KB, pointing at
wiki/INDEX.md, and suggesting/atlas searchor/atlas queryas alternatives to raw grep - Outputs the message via the
hookSpecificOutput.additionalContextchannel - Exits 0 (never blocks the underlying Glob or Grep)
If no KB.md is found in the walk, the hook exits silently and the Glob or Grep proceeds normally. The hook is fast: a single filesystem walk plus a small file read takes microseconds. It runs on every Glob and Grep, so cost adds up only if you grep thousands of times per session.
Disabling
To disable, remove the Glob|Grep entry from the PreToolUse array in settings.json and restart Claude Code. The hook script can stay on disk; without the settings entry it never runs.
Skill File Structure
The skill uses a sub-indexed pattern to keep SKILL.md small. SKILL.md contains the dispatcher, Phase 0 (auto-detect knowledge base), Mode Detection, and Rules for All Commands. Per-command operational logic lives in separate reference files that get loaded on demand:
atlas/
├── SKILL.md # Dispatcher (under 200 lines)
├── README.md # This file
└── references/
└── commands/
├── init.md # Create KB structure
├── ingest.md # Add raw sources
├── compile.md # Build wiki (3 sequential agents)
├── query.md # Hierarchical retrieval
├── lint.md # Health check (6 parallel agents — 5 if wiki/reports/ is empty)
├── verify.md # Spot-check flagged concepts against sources, clear the queue
├── status.md # Quick stats
├── export.md # Render a report as an HTML guide via code-fluent
└── search.md # Alias-aware full-text search
When the user invokes a command, SKILL.md tells Claude to STOP and Read the corresponding file before proceeding. This keeps each invocation's context cost ~75% smaller than loading the full SKILL.md. A /atlas status call loads ~170 lines (SKILL.md) + ~45 lines (status.md) instead of the previous ~1160-line monolith.
Use
Use it however you want. No warranty, no promises.