Built-In Skills Should Stay Private in APX

Not every skill in an agent runtime should behave like user content.

Some skills are part of the runtime itself.

In APX, those built-in skills should stay private, always available, and outside normal enable or delete flows.

That boundary matters because APC and APX do different jobs.

APC is the portable context layer. It carries project truth in files such as AGENTS.md, .apc/agents/, .apc/skills/, and other committed artifacts that can travel with the repository.

APX is the daily-use runtime and tooling layer. It turns that portable contract into live behavior: sessions, channels, MCPs, local memory, and skill loading on one machine.

Skill policy belongs on the APX side.

Three skill sources, one runtime

The APX skills loader already scans three sources in priority order:

• project skills in <project>/.apc/skills/
• user-installed global skills in ~/.apx/skills/
• built-in APX skills shipped inside the runtime

That is a good split.

Project skills belong to APC because they are part of the repository contract. A teammate can clone the repo and get the same project-owned skill set.

Global skills belong to the local APX runtime because they are user preferences or machine-local helpers.

Built-in skills are different from both. They are not project content, and they are not user-installed extensions. They are part of APX itself.

Once you accept that, the policy gets simpler.

Why built-in skills should not look editable

If a built-in APX skill could be disabled or deleted like a normal user skill, the runtime would quietly lose part of its own operating model.

The current APX code avoids that.

src/host/daemon/api/skills.js describes built-in skills as private: always active, not deletable, and not stored in ~/.apx/skills/.

The tests in tests/skill-policy.test.js make the rule explicit too:

• built-in skills are private
• built-in skills are always enabled
• even an explicit false override cannot disable them

That is the correct runtime contract.

A built-in skill is closer to internal runtime documentation than to optional user content. It exists so the agent can reliably load APX-owned operating knowledge when needed.

If the runtime let those disappear through normal settings toggles, the agent would become harder to reason about. Two machines with the same APX version could behave differently for reasons that look like product bugs but are really local deletions.

Where scoping still matters

This does not mean every skill should be forced on forever.

The same skill policy design keeps project and global skills scopeable, which is where flexibility actually helps.

A project may want one local skill disabled in the super-agent by default but enabled inside a specific repository. A user may want to keep a personal helper globally available without committing it into APC. Those are valid scope decisions.

Built-in skills are not that.

They are APX runtime capabilities.

So APX can safely expose toggles for project and user skills while keeping built-ins locked.

That preserves a clean APC/APX split:

• APC owns project-portable skills
• APX owns machine-local user skills
• APX also owns its own private built-ins

Different origins, different policy.

Practical example

Imagine one repository ships a .apc/skills/release-checklist.md file. That skill should travel with the repo. Anyone opening the project should be able to load it.

Now imagine you also keep a personal global skill in ~/.apx/skills/commit-style/ for your own workflow. That one should follow your machine, not the repository.

But when APX ships apc-context or another built-in runtime skill, disabling it is not the same kind of choice. You are not curating project context or personal preference anymore. You are removing part of the runtime's own self-knowledge.

That is why APX marks those skills private and always active.

Bigger lesson

Portable context only stays portable when the runtime is strict about ownership.

APC should carry project-authored skill content.

APX should load that content, combine it with local user skills, and still protect the built-in skills that define how the runtime operates.

Treating every skill as one generic editable object would blur those boundaries.

Keeping built-in skills private does the opposite. It makes APC cleaner, APX more predictable, and skill behavior easier to trust across machines.