Skip to content

Bring sync skill deployment to transform parity with install #892

Description

@williamthorsen

Problem

sync's deploySkill mirrors a skill's library directory verbatim — no include expansion, link rewriting, or tool-name rewriting. install's skill path does all three. #878 routes the skill catalog through sync, so skills that rely on those transforms deploy broken: catalog skills use <!-- include: --> directives, {tool:…} placeholders, and bare-relative Markdown links, none of which survive a verbatim mirror.

Context

  • The three transform primitives already exist as shared library functions (directive expansion, path/link rewriting, tool-name rewriting). Only the skill-directory composition that orchestrates them is private to the install path.
  • The subagent side is already at transform parity through a shared subagent-transform module that both install and sync consume. That is the precedent for the skill side; this ticket is the skill side only.
  • Prerequisite for Retire unconditional install; ship the default catalog through a computed all collection #878.

Proposed solution

Extract the skill-directory transform composition into one shared module consumed by both install and deploySkill — not replicated in sync, which would re-create the install/sync drift this ticket closes.

  • deploySkill applies the shared composition per targeted harness (the tool-name mapping is harness-specific), reaching every .md in the skill, not just SKILL.md.
  • sync's existing byte-stable writes (unchanged skills touch no files) and ownership-marker behavior are preserved.
  • Validation runs eagerly per harness, so a broken include or unmapped placeholder fails the run — including --dry-run — rather than half-writing, matching install's fail-closed behavior.
  • Bundle the overlay loader's rename and relocation into a neutral module (it now serves skills as well as subagents).

Acceptance criteria

Must have

  • sync skill deployment expands <!-- include: --> directives; no deployed skill retains an include directive.
  • sync skill deployment rewrites bare-relative Markdown links to absolute/tilde targets across every .md in the skill, not only SKILL.md.
  • sync skill deployment rewrites {tool:…} placeholders to each target harness's tool names; an unmapped placeholder fails with a file/line-anchored error, including under --dry-run (parity with install).
  • A skill deployed via sync to a harness has the same expanded, rewritten body as the same skill deployed via install (ownership/provenance markers aside).
  • The skill-directory transform is single-source: install and sync share one composition module.
  • Re-running sync on an unchanged skill makes no filesystem changes.
  • Tests exercise the sync/deploySkill path for include expansion, link rewriting, and per-harness tool-name rewriting.

Should have

  • The overlay loader is renamed and relocated to a neutral module shared by both the skill and subagent paths.

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureAdded or improved external functionalityscope:agents

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions