Refresh APX Skills Without Replacing Your Dev Install

Refreshing APX Skills Without Replacing Your Dev Install

You edit an APX skill, open your coding assistant, and get the old instructions again. The Markdown change is correct. The assistant may simply be reading a different file.

Understanding APX and Skill Delivery

For contributors working from a linked APX checkout, refreshing installed skills is a separate operation from upgrading APX. Use apx skills sync when the change needs to reach the external tools' global skill directories.

APX Layer and Skill Delivery

Agent Project Context (APC) is the portable context layer: repository-owned instructions and definitions shared by compatible tools. APX is the daily-use runtime and tooling layer, with a local daemon, CLI, and execution surfaces. That division also helps explain skill delivery.

Different Lifecycles for Project Contract and Helper Files

A project contract and a machine's installed helper files have different lifecycles. Committing an instruction does not automatically refresh every copy already installed on a developer's machine.

APX Package Locations

APX has two relevant locations inside its package:

• src/core/runtime-skills/ contains instructions consumed by APX's own runtime.
• skills/ supplies the separate bundled catalog distributed to external tools.

The skills documentation distinguishes these catalogs. Editing one does not imply that a consumer of the other will see the change.

A Small Stale-Copy Example

Suppose a bundled helper still describes an outdated command. You correct its source in the development checkout, then ask an external coding tool to repeat the workflow. It suggests the outdated command again.

Verifying the Delivery Path

Before rewriting the instruction, inspect the delivery path:

• Confirm that your apx executable resolves to the development installation you intend to test.
• Run the bundled skill refresh.
• Inspect the installed helper in the target tool's global skill directory.
• Verify the corrected passage is present, then exercise the workflow in the consuming tool.

The refresh command is: apx skills sync --verbose

Understanding APX's Sync Handler

APX's sync handler calls the shared installer and reports results by skill and destination. Its output distinguishes created, updated, unchanged, and pruned entries. Check the destination you actually use; a successful write elsewhere does not prove your assistant read the new text.

Why an Upgrade is the Wrong Repair

The APX contributor guide warns against using apx update to refresh a linked development checkout. An upgrade can replace the global link with a published package, leaving subsequent commands pointed at released code instead of your working tree. See the development loop.

Diagnosing the Delivery Path

For APX's own runtime skills, the contributor guide documents loading from the package path on demand. Diagnose that path separately; refreshing external copies cannot fix a change made in the wrong catalog. The useful debugging question is precise: which file does this consumer read, and what operation puts the new content there? Answer it before changing the prompt again.