Category: Graphify

A reliable CC Switch knowledge graph workflow uses two separate layers: CC Switch selects and connects the provider; an external, revision-bound graph supplies repository relationships. The first layer answers “which model can this agent call?” The second answers “which files, symbols, contracts, tests, and owners are relevant to this task?”

Keeping those responsibilities separate makes Claude, Kimi, Codex, and other providers replaceable without pretending that session reasoning or repository understanding moves between them automatically.

The Two-Layer Workflow

The workflow starts with a hard boundary between access state and evidence state.

Layer	Owned data	Refresh trigger	Primary failure
CC Switch access layer	Provider profiles, active route, protocol format, selected model, MCP and Skills configuration	Provider, credential, model, or routing change	Requests reach the wrong endpoint or use an incompatible protocol
Repository evidence layer	Revision, files, symbols, dependencies, schemas, tests, owners, architecture records, provenance	Source or documentation change	The agent receives stale, incomplete, or unsupported relationships
Task packet	Goal, non-goals, selected graph results, assumptions, approvals, verification plan	Each task or handoff	A provider receives too much context or misses a critical constraint

Run the layers as a sequence:

1. Pin the repository revision and define the task boundary.
2. Query the graph for the smallest useful evidence set.
3. Inspect current source behind high-impact relationships.
4. Select the provider and verify the CC Switch route.
5. Start a new agent session with the reviewed task packet.
6. Edit only after the agent restates scope and unresolved assumptions.
7. Run tests, review the diff, and refresh graph artifacts when structure changed.

This is a model-independent workflow because the durable artifact is not a provider transcript. It is a source-linked evidence packet that another provider can reconstruct and challenge.

CC Switch for Model Access

CC Switch is a third-party provider and configuration manager. Its current repository describes profiles for multiple coding tools, one-click switching, provider presets, synchronized MCP and Skills configuration, session management, and a local proxy with format conversion.

Provider access is not always a direct endpoint substitution. The CC Switch Kimi guide says newer Codex clients use the Responses API while Kimi endpoints can expose Chat Completions. Its local route converts requests and responses between those formats. The Claude routing guide describes a similar bridge between Codex Responses and Anthropic Messages. In both cases, the provider card, local routing service, app-level routing toggle, and restarted Codex process must agree.

A preflight should therefore record:

• the coding client and active CC Switch provider;
• model identifier and provider-specific model mapping;
• direct versus local-route connection;
• upstream protocol and any conversion step;
• credential location and allowed disclosure;
• MCP and Skills enabled for the target client;
• whether the client must restart to reload configuration.

Do not infer model equivalence from a successful route. Protocol conversion can make request shapes interoperable, but it does not make tool behavior, context limits, reasoning, output quality, or provider policies identical.

Security also belongs at this layer. The v3.18.0 release says current diagnostic logging uses redaction and rotation, but it explicitly warns that logs written by earlier versions are not retroactively cleaned. The routing guides keep real provider keys in CC Switch configuration while the local route injects them during forwarding. Teams must still review provider terms, retention, network path, local file permissions, and the exact repository evidence being disclosed.

Knowledge Graphs for System Relationships

The graph layer represents revision-bound system structure. Useful node types include repositories, packages, files, symbols, endpoints, schemas, migrations, tests, owners, and decision records. Useful relationships include imports, calls, implements, generates, validates, owns, and explains.

Each result needs provenance. At minimum, return:

• repository and commit;
• source and target entities;
• relationship type;
• file and location supporting the edge;
• extractor or query version;
• deterministic versus inferred status;
• freshness time and known coverage gaps.

This turns a graph result into inspectable evidence. “Service A depends on schema B” is not enough. “At commit X, symbol A imports generated type B at this path; these contract tests reference the same type” gives the next agent a route to verification.

The graph must not be presented as a native CC Switch feature. CC Switch’s own scope covers provider, configuration, routing, MCP, Skills, and sessions. The graph is an external context layer, optionally reached through an MCP tool or another project workflow. The CC Switch codebase-context guide explains why that boundary matters after a provider change.

Query Context Before Running the Agent

Querying first prevents a new model from spending its opening turns on broad repository scans. It also prevents the opposite failure: pasting an entire repository index into the prompt and burying the task.

Use a task-shaped query:

Task: change the public invoice status transition
Revision: <commit>
Return:
- defining schema and implementation symbols
- direct and two-hop callers
- generated clients or artifacts
- contract, integration, and migration tests
- owners and relevant decision records
- inferred or missing relationships
Limit: paths connected to the invoice transition

Then reduce the result to a handoff with four blocks:

1. Scope: goal, non-goals, revision, allowed paths, acceptance criteria.
2. Evidence: relevant nodes and paths with source locations.
3. Uncertainty: inferred edges, dynamic registration, external consumers, missing generated artifacts.
4. Verification: focused tests, broader required suites, owners, and approval gates.

The agent should inspect source behind every high-impact edge before changing code. Dynamic imports, reflection, runtime configuration, generated output, and consumers outside the indexed repository can defeat a static graph. Treat a graph as a navigation and impact-analysis aid, not as a substitute for source, tests, or review.

Keep Providers Replaceable

A provider is replaceable only when durable knowledge does not depend on its private transcript or proprietary state. Put repository policy in version-controlled instructions, architecture decisions in maintained records, graph evidence in reproducible artifacts, and task conclusions in a reviewed handoff.

Use these controls:

• Stable schema: keep task packets provider-neutral and avoid vendor-specific reasoning fields.
• Explicit adapters: isolate provider endpoints, protocol conversion, model mappings, and tool quirks.
• Least disclosure: query only facts required for the task and filter sensitive paths before retrieval.
• Provenance: attach revision and source locations to every important relationship.
• Freshness gates: reject or rebuild graph results when their revision cannot be reconciled with the worktree.
• Independent verification: make the destination model reopen source and rerun tests.
• Human ownership: require the responsible team to approve policy, security, and high-impact architectural changes.
• Transfer record: document what was provided, omitted, inferred, and disproved.

Avoid using unified history as the portability mechanism. CC Switch’s unified Codex history guide says it normalizes the model_provider tag so sessions share a list. It also says cross-provider resume may fail when encrypted reasoning can only be decrypted by the original backend. A fresh task packet is more portable and easier to audit than an old session whose assumptions may be stale.

FAQ

What should the graph expose to each provider?

Expose only task-relevant entities, relationships, source locations, revision metadata, test paths, and approved decision records. Omit secrets, raw production data, unrelated proprietary modules, private user information, credentials, and full historical transcripts. Give the provider enough evidence to verify the task, not a default copy of the entire repository graph.

How should sensitive repo facts be filtered?

Classify graph nodes and fields during ingestion, then enforce provider- and task-specific retrieval policies before results enter the prompt. Redact secrets rather than merely hiding labels, preserve an audit log of returned entity IDs, and require approval for protected areas. Also review local CC Switch logs and configuration backups before sharing them; current redaction does not retroactively sanitize older files.

When should teams rebuild the graph?

Rebuild when source, generated artifacts, schemas, dependency manifests, ownership, or relevant architecture documents change. Also rebuild when the task worktree cannot be matched to the graph’s commit, an extractor changes, coverage expands, or verification reveals a missing relationship. For large repositories, incremental refresh is acceptable only when the artifact still records one coherent revision and coverage boundary.

Conclusion

The CC Switch knowledge graph workflow is reliable because it does not ask one tool to own two different problems. CC Switch owns provider access, configuration, and protocol routing. A separate graph owns revision-bound repository relationships with provenance and freshness.

Query that graph before launching the selected agent, reduce results to a task packet, and verify important edges in current source. With those controls, teams can replace Claude, Kimi, Codex, or another provider without claiming that private reasoning or repository comprehension transferred automatically.

A CodeWhale constitution controls how an agent ranks authority, protects selected paths, escalates risk, and verifies completion; a code knowledge graph describes repository entities and relationships for a particular revision. Use .codewhale/constitution.json for governance. Use an external graph for calls, imports, schemas, tests, ownership, and dependency paths. Verify both against current code and live evidence.

This comparison uses Codewhale for the project’s factual spelling while retaining CodeWhale constitution as the target query. It is based on the v0.9.0 configuration documentation and CodeWhale’s public constitution page as checked on July 23, 2026.

Quick Verdict

Do not turn a constitution into a manually maintained architecture map, and do not let a graph decide policy.

Layer	Primary question	Appropriate contents	Authority and freshness
.codewhale/constitution.json	How should Codewhale decide and verify work in this repo?	authority order, protected invariants, branch policy, verification rules, escalation conditions	human-reviewed policy; changes when governance changes
AGENTS.md	How should agents work on this project?	prose instructions, commands, conventions, contribution workflow	human-reviewed instructions; changes with team practice
External code knowledge graph	What repository entities relate at this revision?	files, symbols, imports, calls, tests, schemas, documents, owners	regenerated or incrementally refreshed from evidence
Current source and tools	Is this claim true for the active task now?	checked-out code, configuration, test results, logs, diff	highest practical factual check for the active turn
Opt-in user memory	What durable personal preferences follow the user?	concise preferences across repositories and sessions	user-scoped; not a repo fact database

The split is operational, not semantic hair-splitting. A constitution may require an agent to trace consumers before changing a public API. The graph can return candidate consumers. Current source and tests determine whether the returned path is accurate and whether the change is acceptable.

The same pattern applies beyond Codewhale. AGENTS.md vs Knowledge Graph explains why human-authored instructions and generated repository relationships should keep different owners and refresh triggers.

What a Constitution Controls

Codewhale v0.9.0 documents several authority layers. The bundled constitution is compiled into the binary. A user-global constitution lives under $CODEWHALE_HOME/constitution.json—normally ~/.codewhale/constitution.json—and expresses standing preferences and stop conditions. A repository can add .codewhale/constitution.json for repo-specific authority and prioritization.

The repo-local file can contain:

• an authority order for resolving conflicting sources;
• protected invariants, optionally scoped to path globs;
• branch policy;
• verification requirements before claiming completion;
• escalation conditions for risky or unclear work.

These fields govern decisions. For example, an authority list can place live code and tests above an old handoff. A verification policy can require focused tests and a readback of changed files. A protected invariant can require approval or block writes to matched paths when expressed in the supported object form.

Codewhale’s documentation also establishes limits. Managing the constitution does not alter sandbox, network, trust, shell, MCP, or approval posture. Runtime security controls remain enforced in code. The constitution can tighten behavior or define authority; it cannot grant broader runtime permission.

Most importantly, constitution entries do not establish repository facts. A rule such as “preserve the billing event schema” tells the agent what matters. It does not enumerate the schema’s producers, consumers, generated clients, migration history, or tests. Those relationships must come from current evidence.

The public CodeWhale constitution page summarizes the same three-layer model and says the repo law sits above project instructions, memory, and handoffs. It also preserves the honest boundary: current requests and live tool evidence control factual reporting.

What a Code Knowledge Graph Describes

A code knowledge graph is a structured, queryable view of repository entities and their relationships. For agent work, useful nodes include files, packages, symbols, endpoints, schemas, tests, owners, configuration keys, and architecture records. Useful edges include imports, calls, implements, generates, publishes, consumes, configures, tests, and owns.

The graph should be external and revision-bound in this workflow. Codewhale v0.9.0 does not document a native code graph or repository index. An external tool can produce the graph, while Codewhale queries or receives the relevant evidence through its normal task context and tools.

Revision binding prevents a generated relationship from becoming timeless lore. Every graph view should identify the commit or snapshot from which it was built. It should also preserve provenance:

• parsed imports and definitions can cite exact locations;
• generated-code relationships should name the generator and artifact;
• inferred runtime paths should carry confidence and an explanation;
• decision links should point to dated records and owners;
• stale or unresolved edges should be visible, not silently omitted.

A graph helps answer “what appears connected?” It cannot prove every runtime path, infer every dynamic registration, or decide which behavior a team wants. Source inspection, focused tests, logs, and reviewers remain necessary.

Why Rules Cannot Replace Repository Facts

Rules age differently from code relationships. A verification rule may remain valid for years. A caller list can become stale after one refactor.

Putting repository structure into constitution prose creates three problems. First, changes to the code do not automatically update the rule. Second, reviewers cannot easily distinguish policy from generated observation. Third, an agent may treat a high-authority constitution block as proof even when current source contradicts it.

The opposite mistake is equally risky. A graph can show that a package imports another package, but it should not decide whether direct dependency is forbidden, whether a migration needs security review, or whether the team permits edits on a release branch. Those are governance decisions.

Consider a database migration:

1. The constitution says migrations require rollback steps, focused verification, and owner escalation.
2. AGENTS.md names the approved commands and contribution flow.
3. The graph identifies schema consumers, generated clients, migration files, and contract tests.
4. The task packet selects the relevant evidence for the active revision.
5. Codewhale reads current files, proposes the change, and runs the required checks.
6. A reviewer evaluates the diff and evidence.

Each layer contributes something the others cannot safely replace. Collapsing them into “agent memory” obscures authority and makes stale data harder to detect.

Codewhale’s optional memory feature reinforces this boundary. It is disabled by default and intentionally user-scoped. The documentation recommends project instructions for repo-specific conventions. Personal memory should not carry an unreviewed architecture summary from one repository into another.

How Governance and Understanding Work Together

Connect the layers with explicit gates rather than a single global context dump.

1. Ratify governance. Review .codewhale/constitution.json like policy code. Confirm its authority order, protected paths, branch rules, verification requirements, and escalation owners.
2. Build repository evidence. Generate a module, dependency, test, and ownership graph from a pinned revision.
3. Retrieve by task. Query only the affected relationships and include source locations, confidence, and unresolved edges.
4. Apply the rules. Use the constitution to decide which sources outrank old summaries and which gates the work must pass.
5. Inspect live source. Read the files behind every load-bearing graph path.
6. Verify behavior. Run the required focused tests and any broader contract or integration checks justified by the impact path.
7. Record the result. Preserve the revision, graph version, commands, test output, diff, reviewer, and remaining uncertainty.
8. Refresh separately. Update the graph after code changes; update the constitution only when governance changes.

This sequence keeps the graph useful without granting it policy authority. It also keeps the constitution authoritative without asking humans to maintain a brittle list of repository relationships.

For large Codewhale tasks, the CodeWhale Large Codebase Context guide shows how the same evidence layer stays portable when models or providers change.

FAQ

Can rules conflict with graph evidence?

Yes, but the conflict often reveals a category error. A rule might claim a path is protected while the graph shows the component moved; current source should resolve the location, and an owner should update the rule. A graph might expose a forbidden dependency; the constitution determines escalation or remediation. Never edit governance automatically just to make it agree with generated evidence.

Who reviews constitution changes?

Repository owners should review them with the people responsible for security, release, and the affected protected paths. Treat changes as policy changes: explain the reason, verify the schema, test any mechanically enforced path globs, and require normal code review. A model may draft text, but Codewhale’s constitution setup distinguishes drafting from ratification.

How should stale repository facts be flagged?

Store the source revision, generation time, provenance, and confidence on graph data. Mark the graph stale when the checkout differs, relevant files change, extraction fails, or a current source check contradicts an edge. Block high-impact use until the affected slice is refreshed. Preserve the failed edge and reason so the indexing process can improve.

Conclusion

The Codewhale constitution and a code knowledge graph are complementary because they answer different questions. The constitution governs priority, invariants, verification, and escalation. The graph organizes revision-bound repository facts and dependencies. Current source and tests arbitrate factual claims.

Keep those boundaries visible. Ratify rules with human owners, refresh graphs from code, retrieve only task-relevant evidence, and record verification. If a statement changes when the repository changes, it belongs in the evidence layer—not in constitution prose. If it expresses how the team must decide or verify work, it belongs in governance—not in a generated graph.

A Git worktree isolates a branch, directory, index, and HEAD; a code knowledge graph helps an agent retrieve relationships such as callers, dependencies, tests, and architecture boundaries. They solve different problems. Use worktrees to separate concurrent write state, and use a revision-bound knowledge layer to improve repository understanding before anyone edits.

This distinction matters in tools such as Supacode. Its documentation describes real Git worktrees, a managed directory for each worktree, per-worktree terminal state, and repeatable repository commands. It does not describe worktrees as AI memory, repository indexing, or a knowledge graph. Treating isolation as understanding leaves an agent with a clean directory but no reliable map of the system.

Quick Verdict

Choose the layer according to the failure you need to prevent.

Question	Git worktree	Code knowledge graph
Primary job	Isolate checked-out files and per-worktree Git state	Represent and retrieve repository relationships
Useful for	Parallel branches, separate builds, task-specific terminals	Impact analysis, dependency discovery, test selection
Source of truth	Current checkout and Git metadata	An index derived from a named repository revision
Main risk	Branch drift, duplicated services, conflicting shared resources	Stale, incomplete, or overexposed derived context
Final verification	Diff, status, merge checks, tests	Current source, current tests, and responsible reviewers

The choice is therefore not either/or. A parallel coding workflow often needs both. The worktree controls where an agent may change files. The graph or repository map controls which evidence it should inspect first. Neither layer proves that a patch is correct.

For a broader separation of rules and repository facts, read AGENTS.md vs Knowledge Graph. The same authority principle applies here: a tool can organize work, derived context can guide discovery, and checked-out source remains the final technical evidence.

What Git Worktrees Are Good At

Git defines a worktree as one of multiple working trees attached to the same repository. A linked worktree has its own working directory and per-worktree files such as HEAD and the index, while much repository data and most refs remain shared. This lets a developer check out more than one branch at a time without repeatedly switching the main working directory.

That boundary is concrete and operational. It supports:

• assigning one branch and directory to each agent or task;
• keeping uncommitted changes out of another agent’s checkout;
• running task-specific build artifacts and tests from distinct paths;
• inspecting one branch while another long-running process continues;
• removing a finished linked worktree through Git’s lifecycle commands.

Supacode builds a macOS workflow around this Git mechanism. Its first-worktree guide says each new worktree is backed by a branch and directory, is created under ~/.supacode/repos/<repository-name>/, and receives its own terminal state. Repository commands can start a coding agent, install dependencies, run a dev server, or clean up before archive. These conveniences strengthen process isolation; they do not add semantic understanding of the code.

Worktrees also do not isolate every resource. Git refs are mostly shared, and external resources such as a database, port, cache, cloud account, or package registry can still collide. Teams need unique ports, disposable data, explicit credentials, and cleanup rules where those resources matter.

What Code Knowledge Graphs Are Good At

A code knowledge graph is useful when a task depends on relationships that are expensive or error-prone to reconstruct from filenames alone. It can connect a symbol to callers, an API to implementations, a schema to consumers, a feature to tests, or a module to architectural documentation.

The graph’s value is evidence selection. Instead of giving an agent a large undifferentiated file dump, a query can return a small candidate path:

1. the public entry point involved in the request;
2. the implementation and configuration that govern it;
3. direct and transitive consumers;
4. related tests and generated artifacts;
5. documents or owners that constrain the change.

This layer should be descriptive, not authoritative by itself. Parsers miss dynamic behavior. Generated code may be absent. Runtime registration, reflection, environment variables, and external systems may not appear as static edges. Every retrieved relationship needs confirmation against the exact worktree revision before it influences a patch.

The 1M Context vs Knowledge Graph guide explains the adjacent capacity question: a large context window can hold more text, but it still needs a method for selecting fresh, relevant evidence.

Where Coding Agents Confuse the Two

The most common mistake is assuming that a fresh worktree gives an agent fresh understanding. It gives the agent a clean filesystem view. The agent may still repeat broad searches, read obsolete documentation, miss an indirect consumer, or infer architecture from directory names.

A second mistake is treating a graph as shared task state. Repository facts and task decisions have different lifecycles. “Function A calls function B at commit X” can be shared read-only. “Agent 2 plans to rename B” belongs to that task until reviewed. Mixing the two turns a neutral repository map into a stream of provisional conclusions.

A third mistake is assuming either layer prevents merge conflicts. Worktrees reduce simultaneous changes in one directory, but two agents can still edit the same logical contract on different branches. A graph may reveal overlapping impact paths, but it cannot arbitrate product intent. Ownership and integration order still need human or controlled-agent review.

The Share Repo Context Across Coding Agents guide provides a general context contract for teams that need common evidence without common write permissions.

How to Combine Both Layers

