Skip to content

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

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)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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