Pi agent and Claude Code skills: why explicit paths beat auto-load

The mental model most teams start with

The assumption is that two agents that both speak SKILL.md should share the same directory by default. Pi can read what Claude Code wrote, the docs imply auto-load handles legacy paths, and the natural conclusion is that pointing the new agent at the old folder is a no-op.

That assumption survives the demo and breaks in the workflow. Pi's default scan does not walk into ~/.claude/skills. Its SKILL.md contract is stricter. Its JSON parser is stricter. None of these are bugs; each is a defensible design choice. The combined effect is that a skill that worked yesterday in Claude Code is invisible today in Pi, with no error to grep.

Call the failure mode what it is: the Path Resolution Trap. The four mistakes below are the ones that produce it.

Four mistakes that produce the trap

Mistake 1. "Auto-load legacy will pick up ~/.claude/skills."

Reality: the auto_load_legacy: true flag is real, but conservative. It does not guarantee a recursive walk of arbitrary home-folder locations. The reliable pattern is an explicit skills array:

{
  "agent": {
    "skills": [
      "~/.claude/skills",
      "./local_skills"
    ],
    "auto_load_legacy": true,
    "skill_resolution_strategy": "priority_local"
  }
}

That snippet does two things the flag alone does not: it names the directory, and it tells Pi how to resolve collisions between local project skills and the shared Claude library (Pi Dev Community, May 19, 2026).

Mistake 2. "A SKILL.md is a SKILL.md."

Reality: Claude Code treats SKILL.md permissively and will index a skill that has nothing but a heading. Pi requires explicit YAML frontmatter with the metadata it uses to register the skill, and skips the file silently if the block is missing (Developer Forum, May 18, 2026). The skill appears to "not exist" — but the file is right there, untouched. The first verification step after any Pi reload is checking ~/.pi/logs/agent.log for the line Skill '<name>' successfully mapped from Claude directory. Absence of that line is the diagnostic.

Mistake 3. "Relative paths in settings.json work the way relative imports work."

Reality: they do not. A path like ./skills in a global ~/.pi/agent/settings.json resolves against the directory pi was invoked from, not against the file the path lives in. Run pi from ~/projects/foo and you have just registered ~/projects/foo/skills — which probably does not exist. Use absolute paths or the ~/ prefix in any config that is not strictly project-local. This is the single highest-frequency cause of Skill Not Found errors in Archon execution (Stack Overflow AI, May 20, 2026).

Mistake 4. "Loading the skill is enough for Archon Assist to use it."

Reality: Pi seeing the skill and Archon Assist routing to it are two different layers. The workflow runner needs a context_bridge entry in workflow.yaml that points at the Claude skills directory, otherwise the Assist command will report the skill is unknown even when pi --reload lists it cleanly. After both layers are wired, the invocation is:

pi archon assist --skill research-summarizer --input ./docs

Practitioners report this is where the published before-and-after numbers come from. Manual prompt setup with broken auto-discovery: ~45 seconds, ~40% success. The same task with explicit paths, frontmatter compliance, and a context_bridge: under 12 seconds, 98% success (Archon Docs Hub, May 21, 2026).

The nuanced point

Auto-discovery is a convenience feature, not an architectural contract. The contract is the explicit skills array, the YAML frontmatter, and the context_bridge. Three small commitments to writing the configuration down, in exchange for a workflow that survives a fresh shell, a different working directory, and a coworker's machine.

The deeper takeaway is that agent interoperability is mostly about honoring each agent's registration surface, not about hoping shared file formats will paper over differences. Two agents reading the same folder is not interoperability. Two agents reading the same folder under the strictest of their two registration contracts is.

What configuration in your own agent stack is silently doing less than you think it is, because the failure mode is a missing log line rather than a thrown error?