repo-atlas
Skill0 starsChanged 4 months agoMITView on GitHub
Create polished repository onboarding documentation as static HTML. Use when a user asks an agent to explore a repo, explain architecture, produce diagrams, render existing Markdown/spec docs into browser-friendly pages, build a glossary of acronyms/domain terms, summarize historical decisions from docs such as .kiro/, or make a new-engineer repo atlas/code map.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- cathrynlavery/repo-atlastheir own version, first seen Nov 6, 2026
- BrickerP/Personal-Skillstheir own version, first seen Nov 1, 2026
- AndreaMontemaggiore1/repo-atlastheir own version, first seen Nov 1, 2026
- Lxiny-zy/repo-atlastheir own version, first seen Oct 5, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- cathrynlavery/repo-atlas★ 56same name
- Lxiny-zy/repo-atlas★ 13same name
- AndreaMontemaggiore1/repo-atlas★ 2same name
- BrickerP/Personal-Skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
32 rules. 0 are common, 16 are distinctive, and 16 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
16
Distinctive
This author's own choices. Worth a look.
16
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Default output path: docs/repo-atlas/ unless the user asks otherwise.
- Very specific: line 30
Do not invent a new visual direction for each repo-atlas run.
- Very specific: line 32
If a repo already contains a high-quality docs/repo-atlas/, use it as the local exemplar for structure, density, and tone before creating …
- Very specific: line 37
Read repo entry points: README*, build files, package/workspace manifests, CI config, docs directories, and obvious app/service roots.
- Very specific: line 38
Search for decision/spec/history directories such as .kiro/, docs/, adr/, architecture/, rfcs/, specs/, and design/.
- Distinctive: line 39
Use QMD or other local notes if project history is likely to matter and the environment provides it.
- Very specific: line 43
Prefer these pages: index.html, architecture.html, history.html, operations.html, code-map.html, docs.html, glossary.html, styles.css.
- Very specific: line 44
Add read/*.html pages for important Markdown/spec documents so browser links do not open raw Markdown.
- Very specific: line 45
If scope must be smaller, keep index.html, architecture.html, code-map.html, and glossary.html.
- Distinctive: line 46
Do not stop at a file catalog.
- Distinctive: line 57
Add a short summary near the top of each rendered page.
- Distinctive: line 58
Keep a source link back to the original Markdown.
- Very specific: line 59
Add local Mermaid support when rendered Markdown contains Mermaid blocks: use scripts/fetch_mermaid.py to vendor the pinned Mermaid bundle …
- Very specific: line 64
Add glossary.html grouped by domain.
- Distinctive: line 65
Add hover/focus explanations on first-use terms across the atlas using accessible text, not only visual decoration.
- Distinctive: line 69
Prefer restrained, tactile, information-dense pages.
- Distinctive: line 70
Avoid generic blue/purple gradients, decorative blobs, and oversized card-heavy SaaS layouts.
- Very specific: line 71
Prefer a readable sans/mono pair for technical docs.
- Distinctive: line 72
Avoid editorial serif headings unless the user explicitly requests that style.
- Distinctive: line 73
If the user supplied a style reference, follow it.
- Distinctive: line 74
Use stable responsive dimensions so diagrams and buttons do not jump or overlap.
- Distinctive: line 77
Run a static link sweep across the generated pages.
- Very specific: line 78
Run a local asset sweep for src, href, and CSS url(...).
- Distinctive: line 79
Start a local static server and inspect at least the index, code map, docs reader, and glossary.
- Distinctive: line 80
Use a real browser for interactive diagrams and mobile layout.
- Distinctive: line 81
If using Mermaid, verify a representative Mermaid diagram renders as SVG and loads the local vendored script.
- Distinctive: line 82
If using bundled fonts, verify local font files load.
- Distinctive: line 83
Remove temporary screenshots/browser metadata before final status.
- Very specific: line 87
Read references/atlas-workflow.md when planning or implementing a full atlas.
- Very specific: line 88
Use assets/paper-atlas.css as a visual starter when no repo design system exists.
- Very specific: line 91
Use scripts/fetch_mermaid.py to obtain the pinned local Mermaid bundle when it is needed.
- Very specific: line 92
Use scripts/render_markdown.py to create simple static HTML reader pages for Markdown documents.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Repo Atlas
Goal
Build a reviewable static documentation bundle that helps a new engineer understand a repository quickly: what it does, how the main parts connect, which docs matter, what terms mean, and where to change code.
Default output path: docs/repo-atlas/ unless the user asks otherwise.
Non-Negotiable Output Contract
Unless the user explicitly asks for a smaller artifact, produce the full atlas shape below and keep it visually consistent:
index.html: guided start page, not a marketing landing page.architecture.html: current architecture with diagrams.history.html: timeline and superseded decisions from repo docs.operations.html: build/run/deploy/observe/failure-mode guide.code-map.html: behavior-oriented source map, preferably interactive.docs.html: curated documentation shelf with summaries.glossary.html: grouped acronym/domain glossary.read/*.html: rendered important Markdown/spec documents.styles.css: use the bundledassets/paper-atlas.cssstarter unless the repo has a stronger design system or the user asks for another style.vendor/fonts/*: copy bundled Atkinson fonts when using the starter CSS.vendor/mermaid.min.js,vendor/mermaid.LICENSE, andmermaid-render.js: include when any reader page has Mermaid blocks.
Do not invent a new visual direction for each repo-atlas run. Start from the bundled warm paper technical-doc aesthetic, then adapt only where repo context or explicit user guidance requires it.
If a repo already contains a high-quality docs/repo-atlas/, use it as the local exemplar for structure, density, and tone before creating or regenerating pages.
Workflow
- Gather context first
- Read repo entry points:
README*, build files, package/workspace manifests, CI config, docs directories, and obvious app/service roots. - Search for decision/spec/history directories such as
.kiro/,docs/,adr/,architecture/,rfcs/,specs/, anddesign/. - Use QMD or other local notes if project history is likely to matter and the environment provides it.
- Inspect source by behavior, not only by directory tree: ingress, transformation, domain logic, persistence/transport, background jobs, operations, deployment, tests.
- Read repo entry points:
- Decide the atlas shape
- Prefer these pages:
index.html,architecture.html,history.html,operations.html,code-map.html,docs.html,glossary.html,styles.css. - Add
read/*.htmlpages for important Markdown/spec documents so browser links do not open raw Markdown. - If scope must be smaller, keep
index.html,architecture.html,code-map.html, andglossary.html. - Do not stop at a file catalog. The atlas must explain relationships, flows, history, and common change paths.
- Prefer these pages:
- Use visual explanation
- Include diagrams before dense tables.
- Show current architecture, request/data flow, deploy shape, and source-code ownership boundaries.
- Mark historical/superseded diagrams clearly when including them.
- Preserve Mermaid diagrams from source Markdown and render them in the browser. Do not leave
graph TB,sequenceDiagram,flowchart,classDiagram, orstateDiagramblocks as raw code in reader pages. - For code maps, add an interactive layer when helpful: tabs for major views, clickable nodes, related-node highlighting, and a detail panel with role, files, docs, and common change reasons.
- Make docs readable in-browser
- Render important Markdown into static HTML under
read/. - Add a short summary near the top of each rendered page.
- Keep a source link back to the original Markdown.
- Add local Mermaid support when rendered Markdown contains Mermaid blocks: use
scripts/fetch_mermaid.pyto vendor the pinned Mermaid bundle and license undervendor/, copyassets/mermaid-render.js, inject both scripts into reader pages, and verify diagrams render as SVG. - For less important Markdown, a styled docs index with summaries is enough.
- Render important Markdown into static HTML under
- Build a glossary
- Extract acronyms, domain words, protocol names, vendor/product names, and operational abbreviations from docs and source.
- Add
glossary.htmlgrouped by domain. - Add hover/focus explanations on first-use terms across the atlas using accessible text, not only visual decoration.
- Design for engineers, not marketing
- The first screen should be useful documentation, not a landing page.
- Prefer restrained, tactile, information-dense pages.
- Avoid generic blue/purple gradients, decorative blobs, and oversized card-heavy SaaS layouts.
- Prefer a readable sans/mono pair for technical docs. The bundled starter uses Atkinson Hyperlegible Next and Atkinson Hyperlegible Mono; copy
assets/fonts/into the output and keep the font paths local sofile://viewing works. - Avoid editorial serif headings unless the user explicitly requests that style.
- If the user supplied a style reference, follow it.
- Use stable responsive dimensions so diagrams and buttons do not jump or overlap.
- Verify before finishing
- Run a static link sweep across the generated pages.
- Run a local asset sweep for
src,href, and CSSurl(...). - Start a local static server and inspect at least the index, code map, docs reader, and glossary.
- Use a real browser for interactive diagrams and mobile layout.
- If using Mermaid, verify a representative Mermaid diagram renders as SVG and loads the local vendored script.
- If using bundled fonts, verify local font files load.
- Remove temporary screenshots/browser metadata before final status.
Resources
- Read
references/atlas-workflow.mdwhen planning or implementing a full atlas. - Use
assets/paper-atlas.cssas a visual starter when no repo design system exists. - Copy
assets/fonts/when using the starter CSS, preserving the relativevendor/fonts/*.woff2output path or updating the CSS paths. - Copy
assets/mermaid-render.jswhen rendering Markdown pages that may contain Mermaid diagrams. - Use
scripts/fetch_mermaid.pyto obtain the pinned local Mermaid bundle when it is needed. The script writes Mermaid's license beside the bundle. - Use
scripts/render_markdown.pyto create simple static HTML reader pages for Markdown documents.
Quality Bar
The result should answer these questions without making a new engineer reverse-engineer the repo:
- What is this system for?
- What are the main runtime components?
- What is the most important request/data flow?
- Which historical decisions matter, and which are superseded?
- Which docs/specs are canonical?
- What do the local acronyms and domain terms mean?
- Where do I change code for the common task categories?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

