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

> Pi's default auto-scan misses skills stored in `~/.claude/skills`. An explicit `skills` array in `~/.pi/agent/settings.json` plus a `context_bridge` in the Archon `workflow.yaml` cuts a doc-summary run from ~45s at 40% success to under 12s at 98%. The trap is path resolution and silent SKILL.md skips, not model quality (Archon Docs Hub, May 21, 2026).

**Published:** 2026-05-24  
**Last reviewed:** 2026-05-24  
**Certification:** CCA-F · Claude Certified Architect - Foundations · D1 Agentic Architecture & Orchestration  
**Tags:** pi-agent, claude-skills, archon-assist, settings-json, skill-md-frontmatter, path-resolution-trap, context-bridge  
**Canonical:** https://claudearchitectcertification.com/blog/2026-05-24-configuring-pi-agent-to-load-existing-claude-code-skills

![Painterly editorial illustration: two-cabinet walnut workshop with a labeled shelf bridging the cabinets, holding a shared toolbox. Loop the orange mascot stands by the shelf as a small subordinate guide.](https://claudearchitectcertification.com/blog/2026-05-24-configuring-pi-agent-to-load-existing-claude-code-skills/hero.webp)

> **Quick answer**
>
> Pi will not auto-discover skills stored under `~/.claude/skills`. Add the directory explicitly to the `skills` array in `~/.pi/agent/settings.json`, ensure each `SKILL.md` carries a YAML frontmatter block, and add a `context_bridge` to the Archon `workflow.yaml` so Archon Assist can route to them. Practitioners report doc-summary runs dropping from ~45s at 40% success to under 12s at 98% once the path resolution and frontmatter contracts are satisfied (Archon Docs Hub, May 21, 2026).

## 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:

```json
{
  "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:

```bash
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.

> **How this shows up on the exam**
>
> D1 (Agentic Architecture, 27%) routinely presents a scenario where an agent ignores a tool that should be available. The trap answers are *"increase the model's reasoning level"* or *"add the tool to the prompt"*. The correct answer is almost always on the registration surface: a missing manifest field, a path that resolves to the wrong directory, a metadata contract the agent's loader requires. PI-skill loading is the textbook example. Memorise the pattern - *agent unaware of tool* almost never means *agent incapable of using tool*.
>
> D3 (Claude Code Configuration & Workflows, 20%) and D5 (Context + Reliability, 15%) test the verification side. D3 questions reward candidates who reach for `~/.pi/logs/agent.log` (or its equivalent in other runtimes) over assumptions about behaviour. D5 rewards the recognition that strict JSON parsing, absolute paths, and explicit-over-implicit configuration are reliability primitives. A single trailing comma crashing the agent on startup is not a bug to file; it is the loader doing its job. The exam will test whether you treat config as code with a schema or as text that should "just work".

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?

## Frequently asked questions

**Q: Why does Pi's auto-load fail to find skills stored under ~/.claude/skills?**

Pi's default scan looks at its own skills directory tree, not Claude Code's. **Auto-load is opt-in for legacy paths and conservative about non-standard locations**, so a folder living under `~/.claude/skills` will be silently invisible unless you list it explicitly in the `skills` array of `~/.pi/agent/settings.json`. The fix is two lines of JSON, not a model swap or a reinstall.

**Q: What is the SKILL.md frontmatter requirement that Claude Code ignores but Pi enforces?**

Pi indexes a skill only when its **`SKILL.md` carries a YAML frontmatter block** with the metadata it needs to register the capability. Claude Code is more permissive and will pick up plain markdown, which is why a skill that worked there can simply not show up in Pi. The symptom is silent - no error, no log line, just an empty skill registry - which is what makes this the most common reported pitfall (Developer Forum, May 18, 2026).

**Q: Should I use the symlink hack or the settings.json array?**

The settings.json `skills` array is the **supported path** and the one to use first. The `ln -s ~/.claude/skills ~/.pi/agent/skills/claude_legacy` workaround circulating on Stack Overflow AI (May 20, 2026) is a fallback for cases where settings don't persist, often a symptom of a permission or schema problem worth fixing rather than masking. Symlinks also make permission mismatches harder to diagnose later.

**Q: Why does ./skills resolve differently in a global config?**

Relative paths in `~/.pi/agent/settings.json` resolve against the **execution directory**, not the home folder. So `./skills` means whatever folder you happened to run `pi` from, which is almost never what you intended. Practitioners report this is the root cause of most `Skill Not Found` errors in Archon execution. Use absolute paths or the `~/` prefix and the class of bug disappears.

**Q: What does the context_bridge do in the Archon workflow.yaml?**

The `context_bridge` is the **declarative link between the Archon workflow and the Claude skills directory**, letting Archon Assist invoke skills like `research-summarizer` as if they were native. Without it, the settings.json array makes Pi see the skills but Archon's workflow runner does not route to them, which produces the most confusing failure mode: skills load but never fire (Pi Dev Community, May 19, 2026).

**Q: How does Pi-skill loading map to the CCA-F exam?**

**D1 (Agentic Architecture, 27%)** uses this exact failure shape as a distractor: an agent ignores a tool that is technically available because the registration contract was not met. The right answer is almost always about the registration surface (frontmatter, path, manifest), not about model capability or prompt phrasing. **D3 (Claude Code Configuration & Workflows, 20%)** tests the verification loop - checking `~/.pi/logs/agent.log` for a `successfully mapped` line - over `assume it worked`. **D5 (Context + Reliability, 15%)** rewards understanding that strict JSON parsing and absolute paths are reliability primitives, not pedantry; the trap answer is `use a more permissive parser`, the architecturally correct one is `treat configuration as code with a schema`.

## Where this fits on the site

- **Skills** (concepts): Pi and Claude Code both treat skills as discoverable, frontmatter-described folders. The concept of a Skill as a portable primitive is what makes a shared `~/.claude/skills` directory work across agents. — https://claudearchitectcertification.com/concepts/skills
- **Agent instruction files** (concepts): SKILL.md is the agent instruction file Pi indexes. The post's `silent skip` failure mode is fundamentally a missing-frontmatter problem, which is the agent-instruction-file contract. — https://claudearchitectcertification.com/concepts/agent-instruction-files
- **Agent skills with code execution** (scenarios): The Archon Assist `--skill research-summarizer` invocation is the canonical shape of an executable skill scenario: a directory of capabilities the agent picks from at runtime. — https://claudearchitectcertification.com/scenarios/agent-skills-with-code-execution
- **Debugging Claude Code hooks** (knowledge): Pi's `~/.pi/logs/agent.log` and the JSON-trailing-comma crash class belong to the same debugging surface as Claude Code's hook logs. The verification ritual transfers. — https://claudearchitectcertification.com/knowledge/debugging-claude-code-hooks

---

Cite the canonical HTML page: https://claudearchitectcertification.com/blog/2026-05-24-configuring-pi-agent-to-load-existing-claude-code-skills