Combine the layers by binding repository context to a commit and keeping each task’s writes local to its worktree.

Start with a base revision. Generate or refresh a read-only module, symbol, dependency, test, and documentation map for that revision. Record the generator version and any known exclusions. Then create one worktree per task from the approved base, with a named branch and an explicit write scope.

Before an agent edits, give it a compact evidence packet: task goal, base commit, relevant nodes and edges, cited source paths, likely tests, and known unknowns. Require the agent to verify every important edge in its current checkout. If the worktree has moved ahead of the graph revision, either refresh the affected slice or mark retrieved context as stale.

During execution, keep these controls visible:

• one owner for changes to each shared public contract;
• separate ports, data, credentials, and services where necessary;
• task-local plans, terminal output, assumptions, and failed experiments;
• read-only access to the shared repository map;
• focused tests in each worktree before integration tests on the combined branch;
• a final diff and impact review at the merge point.

Make the evidence packet reviewable by someone other than the task agent. It should identify the base commit, selected paths, direct relationships, likely tests, and the reason each item was chosen. Reviewers can then reject a stale edge, add a missing consumer, or narrow an overbroad scope before parallel edits begin. That checkpoint turns a helpful repository map into accountable engineering input rather than an opaque prompt attachment.

Supacode’s repository setup, run, and archive commands can automate parts of this lifecycle. For example, a setup command can prepare dependencies or launch an agent, while an archive command can stop task-local infrastructure. Keep context generation explicit and independently versioned unless your own tooling provides it; the reviewed Supacode docs do not claim a built-in repository graph.

FAQ

Can a worktree share graph-backed context safely?

Yes, if the graph is read-only to task agents, scoped to approved repository data, and labeled with the exact commit or content revision it describes. Each agent should verify retrieved paths and relationships in its own checkout. Do not let graph access imply permission to read secrets or write outside the task boundary.

What should not be stored in a knowledge graph?

Exclude secrets, credentials, personal data, unrestricted terminal transcripts, proprietary data outside the approved repository scope, and provisional agent reasoning presented as fact. Task-specific plans, unreviewed conclusions, and ephemeral runtime state should stay with the task unless a deliberate review promotes them into shared documentation.

How should teams audit graph freshness?

Store the indexed commit, generation time, tool version, coverage notes, and failed parses. Compare the worktree’s current commit with the graph revision before every task. Renames, dependency-file changes, schema changes, code generation, and public-interface edits should trigger a targeted refresh or a full rebuild according to measured coverage.

Conclusion

Git worktree vs knowledge graph is a comparison of control plane and understanding layer, not competing implementations. Worktrees isolate branch, directory, index, and terminal workflows. A knowledge graph or structured repository map selects relationship-aware evidence.

Use both when parallel agents must change a large repository: bind shared context to a revision, keep task decisions and writes isolated, and verify every important claim in current source and tests. A clean worktree limits interference. Fresh, reviewable repository context limits guesswork.

Use OpenCode Skills to define repeatable work; use a code knowledge graph to answer what the repository currently contains and how its parts relate. A Skill can require an impact review before a migration, but it should not become a manually maintained list of callers, imports, symbols, and tests. A graph can expose that evidence for a specific revision, but it should not decide the team’s workflow or approval policy.

This distinction matters because both layers may be called “agent memory.” They do different jobs, have different owners, and fail in different ways. OpenCode documents Skills as on-demand SKILL.md instructions. It does not document a native code knowledge graph or a durable semantic repository-memory feature. A graph is therefore an optional external layer, queried through a tool or workflow and verified against current source.

Quick Verdict

The practical split is simple: a Skill says how to work; a graph says what the system appears to be; source and tests decide whether a proposed change is correct.

Layer	Owns	Refresh trigger	Example	Unsafe use
OpenCode Skill	Repeatable procedure, decision gates, commands, evidence requirements	A team changes its workflow	“For API removals, trace consumers, run contract tests, and request owner review.”	Storing a hand-written caller inventory or current schema map
Code knowledge graph	Files, symbols, imports, calls, tests, owners, documents, and typed relationships	Source, configuration, or artifact changes	“These handlers reach this schema and these contract tests.”	Treating inferred edges as unquestioned facts
Current task packet	Scope, commit, acceptance criteria, selected evidence, open risks	The task changes or ends	“Migrate this endpoint only; these consumers are in scope.”	Turning a temporary debugging hypothesis into permanent policy

The existing Context Engineering for OpenCode article covers the full context stack. This page owns the narrower boundary between OpenCode Skills and an external repository graph. For the adjacent distinction between human rules and generated structure, see AGENTS.md vs Knowledge Graph.

What OpenCode Skills Are Best For

OpenCode defines an Agent Skill as a reusable SKILL.md file. The agent sees a list of available Skills and can load the full instruction only when needed. The official discovery paths include project and global .opencode/skills, .claude/skills, and .agents/skills directories. OpenCode also lets a team allow, deny, or require approval for Skill access, including per-agent overrides.

Those mechanics make Skills a good place for procedures that recur across tasks but are too detailed for a root instruction file. A good OpenCode Skill can define:

• when the procedure applies and who may invoke it;
• required inputs, such as a base commit, issue link, or affected public contract;
• the order of exploration, planning, implementation, review, and verification;
• commands that must run and what result would block the change;
• which approvals belong to API, security, data, or release owners;
• a handoff format that preserves paths, assumptions, and unresolved risks.

For example, a public-api-removal Skill can require a search for exports, consumers, samples, and documentation; ask for a dependency path; require compatibility tests; and route the final diff to the API owner. That is procedural knowledge. It remains useful even after package names, symbols, and call paths change.

Skills are also a better fit for controlled access than an oversized instruction document. A destructive migration procedure can be hidden from an exploratory agent, require approval for a planning agent, and be allowed for a designated implementation agent. The procedure is discoverable without making every conversation carry every detailed checklist.

Keep a Skill concise and testable. A rule such as “check the deployment contract before editing generated clients” is actionable. A 700-line document that duplicates source files, package inventories, and incident notes is neither durable procedure nor reliable repository evidence. It is a stale second copy of the system.

What Code Knowledge Graphs Are Best For

A code knowledge graph is useful when the question is relational. Which modules import a schema? Which callers reach a permission check? Which tests cover an exported symbol? Which architectural record explains why a boundary exists? These questions require more than a workflow description.

The graph can model packages, files, symbols, routes, APIs, schemas, tests, owners, and documents as nodes. Typed edges can represent imports, calls, implementations, generation, coverage, ownership, or rationale. A traversal can produce a candidate impact path before OpenCode opens the supporting source.

That gives the agent a useful discovery route, not an automatic answer. Dynamic registration, reflection, configuration, generated artifacts, external consumers, and incomplete extraction can all hide or distort a relationship. A high-impact edge must carry enough provenance to be investigated: the repository revision, extractor version, edge type, location, and whether it was deterministic or inferred.

Graphify is one optional example of this external layer. It turns code and documents into graph artifacts and lets an agent query relationships before reading the underlying evidence. Its value is not that a graph replaces source; it is that the graph preserves structural questions that flat chunks or a huge prompt may hide. The graph must still be refreshed as the repository changes.

The graph should not become a policy engine. It cannot decide whether a risky migration deserves a security review. It can show that a data path reaches a sensitive service, which is evidence the appropriate human-owned rule should use. Likewise, it cannot authoritatively decide that a test suite is adequate merely because a COVERS edge exists.

Workflow Rules vs System Understanding

The easiest way to avoid drift is to give each fact one primary home.

Question	Primary home	Why
What must an agent do before a public schema change?	Skill	It is a team-owned procedure with approval and verification gates.
Which packages depend on the schema now?	Graph plus current source	It is a revision-bound structural observation.
What exact migration is approved this week?	Task packet and issue	It is a temporary, human-scoped decision.
Which build command is mandatory?	AGENTS.md or focused instruction	It is stable project policy rather than a graph relationship.
Did the new patch preserve behavior?	Tests, runtime evidence, and review	No instruction or graph can establish this without verification.

OpenCode’s rules documentation gives AGENTS.md a separate role: project guidance is included in the model’s context, and opencode.json can add instruction files or globs. Rules state team expectations. Skills package an on-demand workflow. A graph provides a structure-aware evidence index. Mixing the layers invites ambiguity: a graph-derived fact pasted into a Skill is likely to age; a procedural exception encoded as an edge has no clear policy owner.

This separation also makes provider changes less fragile. OpenCode supports many model providers and custom endpoints, but choosing another model does not transfer a private chain of reasoning from the old session. What can persist is the repository’s reviewed rule files, versioned Skills, task evidence, and external graph artifact. The new model must still load and verify them in its own context.

How to Combine Both Layers

Combine the layers in a small, auditable loop rather than loading everything by default.

1. Start with the Skill. It states the task category, required constraints, decision owner, and verification sequence.
2. Set the task boundary. Pin a commit, issue, allowed paths, acceptance criteria, and known risks. This prevents an impact query from turning into a repository-wide rewrite.
3. Query structural evidence. Use the graph to locate direct and multi-hop dependencies, tests, ownership, and relevant architecture documents.
4. Open current source. Read the files behind high-impact graph paths. Treat inferred, dynamic, or stale relationships as hypotheses rather than commands.
5. Plan with evidence. Put exact paths, symbols, unresolved edges, and the required tests in the implementation handoff.
6. Edit, test, and review. Run the Skill’s prescribed checks, inspect the diff, and obtain the responsible human approval.
7. Update the right layer. Change the Skill only if the procedure changed; refresh the graph when structure changed; record task conclusions in a durable decision record only when the team accepts them as policy or rationale.

OpenCode can reach an external graph through a local or remote MCP server. Its MCP documentation warns that every server and tool description consumes context, so enable graph tools for the agents or tasks that actually need them. A large global tool catalog can erase the context budget saved by better repository selection.

This pattern provides useful information gain over a generic “add memory” recommendation. It makes freshness observable. A reviewer can ask: Which revision produced this graph result? Which Skill required the query? Which source files confirmed it? Which tests disproved or supported the plan? Those questions turn contextual hints into accountable engineering evidence.

FAQ

Can Skills and graph facts conflict?

