Project Skills Should Override Global Skills

When an agent needs operational instructions, the worst outcome is ambiguous precedence. A project wants one behavior, your machine has another, and the runtime quietly picks the wrong one.

APC and APX avoid that by making skill scope explicit.

APC is the portable context layer. It keeps project-owned instructions in the repository, including .apc/skills/. APX is the daily-use runtime and tooling layer. It discovers those skills, lets the super-agent load them on demand, and still keeps a machine-wide skill catalog under ~/.apx/skills/ plus its own built-in runtime skills.

The important rule is simple: project skills win.

Three skill lanes, one precedence order

The APX skills docs and loader code define one runtime catalog with three sources, in this order:

1. <project>/.apc/skills/<slug>/SKILL.md or <slug>.md
2. ~/.apx/skills/<slug>/SKILL.md
3. APX built-in runtime skills under src/core/runtime-skills/

The first matching slug wins. That means a project skill can override a user-global skill, and a user-global skill can override a built-in one.

That is the right order because APC owns project meaning.

If a repository says its deploy-checklist skill should work a certain way, that project-local instruction should beat whatever happens to be installed globally on one laptop. Otherwise the same APC project would behave differently depending on whose machine ran it.

Why APC needs the top slot

Portable context only works if the repository can carry its own exceptions.

Imagine you keep a global release-notes skill in ~/.apx/skills/ that fits most projects. Then one repository has stricter rules: mention migration risk, list MCP changes separately, and never claim a release is safe without test output.

That repository should not need a forked runtime or a custom machine setup. It should only need:

.apc/skills/release-notes/SKILL.md

Now APX reads the project skill first, and the super-agent loads the correct instructions for that repository.

That is APC doing its job: project-specific context travels with the repo.

Why global skills still matter

Global skills are still useful. They are the machine-wide layer for habits you want everywhere on one workstation.

Examples:

• personal writing style
• preferred debugging checklist
• local publishing workflow
• a custom skill for a tool only you use

APX stores those in ~/.apx/skills/, so they stay available across projects on that machine without polluting any repository.

That is also the APC/APX split in miniature:

• APC keeps shared, reviewable, repo-owned instructions.
• APX keeps operator-local runtime customizations.

A global skill should be convenient. It should not outrank a project contract.

Why built-in skills stay as the safety net

APX keeps a third lane for built-in runtime skills. The docs describe those as private: always available, always active, and not deletable from scope settings.

That matters because APX ships its own operational knowledge there: apx-* skills, apc-context, and runtime-specific guidance. If users could accidentally delete or fully disable that foundation, the runtime would lose basic self-knowledge about how to use its own commands and structures.

So the full design is not just “project overrides global.” It is:

• project wins when the repo needs a local rule
• global wins when the operator wants a machine-wide customization
• built-in remains as the fallback safety net

On-demand loading keeps prompt cost low

This precedence model works well because APX does not dump full skill bodies into every prompt.

The runtime exposes list_skills and load_skill, and APX documents that load_skill pulls the full body only for the current turn. The baseline prompt stays small, while exact instructions stay available when needed.

That means you can keep project-specific skill overrides in APC without paying for all of them on every message.

Practical rule

Use each lane for its real job.

• Put repo-owned exceptions in .apc/skills/.
• Put personal machine-wide helpers in ~/.apx/skills/.
• Leave built-in APX runtime skills alone unless you are intentionally shadowing them with a better local or project version.

If one slug means different things in two repositories, that is not a bug. That is exactly why the project lane exists.

Bottom line

Project skills should override global skills because APC owns portable project intent.

APX makes that practical with a clear precedence chain, built-in fallback skills, and turn-local skill loading. The result is predictable behavior: the repo decides project meaning, the machine adds personal convenience, and the runtime still keeps its own minimum operational floor.