Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add skills/cranot/roam-code/roamnpx skills add Cranot/roam-code --skill roamgit clone --depth 1 https://github.com/Cranot/roam-codeWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00086 | $0.02460 |
| Opus 5 | $0.00043 | $0.01230 |
| Sonnet 5 | $0.00017 | $0.00492 |
| Haiku 4.5 | $0.00009 | $0.00246 |
Grade A, and why
roam scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 276 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Roam — Codebase Comprehension Skill
Repository: https://github.com/Cranot/roam-code
Roam pre-indexes codebases into a semantic graph (symbols, dependencies, call graphs, architecture layers, git history) stored in a local SQLite DB. Query it via CLI instead of repeatedly grepping files and guessing structure.
Setup
Ensure roam-code is installed and the project is indexed:
pip install roam-code # or: pipx install roam-code
cd <project-root>
roam init # indexes codebase, creates .roam/index.db
After git pull or major changes, run roam index to refresh (incremental,
near-instant if few files changed). After large refactors: roam index --force.
Command Decision Table
Use this table to pick the right command for the situation:
| Situation | Command |
|---|---|
| First time in a repo | roam understand then roam tour |
| Need a compact codebase overview | roam map or roam minimap |
| Find a symbol by name | roam search <pattern> |
| Need files to read for a symbol | roam context <symbol> |
| Inspect a file's structure | roam file <path> |
| Inspect a directory | roam module <path> |
| Before modifying a symbol | roam preflight <symbol> |
| What breaks if I change X? | roam impact <symbol> |
| Blast radius of uncommitted changes | roam diff |
| Debugging a failure | roam diagnose <symbol> |
| Which tests cover a symbol? | roam affected-tests <symbol> |
| Check codebase health | roam health |
| Find hotspots (churn x complexity) | roam weather |
| Detect dead/unused code | roam dead |
| PR risk assessment | roam pr-risk |
| Find dependency paths | roam trace <source> <target> |
| Who calls/imports this? | roam uses <symbol> (alias: roam refs) |
| Find every reference to X (replaces multi-shape grep) | roam refs <symbol> |
| Algorithm anti-patterns | roam algo |
| Side effects of a function | roam effects <symbol> |
| Safe to delete? | roam safe-delete <symbol> |
| Simulate a refactor | `roam simulate move |
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- yesterday First seen · 276 lines · 86 tokens per session scan A a78d680a0947
roam is a skill published in the GitHub repository Cranot/roam-code (510 stars, last pushed 6d ago), licensed Apache-2.0. It adds 86 tokens to every session and 2,460 once invoked, about $0.0004 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
audit-pr-architecture
Audit a PR's structural choices against architecture-priming, the repo's own architecture.md, and any nested boundary configs. Use when the user says "audit this PR's architecture", "check the boundaries", "is this PR clean structurally", "post-merge review of.
docs-voice
Voice, tone, and format for the public Codemap docs (apps/docs, built with Blume). Use when authoring or editing apps/docs prose — landing, guides, concepts, recipes, reference, generated API — or deciding headline grammar, benefit framing, peer framing, or anti-pitch wording.
improve-codebase-architecture
Find deepening opportunities in the codebase, informed by the domain language in docs/glossary.md and the architecture in docs/architecture.md. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
writing-agents-config
Codemap repo hybrid deltas for .agents/ — tiers, rule-skill pairing, repo exemplars. Use when creating or reviewing rules/skills in this repo. Read writing-great-skills first for skill vocabulary and authoring principles.
agents-tier-system
Full tier assignments, pairing conventions, and authoring checklist for .agents/ rules and skills. Use when creating or reviewing a rule or skill, deciding Tier 1 vs 2 vs 3, or auditing attachment cost.
verify-after-each-step
Per-file verification checklist — lint-staged and package.json scripts after each milestone.