They should not own the same fact. A Skill may say “verify every generated client before removing a schema.” The graph may return the current generated-client paths. If a path differs from a Skill example, source state wins for the structural fact and the Skill should be revised only if the procedure itself is wrong. Do not edit the graph merely to make it agree with a prose instruction.

Who should approve shared graph updates?

The team responsible for extraction and data quality owns the graph pipeline; owners of affected packages should review important relationship changes; task owners remain responsible for checking high-risk paths against source and tests. A vendor, model, or autonomous agent cannot inherit that accountability.

What should stay in a Skill instead?

Keep reusable action rules in the Skill: scope checks, approval gates, allowed tools, expected evidence, commands, rollback requirements, and handoff shape. Do not place transient issue state, credentials, generated source dumps, exhaustive symbol lists, or unverified architecture claims there.

Conclusion

OpenCode Skills and code knowledge graphs are complementary because they answer different questions. Skills preserve a reviewable way of working. Graphs preserve queryable, revision-bound relationships. Current source, tests, and accountable reviewers decide whether an edit is safe.

Use a Skill when the team needs a repeatable procedure. Add a graph when repository work repeatedly depends on discovering multi-hop structure. Keep both narrow, preserve provenance, and make every high-impact graph result lead back to source verification rather than treating “agent memory” as an authority on its own.

Macaron long context lets a coding workflow place more repository evidence in one model request; a code knowledge graph makes relationships such as calls, imports, ownership, and test coverage queryable. Use the window to reason over a bounded, known evidence set. Use a graph to discover and connect evidence when the task crosses modules. Use current source and tests to verify both.

The fact boundary matters. Macaron-V1-Coding-Venti lists a 1M context length in its MindLab Research model card and a 1,048,576-position configuration. The official MoL harness reference profiles use 262K context at launch. The frequently repeated 2M figure belongs to MindLab’s LongStraw reinforcement-learning training infrastructure, not to a Macaron-V1 inference guarantee. Treat capacity as a dated deployment setting, not a replacement for repository structure.

Quick Verdict

Use long context when a task already has a small, well-justified set of source files, tests, specifications, and decisions to compare. Use a code graph when you first need to answer which files, callers, consumers, tests, or owners are relevant. Use both for a risky multi-module change: graph-select the evidence, read it in context, then verify the result.

Method	Primary question	Best fit	What it cannot establish
Macaron context window	How much evidence can be present together?	A known subsystem, diff review, distributed contract and test reading	That all relevant evidence was included or used correctly
Lexical or semantic retrieval	Which chunks match this query?	Symbols, errors, exact terms, and concept search	A complete dependency or authority path
Code knowledge graph	Which repository entities relate, and through which typed path?	Impact tracing, callers, imports, schemas, tests, ownership	Dynamic behavior, perfect freshness, or policy decisions
Source and tests	Is the claimed behavior supported now?	Any high-impact plan or change	Nothing can replace current evidence and verification

The broader 1M Context vs Knowledge Graph guide compares this pattern across model families. This page applies it to Macaron-V1’s official 1M model specification and its documented serving caveat.

What Long Context Helps With

Long context is valuable after evidence selection. A coding agent can keep a larger coherent slice of the task together: interface contract, implementation, callers, tests, architecture decision, migration plan, logs, and current diff. This reduces the need to compress every source file into summaries that lose important constraints.

With Macaron-V1, a useful long-context request might contain a pinned commit’s authentication middleware, session model, policy configuration, contract tests, recent incident note, and a targeted acceptance criterion. The agent can compare the materials in one working view and explain contradictions without repeatedly reloading fragments.

Long context also helps with:

• reviewing a known migration path across schema, generated client, consumers, and release notes;
• comparing a proposed patch against multiple invariants and test suites;
• retaining a bounded tool trajectory while synthesizing a plan;
• reading a subsystem where the relevant files and documents have already been identified;
• checking whether a diagnosis accounts for both implementation and operational evidence.

The model card’s 1M context value should be read narrowly. It describes the checkpoint configuration. The MoL harness’s documented 262K launch setting describes a provided self-hosted profile. Hosted service behavior may differ again. A team trial should record the exact model, endpoint or harness, context setting, system instructions, tool configuration, prompt size, cache behavior, and repository commit. Without this, “Macaron handled our large codebase” is not reproducible.

Long prompts are not automatically better prompts. Unneeded files, duplicate definitions, stale documents, generated code, vendor code, and tool descriptions can dilute the evidence that matters. A larger window can reduce some retrieval pressure, but it cannot determine authority or make the model notice every important relation.

What Code Knowledge Graphs Add

A code knowledge graph preserves explicit repository structure. It turns questions such as “who consumes this API?” or “which tests reach this schema?” into traversals over named entities and typed relationships.

Useful nodes include packages, files, symbols, routes, APIs, schemas, configuration, tests, owners, and design documents. Useful edges include imports, calls, implementations, generated-from, covers, owned-by, and rationale-for. The result is not merely a ranked set of chunks; it is a candidate explanation of why the evidence belongs together.

That matters when a query is structural rather than textual. Searching for a field name may find its declaration and many incidental mentions. A graph can show that the field is serialized by one adapter, consumed by three clients, validated by a contract suite, and covered by a deployment flag. The agent can then read those primary files together in its context window.

Graphs add three controls that large prompts lack by default:

1. Relationship visibility. An impact path can be inspected and challenged rather than inferred from a pile of files.
2. Provenance and freshness. Important graph results can name the source locations, repository revision, extraction method, and refresh date.
3. Repeatable selection. Different agents or model providers can query the same maintained evidence layer instead of starting discovery from scratch.

Graphify is an optional external implementation of this pattern. It can generate code and document graph artifacts that guide an agent toward structural evidence. It is not a claim that Macaron or a separately configured HCP SDK includes a native code graph. An external graph must be refreshed and its important edges verified against current source.

Repository Tasks That Need Structure

Structure matters when the consequence of a change lies outside the first file the model opens.

Task	Candidate relationship path	Why a graph helps
Remove a public field	schema → serializers → generated clients → consumers → examples → contract tests	Surface matching alone can miss generated or downstream users
Change an authorization rule	entry point → middleware → policy → session store → error tests → audit owner	The behavior spans code, configuration, and responsibility boundaries
Split a package	exports → imports → build graph → package owners → release artifacts	The task is about dependency direction, not one code snippet
Diagnose a delayed job	schedule → queue → worker → retry policy → state write → telemetry	Runtime behavior often crosses vocabulary and modules
Modernize a database call	query helper → transaction boundary → callers → migration → integration tests	Local edits can change ordering, consistency, or rollback behavior

For each path, the graph gives a starting hypothesis. Dynamic registration, reflection, runtime configuration, feature flags, generated code, and external integrations may still be omitted. The model should mark uncertain edges and request the source or owner evidence needed to resolve them.

This is a better test of repository understanding than asking whether a model can summarize a large directory. A useful response identifies the expected path, distinguishes confirmed and inferred relationships, and proposes the tests that can falsify its plan.

How to Combine Context Windows and Graphs

Use the two layers in sequence rather than forcing a false choice.

1. Pin the task. Record objective, acceptance criteria, base commit, allowed write paths, and reviewers.
2. Select the evidence neighborhood. Search and graph-traverse direct dependencies, multi-hop consumers, tests, owners, configuration, and relevant decisions.
3. Verify the path. Open raw source behind high-impact graph edges. Note stale, dynamic, or unconfirmed behavior.
4. Build the context packet. Include only the current files and documents that explain the task, plus an explicit unknowns list.
5. Reason with Macaron. Ask for a minimal plan, cited evidence, change risks, test rationale, and a boundary between fact and inference.
6. Edit under control. Restrict writes to approved scope, review the diff, run focused and broader checks, and obtain owner approval.
7. Refresh after structure changes. Update the graph after accepted refactors, symbol moves, generated-artifact changes, or dependency rewiring. Do not turn temporary task notes into permanent graph facts.

MindLab’s separately published HCP SDK can standardize configuration inputs such as Skills, resources, MCP, hooks, workspace staging, and provider settings. Its public documentation describes a wrapper around other runtime components, not a Macaron checkpoint feature, agent, or repository-memory database. Use that configuration role to make a workflow repeatable, while keeping repository intelligence in source-controlled artifacts and an independently maintained graph.

The combined workflow yields a practical division of labor: the graph reduces repeated discovery, the context window holds the selected evidence for synthesis, and current source plus tests constrain the outcome. This is more reliable than assuming a long prompt or a graph query is self-validating.

FAQ

What 2M context claims should be verified?

First verify what the number measures. For Macaron-V1-Coding-Venti, the official model card and configuration support a 1M model-context specification. MindLab’s LongStraw materials describe 2M-plus reinforcement-learning training infrastructure. They do not establish a 2M production inference window for Macaron-V1. Also verify the actual endpoint or self-hosted harness setting; MindLab’s reference MoL profiles use 262K.

Can graph retrieval miss important files?

Yes. A graph can miss dynamic behavior, unsupported language features, generated files, stale documentation, external services, or an incorrectly inferred edge. Treat traversal as evidence selection, record provenance and revision, inspect high-impact source, and sample the graph against known changes. Retrieval failure is an engineering risk to measure, not a reason to discard structure entirely.

When should teams use both approaches?

Use both when a task spans multiple packages or artifacts and the selected evidence still fits comfortably inside the actual deployment context budget. A graph is most useful before the model knows the relevant neighborhood; long context is most useful after the neighborhood is justified. For a small, known, single-file change, direct source reading and focused tests are usually cheaper.

Conclusion

Macaron context vs knowledge graph is not a contest between a large model window and repository structure. A 1M Macaron-V1 specification can make it easier to synthesize a known body of evidence. A graph can make relationship paths, provenance, and repeated discovery more explicit. Neither proves a patch is correct.

Use a graph to select and explain structural evidence, Macaron to reason over the selected current material, and source inspection, tests, and responsible reviewers to validate the change. Keep the 2M LongStraw training claim separate from the Macaron-V1 inference question.

For the model-specific repository trial, use the Macaron-V1 large-codebase test plan. For constructing and maintaining the bounded evidence packet, continue with Macaron context engineering.

A one-million-token context window expands how much evidence a model can receive in one request; a code knowledge graph changes how repository evidence is selected and connected. Use long context for a bounded body of primary material, retrieval to select likely evidence, and a graph when the task depends on calls, imports, ownership, or other relationships. None of the three proves repository understanding on its own.

