A skill name is a boundary, not just a label. In APX, a project-local skill with the same slug as a user-global or built-in skill wins. That is useful when a repository needs its own operating rules. It is also a reason to treat a skill name change as a real behavior change.
The precedence is deliberate
APX builds its on-demand skill catalog from three places, in this order:
<project>/.apc/skills/<slug>/SKILL.md~/.apx/skills/<slug>/SKILL.md- APX's bundled runtime skills
The first matching slug wins. A project can therefore supply deploy/SKILL.md and make its deploy procedure available only when work is inside that project. APC carries that file with the repository, so teammates and a fresh clone can inspect the same contract. APX supplies the day-to-day runtime that discovers and loads it when relevant.
That split matters. The repository owns instructions that must travel with its code. A machine-wide directory is better for a personal convention that should apply across unrelated projects. Bundled skills remain the fallback for standard APX behavior.
A concrete example
Imagine you use a personal release skill in ~/.apx/skills/release/SKILL.md. It describes your normal checklist: verify tests, create a tag, write release notes.
A regulated service needs a different release contract. Its repository can add:
.apc/skills/release/SKILL.md
That project file can require a change ticket, a deployment window, and a rollback note. APX will use it for that project instead of the personal release skill. The global workflow remains untouched for other projects.
This is not a merge. APX does not combine two files named release; the project file replaces the lower-priority match. If the project version omits an important step from the global version, that step is absent in the resolved project skill.
The common mistake: accidental shadowing
A generic name such as review, test, or deploy makes collisions easy. An engineer may create a project skill with a familiar slug, expecting to add a few local details, but actually replace the existing guidance entirely. The result can look inconsistent: the same request produces different behavior in different projects.
Avoid that surprise with a small review routine:
- Use a shared slug only when replacement is intentional.
- Give additive or experimental guidance a distinct name, such as
payments-releaseorapi-contract-review. - State the scope in the skill description so the catalog explains when it applies.
- Review the complete project skill, not only its diff against a global counterpart.
Portable override, local runtime
The project skill belongs in APC because it is part of the repository's durable agreement. It can be reviewed in Git alongside the code it governs. APX can then resolve that agreement in the active project without putting personal global skills, sessions, or private runtime state into the repository.
That is the practical value of precedence: one project can deliberately own its workflow without turning every local customization into a global rule.
Top comments (0)