A Project Skill Can Change APX Behavior With One Name

In the APX project management system, a project-local skill with the same name as a user-global or built-in skill takes precedence. This is useful when a repository requires its own set of operating rules. A project can supply its own version of a skill by creating a file named SKILL.md in the .apc/skills/ directory within the project. This file overrides the global or built-in version of the skill, providing a customized workflow for that specific project.

For instance, a personal release skill stored in ~/.apx/skills/release/SKILL.md might contain a checklist for normal releases, such as verifying tests, creating a tag, and writing release notes. However, a regulated service may require a different release process. By adding a file .apc/skills/release/SKILL.md within the project's repository, the project can establish its own release requirements, such as needing a change ticket, specifying a deployment window, and including a rollback note. APX will use this project-specific release skill instead of the personal one.

It is important to note that a project skill does not merge with the global or built-in version; instead, it replaces the lower-priority match. If the project version omits a critical step that is present in the global version, that step will be absent in the resolved skill. A common mistake is to use a generic skill name like review, test, or deploy, which can lead to collisions and inconsistent behavior across projects.

To avoid this confusion, engineers should use a distinct name for additive or experimental guidance, clearly stating the scope of the skill in the description. This ensures that the project skill is reviewed in its entirety, rather than just comparing it to the global counterpart.