The practical question is not which technology wins. It is whether the workflow can locate current evidence, preserve the relationships that matter, and verify the answer against source and tests. That distinction prevents a large context limit from becoming an excuse to dump an entire repository into every prompt.

Quick Verdict

The safest default is a hybrid workflow: use a graph or other index to identify a bounded evidence neighborhood, then let a capable long-context model read the relevant source, tests, specifications, and task history together.

Context method	What it changes	Strong fit	Main failure mode
1M context	Maximum material available in one request	Dense review of a known set of files and documents	Important evidence is present but not used correctly
Lexical or semantic retrieval	Which chunks enter the prompt	Exact symbols, errors, concepts, and document search	The necessary chunk never enters top-K
Code knowledge graph	Which entities and relationships can be traversed	Impact paths, callers, imports, implementations, ownership	The graph is stale, incomplete, or contains a wrong inferred edge

These layers answer different questions. Context capacity asks, “How much can the model receive?” Retrieval asks, “Which pieces look relevant?” A graph asks, “How are these entities connected?” AI repository understanding requires all three questions to be handled in proportion to the task.

For the adjacent distinction between human rules and generated structure, see AGENTS.md vs Knowledge Graph. The existing GLM-5.2 context-window comparison applies the same boundary to one model.

What 1M Context Helps With

A million-token window is a real current capability, but the exact number belongs to a specific model and surface. As verified on July 17, 2026, OpenAI documents 1,050,000 tokens for gpt-5.6-sol; Anthropic documents one million tokens for models including Claude Opus 4.8 and Claude Sonnet 5; Google documents a 1,048,576-token input limit for gemini-2.5-pro.

Those limits make several long context coding tasks more practical:

• comparing a specification with several implementations and their tests;
• reviewing a migration whose behavior spans code, schema, fixtures, and logs;
• keeping a long agent trajectory with tool results available for synthesis;
• reading a bounded subsystem without prematurely compressing every file;
• checking whether a patch satisfies several distributed constraints at once.

Long context is especially useful after the evidence set is known. If a team has already identified the authentication package, its callers, contract tests, relevant decision record, and deployment rule, one request can let the model reason across them without fragmenting the task into many disconnected summaries.

Capacity also reduces some retrieval pressure. A workflow can include more neighboring files and preserve more local detail instead of forcing a retriever to pick only a handful of chunks. Google’s long-context guidance nevertheless recommends omitting unnecessary tokens and notes that longer inputs generally increase time to first token. More room is useful; filling every available position is not the goal.

What Long Context Still Misses

Maximum input length is not the same as effective use of every token. A model may have the evidence and still miss its relevance, confuse two similar definitions, or fail to connect facts separated across modules.

Historical peer-reviewed evaluations explain why teams should test effective context rather than trust the limit alone:

• NoLiMa removed easy literal overlap between questions and hidden evidence. In its 2025 model set, performance degraded as context grew, showing that exact “needle” retrieval can overstate semantic long-context use.
• LongCodeU evaluated code-unit perception, within-unit understanding, cross-unit relationships, and documentation. Across its nine tested models, performance dropped sharply beyond 32K, and inter-code-unit relationships were the hardest category.
• RULER extended simple needle tests with multiple needles, multi-hop tracing, and aggregation, exposing performance gaps that a basic exact-retrieval test missed.

These results do not score the current 2026 models named above. They establish a better evaluation standard: a model’s published window is a capacity claim, while effective repository reasoning must be measured on the model version, prompt, tools, and codebase actually used.

A million token codebase dump also lacks automatic authority. Old generated files, vendored code, duplicated definitions, obsolete architecture notes, and irrelevant test fixtures can all fit beside current evidence. The model still needs revision boundaries, source priority, and a way to distinguish facts from hypotheses.

Retrieval vs Code Knowledge Graphs

Retrieval and graphs both reduce the evidence passed to the model, but they preserve different signals.

Lexical search is strong when the query contains an exact symbol, route, error code, or configuration key. Semantic retrieval can find conceptually similar text when vocabulary differs. Combining them improves coverage, but both usually return ranked chunks rather than an explicit dependency path.

Retrieval can fail before generation. Anthropic’s Contextual Retrieval report explains that ordinary chunking may remove the context needed to retrieve a passage. In its disclosed multi-domain evaluation, contextual embeddings, BM25, and reranking reduced top-20 retrieval failures, but did not remove them. Those percentages should not be transferred to a codebase or to Graphify; the durable lesson is that chunk boundaries, query wording, embedding choice, ranking, and top-K all affect recall.

A code knowledge graph instead represents entities such as files, symbols, APIs, tests, schemas, owners, and design documents, then connects them through typed edges. Peer-reviewed systems including RepoGraph and CodexGraph use repository graphs for navigation and structure-aware retrieval. Their results show that graph-guided context is a credible design pattern, not that every graph implementation wins on every repository.

Graphify documents a similar separation between deterministic and inferred evidence. Its AST pass emits structural relationships with provenance, while semantic relationships can be marked INFERRED or AMBIGUOUS. Its report and query artifacts can guide an agent toward current files, but Graphify does not replace raw-source inspection, tests, permissions, or human approval.

The useful pattern is therefore graph-selected raw context: traverse the likely impact path, open the source behind important nodes and edges, include the relevant evidence in the model window, and verify behavior.

Repository Tasks That Need Structure

Structure matters most when answering the task requires more than locating a matching string.

Repository task	Evidence path that should be explicit
Change a shared schema	schema → generated clients → consumers → contract tests → deployment order
Replace an authentication method	entry points → middleware → policy checks → session storage → failure tests
Remove a public API	exports → callers → documentation → examples → downstream packages
Diagnose an intermittent job	scheduler → queue → handler → retry policy → state writes → telemetry
Split a package	imports → interfaces → ownership → build graph → release boundaries

For these tasks, a flat repository dump may contain every relevant file while hiding why those files belong together. Retrieval may find the target symbol but miss a caller whose vocabulary differs. A graph can make the candidate path explicit, but dynamic registration, reflection, generated behavior, runtime configuration, and external consumers may still escape extraction.

Use a relationship-aware workflow:

1. Pin the task to a commit and define the allowed repository scope.
2. Query or inspect direct neighbors, multi-hop dependencies, related tests, and current owners.
3. Open the raw source behind every high-impact relationship.
4. Add the selected source, specifications, and test evidence to the working context.
5. Mark dynamic or inferred paths as hypotheses.
6. Run focused tests, broader contract checks, and owner review.

This workflow converts a graph from an attractive map into an auditable evidence selector.

Limits and Cost Trade-Offs

Every approach moves cost rather than eliminating it.

Long prompts consume input capacity, add latency, and may cost more under provider-specific rules. Repeatedly sending the same large evidence set can benefit from caching, but caching does not improve a poor selection. Retrieval adds indexing, query, and reranking work. A graph adds extraction, storage, query design, and refresh obligations.

Measure the whole workflow rather than one token number:

• answer or patch correctness on representative private tasks;
• coverage of the expected files, dependencies, and tests;
• false or unsupported relationship claims;
• uncached input, cached input, output, and reasoning tokens;
• tool calls and time to first useful result;
• index construction and refresh time;
• reviewer corrections and escaped regressions.

Graph freshness is a hard boundary. Record the repository commit or snapshot used to build the index. Refresh after symbol moves, public-contract changes, dependency rewiring, generator updates, and accepted structural patches. Verify high-impact graph edges against the current worktree.

A graph is unnecessary when the task is small, the evidence set is already known, relationships are shallow, and a direct source read plus focused tests is cheaper than maintaining an index. Conversely, a giant prompt is wasteful when repeated work begins by rediscovering the same architecture and dependency paths.

No universal break-even point exists. Run the full-context, retrieval, graph, and graph-plus-source variants on the same commit and tasks before standardizing a team workflow.

FAQ

Should teams index everything first?

No. Start with repositories or subsystems where repeated impact tracing and cross-file discovery create measurable review cost. Exclude generated, vendored, secret, or irrelevant material deliberately. Expand coverage only when missed relationships justify the additional indexing and refresh burden.

How should context costs be measured?

Record the exact model ID, date, prompt size, cache status, reasoning setting, output tokens, tool calls, latency, and index-refresh work. Pair those numbers with correctness, evidence coverage, and reviewer corrections. A cheap wrong patch or an expensive correct summary is not a useful comparison by itself.

When is a graph layer unnecessary?

Skip it for a small, stable project; a single-file task; a known evidence packet; or an occasional question answerable through exact search and tests. Add a graph when structural queries recur, relationships span many modules or artifacts, and the team can keep the index aligned with the source revision.

Conclusion

The 1M context vs knowledge graph decision is not a choice between “reading everything” and “using structure.” Long context supplies working capacity. Retrieval selects likely evidence. A code knowledge graph preserves navigable relationships. Current source and tests determine whether the resulting claim is true.

Use a long window directly when the evidence is bounded and already known. Add retrieval when the corpus is larger than the task. Add a graph when repeated work depends on multi-hop structure. For high-impact repository changes, let the graph select candidates, let the model read the underlying evidence, and let tests and responsible owners approve the result.

AGENTS.md should carry human-authored rules; a code knowledge graph should carry generated repository relationships; task-local context should carry the current objective and evidence. These layers are complementary. A reliable coding agent context design keeps their authority, refresh cycle, and audit trail separate instead of treating any one layer as complete project memory.

This division answers a practical problem for teams using Qoder CLI or another coding agent: where should a fact live, who should maintain it, and what must be rechecked before an edit? The answer depends less on file format than on whether the information is policy, observed structure, or a temporary task decision.

Quick Verdict

Use AGENTS.md for stable instructions that people intend the agent to follow. Use a code knowledge graph for refreshable observations derived from source, tests, and project artifacts. Put issue scope, acceptance criteria, selected files, and current hypotheses in a task packet that expires when the work ends.

Layer	Best content	Update mechanism	Authority	Typical failure
AGENTS.md	Commands, conventions, ownership, restrictions, review rules	Human review and commit	Team policy, subject to instruction precedence	Stale, vague, conflicting, or oversized prose
Code knowledge graph	Symbols, imports, calls, implementations, tests, owners, rationale links	Rebuild or incremental refresh	Indexed evidence for a repository snapshot	Missing, stale, or incorrectly inferred edges
Task-local context	Objective, allowed scope, evidence packet, decisions, open questions	Created and revised during one task	Current task contract	Hidden assumptions or conclusions that outlive their evidence

The comparison is therefore not “text file versus database.” It is human intent versus generated structure versus temporary working state. The companion 1M Context vs Knowledge Graph guide explains how these layers interact with model capacity and retrieval.

What AGENTS.md Is Best For

The open AGENTS.md specification defines a plain Markdown instruction file with no required fields. It can document build commands, testing steps, code conventions, repository orientation, and other guidance. The closest applicable file wins when scoped instructions conflict, while explicit user prompts take precedence.

That makes AGENTS.md a good operating contract. Useful entries include:

• authoritative build, format, test, and release commands;
• package ownership and escalation paths;
• generated-file rules and the location of their source templates;
• compatibility, security, and review requirements;
• links to maintained architecture decisions;
• boundaries on files, tools, data, and external systems;
• the evidence required before a task is considered complete.

Write rules as actions that a reviewer can verify. “Run the contract suite after changing the public schema” is stronger than “be careful with compatibility.” “Do not edit generated clients; change the schema and rerun the generator” identifies both the prohibition and the approved path.

Qoder CLI documents AGENTS.md as part of its static memory system. Its current memory guide describes user, project, local, and focused-rule scopes, along with /init and /memory for initializing and inspecting memory. That is a Qoder memory feature, not proof that the file contains current repository relationships.

Keep the root file concise. Import or link to approved architecture and testing documents instead of pasting a codebase manual into every session. Secrets, transient logs, speculative debugging notes, and full source dumps do not belong in shared instructions.

What Code Knowledge Graphs Are Best For

A code knowledge graph is useful when the question is relational: what calls this handler, which modules depend on a schema, what tests cover a symbol, or which decision record explains a boundary?

The graph can represent packages, files, symbols, APIs, schemas, tests, owners, and documents as nodes. Typed edges can represent imports, calls, implementations, generation, coverage, ownership, or rationale. A traversal can then select a candidate impact path before the model opens current source.

This pattern has peer-reviewed support. RepoGraph was evaluated as a repository-level navigation layer across multiple software-engineering systems. CodexGraph uses a graph database and model-generated graph queries for structure-aware repository retrieval. Those studies establish code graphs as a credible context architecture; they do not prove that every graph implementation is accurate or that graphs always outperform lexical or semantic retrieval.

Graphify documents a related provenance boundary. Its Tree-sitter pass labels deterministic structural observations as EXTRACTED, while semantic relationships can be marked INFERRED or AMBIGUOUS with confidence. Its GRAPH_REPORT.md and graph.json outputs can guide discovery, but an inferred edge remains a hypothesis until source or runtime evidence confirms it.

A graph is therefore an evidence index, not a new source of truth. It should identify the repository revision it describes, expose the origin of important nodes and edges, and send the agent back to raw files and tests for high-impact decisions.

How Task Context Fits Between Them

Task-local context connects stable rules to repository evidence for one bounded piece of work.

A useful task packet contains:

• the issue, desired outcome, and acceptance criteria;
• the base commit, repository scope, and allowed write paths;
• relevant instruction files and architecture decisions;
• selected source files, tests, and graph paths;
• known risks, assumptions, and unresolved questions;
• the responsible owner for security, API, data, or deployment decisions;
• the commands that will verify completion.

This content changes too quickly for root instructions and is too intentional to derive from a graph. A graph may show that three consumers depend on an API, but it cannot decide which consumer is in scope for today’s migration. AGENTS.md may require backward compatibility, but it cannot determine whether the proposed adapter satisfies the current issue.

Treat task hypotheses as temporary. If a finding becomes a durable design decision, review it into an architecture decision record. If it becomes a stable workflow rule, review it into AGENTS.md. If it describes current structure, refresh the index. Do not append every result to an ever-growing “memory” file.

This separation also improves handoffs. A planning agent can return a compact evidence packet with file and relationship references. An implementation agent can verify those references in its current worktree. A reviewer can distinguish inherited policy, generated observations, and task-specific judgment rather than receiving an undifferentiated summary.

Layered Context Design for Qoder CLI

Qoder CLI can serve as the working agent while the three layers retain separate ownership.

1. Load human rules. Maintain concise project guidance in AGENTS.md and focused Qoder rule scopes. Use /memory to confirm which instructions are available when nested rules matter.
2. Pin the task. Record the base commit, objective, acceptance criteria, allowed paths, and required reviewers.
3. Select structural evidence. Use current source search and, where justified, an independently maintained code graph to locate callers, dependencies, tests, and related documents.
4. Verify before planning. Open the raw files behind important results. Mark dynamic registration, runtime configuration, external consumers, and inferred graph edges as uncertain.
5. Build an evidence packet. Pass exact paths, symbols, relationship paths, constraints, and expected verification to the agent or Subagent performing the work.
6. Test and reconcile. Run the required checks, inspect the diff, resolve contradictions, and update the layer whose content actually changed.

Qoder CLI does not need to own the graph for this design to work. The graph can come from Graphify or another approved external system, while Qoder CLI reads the selected evidence and performs the task. Do not attribute Graphify extraction, graph traversal, or graph freshness to Qoder.

The forthcoming Qoder CLI context-engineering guide owns the detailed workflow. The Qoder CLI large-codebase guide explains why rule files alone become insufficient as dependency paths widen.

Limits and Trade-Offs

Every layer can drift, and adding layers increases maintenance rather than removing it.

AGENTS.md can contradict a nested rule, import an obsolete document, or become too broad to guide a specific change. A graph can omit dynamic behavior, misresolve a call, preserve an old generated client, or infer a relationship that the source does not support. A task packet can carry a confident but incorrect conclusion from one worker to the next.

Use a separate audit for each failure mode:

1. Instruction audit: confirm owners, scope, precedence, commands, and linked documents.
2. Graph audit: record the commit, extractor version, provenance type, unresolved edges, and refresh event.
3. Task audit: confirm objective, allowed changes, evidence locations, assumptions, tests, and decision owner.
4. Source audit: check high-impact paths against the current worktree and runtime configuration.
5. Outcome audit: review the diff, test results, external contracts, and residual risks.

Avoid conflict by assigning each fact one primary home. A test command belongs in instructions; a call edge belongs in the graph; a temporary migration exception belongs in the task packet. Other layers may link to that fact, but should not maintain competing copies.

The graph may be unnecessary for a small repository or a known single-file change. A detailed task packet may be unnecessary for a harmless spelling fix. Layering should follow risk and repeated discovery cost, not a universal template.

FAQ

Can teams use both without conflict?

Yes, if authority is explicit. Let AGENTS.md define policy and tell the agent when to consult structural evidence. Let the graph describe a named repository snapshot. Let the task packet choose the current scope. When they disagree, verify source state and route policy changes through the human owner instead of asking the model to invent a winner.

Who owns generated context quality?

The team operating the index owns its freshness, coverage, provenance, and failure handling. Package owners should review important structural paths; platform teams can maintain extraction and refresh automation; task owners must verify high-impact results. The graph vendor or model cannot absorb repository accountability.

How should context layers be audited?

Audit them independently and together. Review instructions like code, validate graph samples against source, and require task handoffs to cite paths, symbols, commits, tests, and unresolved assumptions. Then run representative repository tasks to measure missed dependencies, unsupported relationships, reviewer corrections, and regressions.

Conclusion

AGENTS.md vs knowledge graph is a boundary question, not a winner-take-all comparison. Human-maintained instructions state how work should proceed. Generated graphs expose how repository entities appear to relate at a specific revision. Task-local context defines what the team is trying to accomplish now.

Use all three when repository risk and repeated discovery justify them. Keep their owners and refresh cycles separate, preserve provenance, and verify high-impact claims against current source and tests. A context layer is trustworthy only when a reviewer can identify where its claim came from, when it was refreshed, and who is accountable for acting on it.

pxpipe makes an important point about AI coding cost: the same bulky context can sometimes be carried more cheaply as images than as text. That can help long agent sessions, but it does not tell the agent which repository facts matter or how modules depend on one another. Context efficiency and repository understanding are related operational problems, not the same capability.

The practical goal is not to maximize the amount of code placed in a context window. It is to supply the smallest trustworthy evidence set that supports the task, preserve exact details, and verify the resulting change.

Why pxpipe Became Interesting

The independent teamchong/pxpipe project intercepts supported model requests and renders selected large text blocks as dense PNG images. Its current documentation focuses on Claude Code, where Anthropic officially allows requests to be routed through a proxy using ANTHROPIC_BASE_URL.

The idea is attractive because model input is not priced only by human-visible information. Text and images use different tokenization paths. A dense tool result or old conversation history may occupy fewer visual tokens after rendering, provided the target model can read the page well enough.

pxpipe defaults to Claude Fable 5. Anthropic confirms that Fable 5 supports vision and is available in Claude Code. The pxpipe project reports that Fable reads its dense render profile more reliably than other models it tested. This is project evidence, not an Anthropic endorsement of pxpipe.

The project also publishes measurements instead of presenting compression as free. Its own SWE-bench Lite pilot reports 10 of 10 tasks completed in both arms and 65% smaller measured requests with compression. Its larger Pro sample reports 14 of 19 resolved with pxpipe and 15 of 19 without it. Those small, maintainer-run results support a pilot hypothesis: request size can fall without an obvious collapse in task completion. They do not establish universal parity or better coding performance.

pxpipe also documents the uncomfortable part. Image context is lossy. Dense prose and broad state may survive while a hexadecimal value, identifier, or name is silently reconstructed incorrectly. That honesty makes the project useful as a case study in context engineering, even for teams that never deploy it.

The Cost Problem in Code Context

Coding agents consume context through more than source files. System instructions, tool schemas, repository rules, file reads, command output, test failures, diffs, plans, and old conversation turns all occupy the working request.

Long tasks create several kinds of waste:

• the client resends stable instructions and tool definitions;
• the agent reopens files it inspected earlier;
• command output contains repeated or irrelevant lines;
• old history stays available after its exact wording stops mattering;
• broad repository reads include generated, vendored, or unrelated code;
• failed trajectories remain in the transcript.

