// Use synrepo in repositories with a .synrepo/ directory. Prefer synrepo cards, compact search, and bounded task contexts before reading source files cold.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | synrepo |
| description | Use synrepo in repositories with a .synrepo/ directory. Prefer synrepo cards, compact search, and bounded task contexts before reading source files cold. |
Use this skill only when the current repository contains a .synrepo/ directory.
This repo-root file is the canonical agent protocol doc for synrepo. It is not the standalone install target. Installed Agent Skills live in spec-valid directories such as .agents/skills/synrepo/ and .claude/skills/synrepo/.
For product overview, setup flow, and operator-facing docs, start with README.md. This file is the agent operating guide for querying synrepo safely once the repo is already wired.
Synrepo is a local, deterministic code-context compiler. Its product model is repo files -> graph facts -> code artifacts -> task contexts -> cards/MCP. Graph facts are authoritative observed source truth; code artifacts are compiled records; task contexts are bounded bundles for a workflow; cards and MCP responses are the delivery packets you consume.
Use synrepo_ask(ask, scope?, shape?, ground?, budget?) as the default high-level front door for one bounded, cited task-context packet. It returns answer, cards_used, evidence, grounding, omitted_context_notes, next_best_tools, and context_packet. Its grounding policy accepts mode or citations, include_spans, and allow_overlay; default to graph facts as authoritative observed source truth. Overlay commentary, explain docs, and notes are advisory; LLM-authored output never mutates the canonical graph. Embeddings are optional routing/search helpers.
Existing explain reads are safe when useful: use synrepo_explain with budget=deep for 1-3 focal symbols/files before non-trivial implementation, review, security work, or unfamiliar subsystem changes; use synrepo_docs_search for architecture, intent, gotchas, or "why is this like this" questions. These read cached overlay output; they do not generate or refresh commentary.
Use synrepo for orientation, codebase questions, reviews, broad search before opening files, exact lexical search, edit routing, first-pass impact, entrypoint discovery, test-surface discovery, and high-level subsystem understanding.
Do not use synrepo for tiny files you already need to edit directly, files already in working context, simple config or text files with no meaningful symbols, or raw-source patching after a bounded synrepo card has already identified the exact range.
The required sequence for codebase questions, reviews, search routing, and edits is orient, ask or search, cards, impact or risks, edit, tests, changed.
synrepo_orient before reading the repo cold. It is a small routing summary, not the full dashboard.synrepo_ask for broad plain-language tasks that need one bounded, cited task-context packet.synrepo_task_route when only classification is needed, then choose between synrepo_ask, synrepo_find, synrepo_where_to_edit, and synrepo_search.tiny cards to route and normal cards to understand. Use synrepo_minimum_context as the bounded neighborhood step when a focal target is known but the surrounding risk is unclear, especially for file reviews and codebase questions.synrepo_impact or synrepo_risks before editing or reviewing risky files.synrepo_tests before claiming done.synrepo_changed after edits to review changed context and validation commands.synrepo_resume_context before asking the user to repeat repo state.deep cards only after bounded cards identify the target or when the card content is insufficient. Full-file reads are an explicit escalation, not the default first step.Rule of thumb: tiny to find, normal to understand, deep to write.
Load only the reference file that matches the immediate task:
references/search-routing.md: exact search, broad query recovery, diagnostic fields, and code-shaped probes.references/mcp-tools.md: full tool catalog, overlay-write tools, source-edit tools, and when to use each.references/budgets-and-errors.md: budget tiers, context contract, response fields, rate limits, and structured errors.references/editing-and-mutation.md: MCP edit path, mutation gates, prepared anchors, and hook signals.references/setup-and-fallback.md: project/global MCP selection, managed project registration, resources, and CLI fallback.For exact symbols, tool names, function names, flags, JSON keys, CLI args, error strings, or file paths, prefer:
synrepo_search(query, literal?, limit?, output_mode?, budget_tokens?)Use output_mode: "compact" for orientation. Search rows and compact file groups may include root_id, is_primary_root, file_id, and root-aware suggested_card_requests; use those fields when the same relative path appears in both the primary checkout and a linked worktree. Do not use a full sentence when an exact token or string literal is known. Set literal: true for code strings that contain regex metacharacters, for example Error::Other(anyhow. If a regex-like query fails to compile, synrepo_search retries as a literal and reports pattern_mode: "literal_fallback" with a warning. For plain-language edit or investigation tasks, call:
synrepo_ask(ask, scope?, shape?, ground?, budget?)synrepo_task_route(task, path?)synrepo_find(task, limit?, budget_tokens?)synrepo_where_to_edit(task, limit?)Read query_attempts, fallback_used, miss_reason, recommended_next_queries, recommended_tool, suggested_card_targets, and output_accounting when present. If miss_reason is no_index_matches, do not retry the same broad sentence. Switch to exact lexical probes.
See references/search-routing.md for examples, fallback rules, and phrase-to-probe mappings.
Graph content is primary. Overlay content is advisory. Materialized advisory explain docs are overlay output, not canonical graph facts. Prepared edit anchors are session-scoped operational state. They are not graph facts, overlay content, commentary, agent notes, or agent memory.
If overlay and graph disagree, trust the graph. Existing explain reads use cached overlay output. Freshness is explicit. A stale label is information, not an error; it is not silently refreshed on read.
Global MCP configs that launch synrepo mcp serve registered projects by absolute path. In global or defaultless contexts, pass the current workspace's absolute path as repo_root to repo-addressable tools, or call synrepo_use_project(repo_root) once to set the session default.
If a tool reports that a repository is not managed by synrepo, ask the user to run:
synrepo project add <path>
Do not bypass registry gating.
Client-side nudge hooks for Codex and Claude may remind agents to use synrepo before direct grep, read, review, or edit workflows. Do not mistake client-side hook nudges for MCP interception or enforcement. They are non-blocking reminders.
tiny and escalate only when a specific field forces it.--generate-cross-links, commentary generate/refresh) unless the task justifies the cost; cached explain reads are allowed.synrepo watch is explicitly running.synrepo_apply_anchor_edits without a fresh synrepo_prepare_edit_context response.root_id from search or prepare results when editing worktree files; omitted root_id means the primary checkout.synrepo_find query repeatedly. Convert it to exact synrepo_search probes.synrepo_resume_context has been tried.Do not maximize returned context. Return the smallest useful MCP response.
Default to tiny. Use normal for the best 1-3 targets when local understanding matters. Use deep or full-file reads only immediately before implementation or validation. Do not request deep cards for more than 1-3 files at a time.
See references/budgets-and-errors.md for the full budget sequence, response fields to consume first, and rate-limit/error handling.
synrepo stores code facts and bounded operational memory. It is not a task tracker, not session memory, and not cross-session agent memory.
Any handoff or next-action list is a derived recommendation regenerated from repo state. External task systems own assignment, status, and collaboration.
Prepared edit anchors are short-lived MCP operational state, not durable agent memory.
synrepo_resume_context is advisory, read-only, and regeneratable. It is not prompt logging, chat history, raw tool-output capture, or generic session memory.