Give APC Skill Paths an Explicit Base

A release skill can live in version control and still depend on one developer's laptop. The giveaway is often a path: /Users/alex/work/shop/docs/releases.md. Cloning the repository copies the instruction, but it does not make that address valid on another machine.

For project-owned files, write the location relative to an explicit repository root. That is a practical authoring convention, not a claim that APC automatically rewrites paths.

APC is the portable context layer: it carries shared project guidance. APX is the daily-use runtime and tooling layer that puts that context to work. Keeping those responsibilities separate helps expose a small but costly mistake: embedding the author's checkout location in a reusable procedure.

Give each path a base

The APC skills specification places reusable instruction files at .apc/skills/<name>.md. Agents can reference those skills from AGENTS.md or their agent definitions. The skill remains the shared source of the procedure.

Consider a fictional repository with this layout:

shop/
├── AGENTS.md
├── docs/
│   └── releases.md
├── scripts/
│   └── check-release.mjs
└── .apc/
    └── skills/
        └── release-review.md

A brittle instruction says:

Read /Users/alex/work/shop/docs/releases.md.
Run node /Users/alex/work/shop/scripts/check-release.mjs.

A more useful skill body says:

# Release review

All paths below are relative to this repository's root.
Before running commands, set the working directory to that root.

1. Read docs/releases.md.
2. Run node scripts/check-release.mjs.
3. Report the command's exit status and any failed checks.

Here, check-release.mjs is an example script that the fictional project owns, not an APX command or bundled capability. The skill tells the agent where to look and where to execute. A contributor can put the checkout under a different home directory without editing the procedure.

The explicit base matters. A bare docs/releases.md could otherwise be interpreted relative to the skill's directory, the shell's current directory, or a different checkout. Relative paths remove one machine dependency; naming the base removes the ambiguity they introduce.

Check the reference, not just the wording

Before merging a skill change, open the referenced document from the intended root. Check that the script exists in the repository and that its documented prerequisites are available. If the command changes files or publishes anything, review what it will do before running it merely to validate a path.

For a monorepo, specify the package directory when needed. An instruction to run a command from packages/storefront/ means something different from running it at the repository root. Keep that distinction in the procedure instead of expecting the agent to infer it from a filename.

A useful review exercise is to imagine the same checkout at two unrelated locations. Would every project-file reference still identify the same file? Would the command run against that checkout, or reach back into the author's original folder?

Keep actual machine dependencies visible

Some inputs genuinely live outside the repository: a private credential file, a local service configuration, or a separately installed tool. Turning those into invented relative paths does not make them portable. Describe the prerequisite and leave its machine-specific resolution to local setup.

The APC migration guide separates machine-local paths from shared project context. Applying that boundary to skill instructions preserves the team's procedure without committing someone's workstation layout.

APX can provide the execution environment, but the written contract should still explain its path assumptions. Start with one existing skill: replace hard-coded checkout prefixes, declare the reference root, and verify its targets. That small edit makes the next clone easier to use.

Explore the APC repository for the portable context format and APX for the runtime layer.