Compression can reduce the footprint of some of this material. It cannot decide whether the material should have been loaded in the first place.

That distinction affects cost measurement. A project can report fewer transmitted tokens while the agent takes more turns, rereads exact data, or requires more human review. Prompt caching can also change the economics. Anthropic’s token-count documentation says counts are estimates and that Fable 5 uses a newer tokenizer than older Claude generations. Teams should measure the same current workload under the exact model and client instead of applying a headline percentage.

The cost unit that matters is accepted work, not a compressed request. A useful trial tracks total provider cost, latency, successful tests, review time, corrections, re-fetches, and recovery from failures.

Why Cheap Context Is Not the Same as Understanding

Repository understanding requires selection and relationships. A model needs to know not only that a file contains a matching string, but also whether that file owns the behavior, which callers depend on it, which tests represent the contract, and which design rule constrains the change.

Consider a shared type used by an API, a queue consumer, generated clients, and analytics. A compressed dump of all matching files may be cheaper than raw text. It still does not label the authoritative schema, identify runtime consumers, or explain why one field cannot change.

More context can even make reasoning harder. Generated code, fixtures, duplicated implementations, stale documents, and vendor directories compete with the relevant interface. A one-million-token window is capacity, not prioritization.

The same boundary applies to memory. Fable 5 supports compaction and a memory tool in supported harnesses, but those features do not automatically create a durable model of a repository. A conversation summary is not a dependency graph. An old tool result rendered as an image is not a maintained architecture record.

For exact work, cheap but lossy context can create hidden cost. The pxpipe project reports that dense identifiers can be misread without an error signal. A plausible wrong path or hash is more dangerous than an explicit “not found” because the agent may act on it. Keep code to be edited, commands, IDs, versions, numerical limits, and acceptance criteria in text or re-read them from the source.

Where Code Knowledge Graphs Help

A code knowledge graph addresses selection by modeling entities and relationships before the model consumes task-specific evidence. Graphify can provide a reusable map across source code and project documents.

The graph can answer questions that compression does not:

• Which modules import or call this symbol?
• Which tests and documents connect to this subsystem?
• What path links the requested feature to storage?
• Which entities belong to the same architectural community?
• Which relationships were extracted directly and which were inferred?

That map lets the agent open a smaller set of authoritative files. Compression may then be unnecessary for short tasks or useful only later, after test logs and history accumulate.

Graphs are not perfect understanding either. Static analysis can miss reflection, runtime wiring, feature flags, external repositories, and generated behavior. Documents can be stale. Inferred edges can be wrong. Graph results should include provenance and point back to source evidence.

The durable workflow is layered:

1. Query project structure.
2. Open the authoritative source and current documentation.
3. Keep exact constraints as text.
4. Compress only older or bulky gist-level material.
5. Verify the patch with tests, diff review, and architecture ownership.

The Graphify knowledge-graph guide explains the structural layer. The broader pxpipe vs Graphify comparison owns the product-selection decision once that page is live.

Practical Limits to Verify

Start with lifecycle. pxpipe’s npm package and default branch were still changing in mid-July 2026, but its maintainer said they could not promise responses or reviews for all issues and pull requests. Pin the tested version and keep a bypass path.

Then test model compatibility. pxpipe’s built-in default is Fable 5; other models are opt-in because the project reports weaker dense-image results. A model update can change image reading, token accounting, safeguards, or request behavior.

Review privacy and trust boundaries. A local proxy still forwards requests upstream. The project has open reports concerning failed-request body logging, relocated system material, safeguard refusals, and inherited proxy environment variables affecting child processes. Treat these as issues to reproduce against the installed version, not as proof that every deployment fails.

Finally, separate measured and inferred value. Record:

• original versus transformed request tokens;
• cached and uncached input;
• total session cost and turns;
• exact-string mistakes;
• re-read and rehydration calls;
• tests passed and hidden regressions;
• human review minutes;
• proxy errors and safeguard refusals;
• repository files loaded before and after structured retrieval.

This evidence shows whether compression reduces total work and whether a graph reduces unnecessary discovery.

FAQ

What context should be compressed first?

Start with large, repeated, token-dense material whose exact wording no longer matters: old narrative history, verbose logs, completed tool output, or repeated documentation. Do not start with source code about to be edited, commands, secrets, hashes, paths, versions, numerical constraints, or acceptance tests.

When does compression hide useful structure?

Compression hides structure when files and relationships are flattened into pages without labels for ownership, calls, imports, tests, or provenance. It also creates risk when visually similar characters matter. Use search or a code graph to select evidence, and preserve exact source links for verification.

How should teams compare cost savings?

Run repeated tasks from the same repository commit with the same model, client, permissions, prompt, and tests. Compare total cost per accepted task, not one request. Include latency, turns, re-fetches, failures, review time, and regressions. Label project-published benchmark numbers as project evidence.

Conclusion

pxpipe is interesting because it turns context cost into a measurable engineering problem. Its project evidence suggests that Fable 5 can read enough dense imaged context to reduce request size on some Claude Code workloads, while the documented exact-string failures prevent treating the representation as lossless.

The larger lesson is that cheap context is not repository understanding. Use structured project knowledge to identify what matters, native text for exact evidence, compression for suitable bulk, and tests plus human review for acceptance. Optimize the whole task, not only the number printed beside one request.

pxpipe and Graphify solve different parts of the AI coding context problem. pxpipe reduces the token footprint of bulky context already being sent to a model by rendering selected text as images. Graphify builds reusable structural knowledge about a repository. Choose by the bottleneck: request cost and repeated history favor pxpipe; dependency paths and project understanding favor Graphify; some teams can use both.

The comparison is not a contest between two interchangeable indexes. pxpipe is an independent proxy with a lossy representation. Graphify is a project knowledge layer. Neither removes the need to inspect source code, run tests, and review architecture-sensitive changes.

Quick Verdict

Use pxpipe when your agent repeatedly sends large, token-dense material and the older material can tolerate gist-level recall. Use Graphify when the agent needs to ask structural questions such as which modules depend on an interface, which tests cover a path, or how code and design documents connect.

Decision factor	pxpipe	Graphify
Primary job	Reduce the request footprint of bulky context	Preserve reusable repository structure
Representation	Dense PNG pages plus selected text anchors	Entities, relationships, paths, communities, and provenance
Works on	Context the client already sends	Code, documentation, and project artifacts that are indexed
Exactness	Imaged text is lossy; exact values need text or re-reading	Graph results still require source verification
Strong fit	Old history, repeated tool output, dense logs	Navigation, impact analysis, dependency and ownership questions
Main risk	Silent visual misread, proxy compatibility, logging	Stale or incomplete relationships and overtrusted inference

The safest design uses each layer for its actual job. A graph can help select relevant evidence. A compression proxy can reduce the cost of carrying bulky, gist-tolerant evidence through a long session. Exact edit targets, commands, identifiers, and acceptance criteria should remain connected to their original source.

What pxpipe Tries to Solve

The canonical teamchong/pxpipe repository describes pxpipe as a local proxy that transforms selected large input blocks into PNG images before forwarding a request. It can image system and tool documentation, large tool results, and older history while leaving recent turns and ineligible material as text. It compresses the request, not the model response.

Claude Code officially supports the ANTHROPIC_BASE_URL environment variable for routing requests through a proxy or gateway. pxpipe uses that transport path, but it is not an Anthropic product or official Claude Code integration.

The project defaults to Claude Fable 5 because its maintainers report better dense-image reading from Fable than from the other models they evaluated. Anthropic independently confirms that Fable 5 supports vision and is available in Claude Code. That establishes technical compatibility, not independent validation of pxpipe’s quality or savings.

The project reports substantial reductions on its own traffic and small paired tests. Its SWE-bench Lite pilot reports 10 of 10 tasks resolved in both compressed and uncompressed arms, with 65% smaller measured requests in the compressed arm. Its SWE-bench Pro expansion reports 14 of 19 tasks resolved with compression and 15 of 19 without it, with 18 of 19 verdicts agreeing. These are maintainer-run, workload-specific results. They do not prove universal savings, repository superiority, or statistical equivalence.

The important limitation is lossiness. pxpipe reports that broad gist survives more reliably than exact strings. Dense identifiers can be silently misread, so hashes, paths, version numbers, secrets, commands, code to be edited, and numerical constraints should stay as text or be re-read from the repository.

What Graphify Tries to Solve

Graphify addresses a different question: how can an agent reuse project knowledge instead of reconstructing the repository’s structure from scratch during every task?

A code knowledge graph represents entities such as files, symbols, modules, APIs, tests, documents, and concepts. Relationships can express imports, calls, ownership, containment, test coverage, or cross-document references. The graph becomes a query layer for finding a relevant neighborhood before the model opens the underlying source.

This matters because repository understanding is not proportional to the amount of text in a prompt. An agent may read ten files and still miss a dynamic consumer, a generated contract, or the design decision that explains an unusual boundary. Structured relationships help the agent form better navigation questions:

• What calls this service?
• Which tests exercise this interface?
• Which module owns the shared type?
• Which documents explain this dependency?
• What paths connect the requested feature to persistence or deployment?

Graphify does not make those answers infallible. Static extraction can miss reflection, runtime configuration, external consumers, and generated behavior. Inferred relationships can be wrong. A stale graph can point to an obsolete path. The graph should narrow and organize source inspection, not replace it.

For the underlying model, see Graphify’s guide to knowledge graphs for AI coding assistants. For Claude-specific use, the Graphify and Claude Code integration guide explains how the saved project report fits into an agent workflow.

Compression vs Structured Code Knowledge

Compression asks, “How can this material occupy fewer model tokens?” Structured code knowledge asks, “Which project facts and relationships should the agent retrieve?”

Those questions lead to different failure modes.

With compression, the relevant information may be present but visually misread. The model can recover the broad meaning of a tool log while corrupting a hash or variable name. The mitigation is to classify information by exactness: keep precision-critical fields as text and provide a source re-fetch path.

With a graph, the relationship may be missing, stale, or inferred incorrectly. The agent may receive a clean structural answer that omits a runtime edge. The mitigation is provenance, refresh rules, source links, and verification through search, tests, and runtime evidence.

