OpenCode Skills vs Code Knowledge Graphs

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.