Skip to content

fix: load reflection skill from system directory to avoid collision with user skills #415

Description

@avoidwork

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

  1. Create system-skills/ directory at the project root (alongside skills/, src/, etc.)
  2. Move system-critical skills (starting with reflection/) from skills/ to system-skills/
  3. Update Dockerfile to copy system-skills/ into the image at build time:
    COPY system-skills/ ./system-skills/
  4. 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:

  1. Run /opsx:propose to generate a full proposal with specs and tasks
  2. Iterate on the design before any code is written
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    approvedAn identifier for Madz to take action.bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions