TLDR: Skill instruction files must use absolute paths. Relative paths silently misresolve when the shell's cwd isn't what you think. And if your skill lives in two places, they will drift apart — and the wrong one will win.

the setup

Apollo is my personal AI system — a Claude Code setup I've built out with custom slash commands called "skills."

One of those skills is /apollo-boot (my AI assistant's boot sequence). Every session it reads a routing table (MEMORY.md), loads my identity files, and pulls in a set of core behavior rules. About 10 files total, executed in order.

Simple in theory.

what actually broke

One morning /apollo-boot "felt like it wasn't working."

That's the polite version. What actually happened: the skill fanned out into a cross-project search loop, reported "Apollo memory files don't exist in this project," and the shell kept printing Shell cwd was reset to /Users/redfoxlake/Developer/a-client-project.

The files were RIGHT THERE. At the absolute path. Sitting perfectly still. Apollo just had the wrong base.

The skill instructions said things like Read MEMORY.md and memory/user_soul.md. Those paths resolve against wherever the shell's cwd is — and the shell does not initialize to the Apollo project directory. It reinitializes to whatever project was last active (in this case: an unrelated client repo). Every relative path in the skill prose silently misresolved.

the fix — and the sneakier second problem

The obvious fix: anchor everything absolutely.

MEMORY.md → /Users/redfoxlake/Developer/Apollo/MEMORY.md.

memory/user_soul.md → /Users/redfoxlake/Developer/Apollo/memory/user_soul.md.

I added a "Path rule" block right at the top of the skill so it's the first thing Apollo reads before any step. Shipped in apollo-boot v0.3.0 (commit c85ecf9).

That almost fixed it.

The subtle trap: MEMORY.md itself contains pointers to the core behavior rule files — written as memory/feedback_*.md. After reading MEMORY.md, Apollo would try to follow those embedded links as bare relatives. Same bug, one layer deeper. I had to explicitly state in the skill: resolve every memory/... pointer inside MEMORY.md against the absolute base before reading. Don't assume the agent inherits the right context just because the first file landed right.

the drift bug hiding in plain sight

Here's the one that really stung.

Apollo skills live in two places: ~/.claude/skills/ (global) and Apollo/.claude/skills/ (project-local). Inside the Apollo project, the project-local copy overrides the global one.

I fixed the global copy. I tested it in a fresh session. It worked.

And then I opened Apollo's project window — where the stale project-local copy was still running the old broken boot, with the dead FULL_REFERENCE.md step I'd already retired. Two copies. Silently diverged. The wrong one winning.

The rule now: whenever I touch any Apollo skill, I update both copies in the same pass and verify they're byte-identical:

diff -q ~/.claude/skills/apollo-boot/SKILL.md \
        /Users/redfoxlake/Developer/Apollo/.claude/skills/apollo-boot/SKILL.md

If there's output, something's wrong.

why this matters to me

I've been building Apollo for months and I trust it with a lot. When the boot breaks quietly — hunting for files instead of just failing loudly — that's the worst kind of failure. You spend 20 minutes second-guessing everything before you find out it was the equivalent of a wrong working directory.

The lesson isn't exotic. It's the same thing you learn with launchd plists and cron jobs: don't assume the ambient context. Absolute paths. Every time.