Pi Skills vs CLAUDE.md is not a winner-takes-all comparison. A Pi Skill packages an on-demand procedure. CLAUDE.md provides always-relevant human-written instructions for Claude Code and can also act as Pi’s fallback context file when no AGENTS.md exists. A code knowledge graph supplies current structural repository facts. Use each layer for the job its lifecycle can support.
The title hides an important nuance: CLAUDE.md is not unreadable to Pi. Pi selects one recognized context file per directory and prefers AGENTS.md, but it falls back to CLAUDE.md. The tools still interpret files and permission semantics differently, so shared readability is not shared enforcement.
This comparison was checked against Pi v0.82.0 and current Claude Code documentation on July 24, 2026. It focuses on layer ownership, not the cross-tool file-layout tutorial covered in the separate sharing guide.
Pi stores conversations as JSONL session trees and compacts older turns when needed; that session history is not organization-wide shared memory. Claude Code keeps CLAUDE.md, Skills, and auto memory as separate context surfaces, so tool-specific rules must remain distinct from repository facts.
Quick Verdict
Pi Skills vs CLAUDE.md is a lifecycle decision: load reusable procedures on demand, keep broadly applicable instructions persistent, and query changing code relationships from current evidence.
Use an always-loaded instruction file for stable facts every task needs: repository purpose, approved commands, generated-code rules, security constraints, and links to authoritative documents.
Use a Skill for a reusable workflow that should load on demand: repository analysis, migration review, incident triage, release checks, or an evidence schema with supporting references.
Use a code knowledge graph or another source-attributed index for volatile structural facts: modules, symbols, calls, registrations, schemas, event flows, generated sources, and tests at a specific commit.
Keep task plans and intermediate reasoning in the task or session. Keep proof in current source and executable tests. No context layer should validate itself.
What Pi Skills Are Best For
A code knowledge graph complements Pi Skills by supplying revision-bound relationships that the procedure can query and verify instead of hard-coding.
Pi Skills follow the Agent Skills standard. Pi scans names and descriptions at startup, then reads the full SKILL.md when selected. A user can explicitly invoke a Skill with /skill:name. The package can include references or scripts that support a specialized procedure.
A good repository-analysis Skill defines:
- task inputs and stop conditions;
- read-only tools or adapter commands;
- required module, caller, test, and risk fields;
- provenance and revision checks;
- how to report unknown or conflicting evidence;
- review and escalation rules.
That procedure stays useful when individual code relationships change. The Skill asks the current repository layer for facts rather than hard-coding an inventory of callers.
Pi warns about duplicate Skill names and keeps the first discovered instance. This is a discovery rule, not semantic conflict resolution. Two differently named Skills can still contradict each other. Give every shared Skill an owner, version, fixture test, and review trigger.
Queries such as Pi coding agent web UI can surface third-party or package-based interfaces. Do not transfer their behavior into core Pi. The first-party harness is terminal-oriented and extensible; evaluate any web UI or extension as a separate component with its own permissions and update path.
What CLAUDE.md Is Best For
A Pi coding agent web UI is a separate integration surface and should not be treated as the authority for either Pi's first-party context loading or Claude Code's CLAUDE.md behavior.
CLAUDE.md is Claude Code’s persistent human-written instruction file. It can define commands, conventions, architecture guidance, and project constraints that should be available across sessions. Claude Code supports nested files, rules, and imports.
Keep it concise. Every always-loaded instruction competes for context and can become stale. Anthropic recommends putting stable, broadly applicable guidance in CLAUDE.md and moving specialized procedures into Skills.
For Pi, CLAUDE.md is a fallback context candidate. If AGENTS.md exists in the same directory, Pi selects AGENTS.md first. That means a team should not assume Pi loads both and reconciles differences. If the repository serves several tools, make neutral instructions canonical in AGENTS.md and use Claude’s documented import pattern.
CLAUDE.md also is not hard enforcement. A sentence that says “never edit migrations” is guidance. Back it with repository permissions, review rules, CI, and generated-file checks where the constraint matters.
What Code Knowledge Graphs Add
Instruction and procedure files explain how the team wants work performed. They do not continuously derive what the system currently connects.
A graph can model:
- repository, module, file, symbol, schema, service, test, and decision nodes;
- defines, imports, calls, registers, generates, publishes, consumes, tests, owns, and constrains edges;
- source locations, indexed commit, extraction method, confidence, and coverage gaps.
This enables task-shaped queries: “Which consumers depend on this schema?” or “Which tests cover paths from this entry point?” The result should be a bounded evidence shortlist, not a replacement for source inspection.
Graph facts can drift. Dynamic dispatch and runtime configuration can remain unresolved. Access controls can leak cross-repository structure. Keep the graph read-only for ordinary agents, filter by identity, and require current-source verification for material edges.
The graph is external to both Pi and Claude Code unless your team integrates it. Claude can use MCP or a CLI. Pi needs a CLI or extension/package because built-in MCP is not documented.
Used by both harnesses, the code knowledge graph is a shared external layer for model-independent structural queries with revision-aware provenance.
How the Three Layers Fit Large Projects
Use the layers in sequence:
- The instruction layer establishes stable constraints and approved commands.
- The Skill receives the task and selects a repeatable analysis procedure.
- The graph or index returns relationship evidence for the pinned commit.
- The agent verifies high-impact paths in current source.
- Tests and review validate the planned or implemented change.
- Reusable workflow improvements update the Skill; repository changes refresh the graph; stable policy changes update instructions.
Do not promote every solved task into always-loaded context. A task-specific path can become obsolete immediately. Promote the general procedure only when it recurs, has an owner, and passes fixtures.
Do not put organization policy into the graph merely because it is queryable. Link approved architecture records as evidence, but preserve their authority and authorship.
The three-layer model also improves debugging. If an agent skips a check, inspect the Skill. If it follows a stale rule, inspect the instruction file. If it reports a wrong caller, inspect the graph and source. If it makes an unsafe edit despite correct context, inspect permissions and review controls.
Apply an explicit promotion test before moving information between layers. A repeated task observation becomes a Skill step only when the procedure is stable across several cases. A Skill step becomes an always-loaded rule only when nearly every task needs it and the context cost is justified. A repository relationship never becomes permanent policy merely because it appeared in several successful runs; keep it derived from source.
Version each layer independently. Record an owner and review trigger for CLAUDE.md or AGENTS.md, a semantic version or content hash for Skills, and an indexed commit plus extractor version for graph data. A task result should name all three versions. When behavior changes, this lets reviewers reproduce the context the agent actually received.
Test failure paths as carefully as the happy path. The Skill should stop on an unavailable adapter or revision mismatch. The instruction layer should not authorize destructive behavior through ambiguous prose. The graph should return access denial and coverage gaps explicitly. A team that tests only successful retrieval will mistake silent fallback for reliability.
Finally, control context size. Always-loaded instructions should remain short enough to review. Skill descriptions should be specific enough for correct selection without loading every body. Graph responses should return the smallest evidence set that supports the task. More context can hide contradictions as easily as it can answer questions.
Review context growth as part of regular repository maintenance, not only after an agent fails.
FAQ
Can rules and Skills conflict?
Yes. A persistent rule can prohibit an action that a Skill requests, or duplicate Skills can prescribe different workflows. Define precedence, test both harnesses, and stop for human review when the conflict affects security, data, or destructive operations.
Who audits graph-backed context?
An index maintainer owns extraction health and coverage. Code owners review material schema or manual-fact changes. Task agents verify retrieved edges in their checkouts, and reviewers validate impact and tests.
When should a Skill become a shared workflow?
Promote it when the procedure recurs across tasks, has stable inputs and outputs, includes honest stop conditions, has a named owner, and passes fixture tests. Do not promote a one-off solution path as universal guidance.
pi-coding-agent github
Use the current first-party earendil-works/pi repository and pin the reviewed release. Historical names and community forks may not match current Skill loading, context files, or security behavior.
Conclusion
Put stable instructions in the always-loaded layer, reusable procedures in Pi Skills, and current system relationships in a revision-bound graph or index. Keep each layer owned and testable. The payoff is not more context; it is faster diagnosis when context is missing, stale, contradictory, or unsupported.
Leave a Reply