Summary
The reflection skill must be loaded from a dedicated system directory (system-skills/) baked into the Docker image, separate from the user-mounted ./skills directory.
Motivation
The ./skills directory is user-mounted at runtime and may contain user-provided skills that could collide with or override system skills. The reflection skill is a built-in system skill that must always be available regardless of what the user mounts. Currently, skills/ is not copied into the Docker image (see Dockerfile line 39-43), meaning system skills are lost at build time and must be mounted — putting them in the same namespace as user skills.
Proposed Solution
- Create
system-skills/ directory at the project root (alongside skills/, src/, etc.)
- Move system-critical skills (starting with
reflection/) from skills/ to system-skills/
- Update Dockerfile to copy
system-skills/ into the image at build time:
COPY system-skills/ ./system-skills/
- Update skill discovery in
src/skills/discoverer.js and src/skills/registry.js to scan both directories:
- System scope:
system-skills/ (baked into image, higher priority)
- User scope:
skills/ (mounted at runtime)
- System skills shadow user skills with the same name (consistent with existing
.agents/skills override logic)
Alternatives Considered
- Keeping system skills in
skills/ with a naming convention (e.g., system-reflection) — rejected because user mounts could still override them
- Using environment variables to specify skill directories — adds configuration burden
- Bundling system skills into the package entry point — loses the progressive disclosure model
OpenSpec Note
This project uses OpenSpec for feature development. If this request is approved, I will:
- Run
/opsx:propose to generate a full proposal with specs and tasks
- Iterate on the design before any code is written
- Follow the task-driven implementation workflow
Additional Context
The reflection skill currently lives at skills/reflection/SKILL.md. The skill loading mechanism needs to be updated to resolve system skills from a separate, non-user-mounted path. This likely affects the skill discovery and loading pipeline wherever it resolves skill paths.
Summary
The reflection skill must be loaded from a dedicated system directory (
system-skills/) baked into the Docker image, separate from the user-mounted./skillsdirectory.Motivation
The
./skillsdirectory is user-mounted at runtime and may contain user-provided skills that could collide with or override system skills. The reflection skill is a built-in system skill that must always be available regardless of what the user mounts. Currently,skills/is not copied into the Docker image (see Dockerfile line 39-43), meaning system skills are lost at build time and must be mounted — putting them in the same namespace as user skills.Proposed Solution
system-skills/directory at the project root (alongsideskills/,src/, etc.)reflection/) fromskills/tosystem-skills/system-skills/into the image at build time:COPY system-skills/ ./system-skills/src/skills/discoverer.jsandsrc/skills/registry.jsto scan both directories:system-skills/(baked into image, higher priority)skills/(mounted at runtime).agents/skillsoverride logic)Alternatives Considered
skills/with a naming convention (e.g.,system-reflection) — rejected because user mounts could still override themOpenSpec Note
This project uses OpenSpec for feature development. If this request is approved, I will:
/opsx:proposeto generate a full proposal with specs and tasksAdditional Context
The reflection skill currently lives at
skills/reflection/SKILL.md. The skill loading mechanism needs to be updated to resolve system skills from a separate, non-user-mounted path. This likely affects the skill discovery and loading pipeline wherever it resolves skill paths.