They also operate at different times. Graphify can prepare reusable project context before a session and update it as the repository changes. pxpipe transforms eligible material on the live request path. A graph can reduce unnecessary file reading; pxpipe can reduce the footprint of the remaining bulky context.

This suggests a layered workflow:

1. Query the graph for relevant entities and paths.
2. Open the authoritative source files and current documentation.
3. Keep exact edit targets and constraints as native text.
4. Compress only older, dense material where gist is sufficient.
5. Run tests and inspect the final diff against the original repository.

When Each Approach Fits

Choose pxpipe for a pilot when long Claude Code sessions repeatedly resend large logs, tool output, or old conversation history. The workload should have measurable input cost, a clear source of truth, and low dependence on exact recall from compressed material.

Choose Graphify when developers repeatedly spend time locating owners, dependencies, tests, and cross-file paths. It is especially relevant when multiple agents or models need the same repository map, because the structural layer can remain model-independent.

Use both when project discovery and context cost are separate bottlenecks. For example, Graphify can identify the modules, tests, and design notes involved in a migration. The agent can read those sources directly. pxpipe can then compress older tool output or historical discussion as the session grows.

Avoid either tool as a default without a controlled trial. For pxpipe, record exact package and model versions, request logs, safeguard refusals, incorrect identifiers, re-read calls, cost, and task outcomes. For Graphify, record graph freshness, missing or incorrect edges, retrieval usefulness, source-opening behavior, review time, and regressions.

Lifecycle also matters. pxpipe’s package and code were changing in mid-July 2026, but its maintainer stated that issue and pull-request response capacity was limited. A graph layer introduces its own maintenance work: refresh triggers, extraction coverage, provenance, and ownership. The easier system is the one whose failure mode your team can observe and correct.

FAQ

Can compression and graphs be used together?

Yes. Use the graph to select relevant project knowledge, then use compression only for bulky material that does not require byte-exact recall. Keep code, paths, IDs, commands, secrets, version strings, and acceptance criteria in native text or retrieve them again before acting.

What evidence should teams collect before switching?

Freeze the repository commit, task, client, model, permissions, and tests. Compare repeated runs with and without the new layer. Record request tokens, cost, latency, task success, incorrect facts, source re-reads, review effort, graph misses, proxy failures, and recovery time. A lower bill is not useful if review or rework rises.

Which approach is easier to maintain over time?

It depends on the operating risk. pxpipe requires version, model, proxy, privacy, and visual-fidelity checks. Graphify requires graph refresh, extraction coverage, provenance, and stale-edge controls. A small team with mostly dense session history may prefer the narrower proxy. A team with recurring repository-navigation problems may gain more from maintained structural knowledge.

Conclusion

The useful answer to pxpipe vs Graphify is not a winner. pxpipe is a request-path optimization for carrying bulky context more cheaply, with an explicit lossiness trade-off. Graphify is a reusable structural layer for asking better repository questions, with freshness and coverage trade-offs.

Start from the bottleneck. If the agent already has the right evidence but resends too much of it, test pxpipe. If the agent repeatedly reads files without building a dependable map of dependencies and intent, test Graphify. If both problems exist, combine selective retrieval, cautious compression, source verification, and tests rather than asking one tool to solve every context problem.

No authoritative single product, repository, or standard named “Skill Zoo” was verified for this article. Here, the phrase describes the growing ecosystem of Agent Skills libraries: reusable SKILL.md packages for Claude Code and other coding assistants. That ecosystem improves capability reuse, but it does not automatically give an agent current knowledge of a complex repository.

What Skill Zoo Changes for Coding Assistants

The skill-library phenomenon changes how teams package instructions for coding agents.

Anthropic's official Claude Code documentation defines a skill as a folder with a SKILL.md entry point. A skill can include instructions, scripts, references, templates, and examples. Claude discovers the skill through its name and description, then loads its full instructions only when the task calls for them. This progressive-disclosure model avoids placing every procedure in permanent context.

That is a meaningful improvement over repeatedly pasting the same checklist into chat. A team can encode:

• how to prepare a release;
• how to review an API change;
• how to run a repository's application;
• how to validate migrations;
• how to follow an internal writing or security workflow.

Claude Code supports skills at personal, project, enterprise, and plugin scopes. Anthropic also publishes a public skills repository with examples. Its README includes an important limitation: the examples are educational and demonstrative, and the behavior available in Claude may differ. Some materials use different licenses, so “public repository” must not be read as “every file is open source and production-approved.”

OpenCode implements the same broad SKILL.md pattern and discovers skills from OpenCode, Claude-compatible, and Agent Skills-compatible directories. The Agent Skills standard describes this portability as a lightweight open format. Portability, however, does not guarantee identical behavior. Clients can interpret permissions, extra frontmatter, tools, and execution differently.

So the useful meaning of “Skill Zoo” is not one verified marketplace. It is a large and expanding collection of reusable agent procedures that teams must still evaluate, version, and govern.

Skills vs Project Understanding

A skill and a project model answer different questions.

Layer	Main question	Typical contents
Skill	How should the agent perform this type of work?	Steps, quality gates, tools, templates, examples
Project rules	What stable constraints apply here?	Commands, conventions, generated-file rules, approvals
Repository knowledge	What entities and relationships exist now?	Symbols, imports, dependencies, tests, schemas, docs
Task evidence	What changed in this run?	Current diff, logs, failing tests, tool output

A code-review skill can tell Claude to check authentication boundaries and run focused tests. It does not know which module owns authentication in the current repository unless that knowledge is supplied or discovered. A release skill can define the workflow but cannot know the current dependency graph from a static instruction file.

This is why “more skills” should not be confused with “better repo understanding.” Skills improve procedural consistency. Repository understanding requires current, source-backed evidence.

The boundary also protects skill quality. If a team copies a fast-changing directory inventory, symbol list, or dependency map into SKILL.md, the package becomes stale quickly. A better skill instructs the agent how to retrieve current facts: inspect the source, consult generated architecture artifacts, query a graph, and record the commit it used.

Why Complex Repos Need Code Knowledge Skills

Complex repositories need skills that connect procedure to live project structure.

A generic debugging skill might say: reproduce the failure, narrow the scope, inspect recent changes, form a hypothesis, and run the smallest confirming test. A code knowledge skill can make those steps repository-aware by requiring the agent to:

1. identify the owning package and public entry point;
2. trace dependencies before editing;
3. find the tests that cover the affected path;
4. check generated or vendored boundaries;
5. locate architecture decisions connected to the code;
6. report the evidence behind its proposed change.

The skill still does not need to contain the graph. It can call or reference the system that maintains it.

The strongest pattern keeps the workflow portable while deriving repository facts from a refreshable source.

This separation helps monorepos in particular. Claude Code can discover nested project skills, allowing one package to define specialized procedures. Yet package-local instructions still benefit from a shared view of cross-package relationships. Otherwise, an agent may follow the frontend workflow correctly while missing that the proposed change alters a generated client or backend contract.

Versioning matters too. Project skills should live beside the code when they describe repository-specific procedures. Review skill changes like code changes: inspect the diff, test the workflow in a fresh session, and record which tools and permissions it needs. Avoid automatically trusting a downloaded skill merely because it appears in a popular collection.

How Graphify Fits as a Project Memory Layer

Graphify can complement Agent Skills by supplying a queryable project-memory layer.

Graphify turns repository materials into graph artifacts that represent entities and relationships. Its knowledge graph guide explains why typed structure can answer questions that a flat file list cannot. Its CLI supports queries, paths, explanations, updates, and watch workflows.

A project skill can then define a safe retrieval procedure:

Before planning a repository-wide change:
1. Query the graph for the affected entity.
2. Trace dependency paths and linked tests.
3. Open the current source files named by the result.
4. Report stale or ambiguous graph evidence.
5. Do not edit until current source confirms the path.

This design has three advantages.

First, the skill stays compact. It contains the method, not an ever-growing copy of the repository.

Second, multiple agents can share the same project map. Claude Code, OpenCode, Codex, or another compatible assistant can follow equivalent retrieval rules even when their skill features differ.

Third, provenance remains visible. The graph can carry source locations and generation metadata, while the skill requires the agent to verify current code before acting.

Graphify already hosts a code graph for addyosmani/agent-skills, a public repository that packages engineering workflows for coding agents. That example illustrates the two layers directly: the repository contains reusable skills, while Graphify maps the repository's own implementation structure.

Limits and Integration Questions

Skills expand an agent's operating instructions, so teams should treat them as executable supply-chain inputs.

Review the complete skill folder before trusting it. Supporting scripts can run commands, reference external resources, or request broad tool permissions. Check licenses per repository and file; do not assume every example in a mixed collection has the same terms.

Keep sensitive data out of the package. A project skill may describe how to access secrets safely, but it should not contain credentials, customer records, production tokens, or copied private conversations.

Plan for client differences. Claude Code documents invocation controls, subagent execution, dynamic context, and Claude-specific frontmatter. OpenCode recognizes a smaller defined frontmatter set and ignores unknown fields. A cross-client skill should use the common core or document client-specific behavior explicitly.

Finally, decide what happens when knowledge is stale. A skill should not force the agent to trust a graph or generated report blindly. Require a source revision, a refresh threshold, and a fallback to direct inspection.

FAQ

Which skills should be project-specific?

Make a skill project-specific when it depends on that repository's commands, architecture, deployment path, review gates, or generated artifacts. Keep broadly reusable practices personal or shared at the organization level, then layer project rules on top.

How should teams version code knowledge skills?

Store project skills in version control, review their changes, and test them in fresh sessions. Pin external dependencies where possible. Record the expected tools, permissions, and generated knowledge artifacts so a skill update cannot silently broaden its authority.

What should not be stored inside a skill?

Do not store secrets, private customer data, unrestricted transcripts, volatile symbol inventories, or large copied source trees. Store procedures and stable rules. Retrieve current repository facts from source-backed files, generated reports, or a maintained code graph.

Conclusion

The Skill Zoo idea is useful as a description of today's expanding Agent Skills ecosystem, not as an unverified product claim. Skills make coding workflows reusable, discoverable, and easier to audit. They answer how an agent should work.

They do not automatically answer what the current repository means. For complex projects, pair procedural skills with refreshable source evidence and a queryable structural layer. The decision rule is straightforward: put stable methods in the skill; keep changing project facts close to the code.