Skip to content

design: ~/.apc/skills/ as single source of truth — dir-level symlinks, no inline skills #69

@FZ2000

Description

@FZ2000

Design Decision

Current behaviour (broken)

  • apc collect stores skills inline in ~/.apc/cache/bundle.json
  • apc install saves to ~/.apc/skills/ then copies (fixed in fix(#33): apc install symlinks skills instead of copying them #58) or per-skill symlinks into each tool
  • apc sync creates per-skill symlinks from <tool_skills_dir>/<name>~/.apc/skills/<name>
  • New apc install after sync → does not auto-propagate to synced tools

Desired behaviour

  1. ~/.apc/skills/ is the single source of truth for all skills — installed and collected
  2. apc collect writes extracted skills to ~/.apc/skills/<name>/SKILL.md (not inline cache)
  3. apc install only saves to ~/.apc/skills/ — nothing else
  4. apc sync establishes a dir-level symlink once: <tool_skills_dir>~/.apc/skills/
  5. After sync, any apc install automatically appears in the tool — no re-sync needed

Per-tool plan

Tool Skills dir Approach
OpenClaw ~/.openclaw/skills/ ✅ Dir-level symlink (exclusive dir)
Claude Code ~/.claude/skills/ ✅ Dir-level symlink (exclusive dir)
Cursor ~/.cursor/rules/ ⚠️ Per-skill symlinks (mixed dir — user may have other rules)
Windsurf None N/A
Gemini None N/A
Copilot ~/.github/instructions/ ⚠️ Per-skill symlinks (project-level, mixed)

Code changes

  • src/appliers/base.py: add SKILL_DIR_EXCLUSIVE flag + sync_skills_dir() method
  • src/appliers/openclaw.py + claude.py: set SKILL_DIR_EXCLUSIVE = True
  • src/collect.py: write skills to ~/.apc/skills/ via save_skill_file() instead of inline cache
  • src/sync_helpers.py: use sync_skills_dir() for exclusive tools; keep link_skills() for others
  • src/install.py: remove _link_skill_to_targets() — save to ~/.apc/skills/ only; exclusive tools get it automatically, per-skill tools document that re-sync is needed
  • src/cache.py: deprecate save_skills()/load_skills() for skills (keep for MCP/memory)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions