Problem
The rulebook library's walking skeleton (S1, #731) delivers rulebooks only in ambient mode, inlining their bodies into .agents/PROJECT.md. The skill delivery mode — the on-demand, scoped counterpart to ambient guidance — is unimplemented, so a rulebook cannot yet be surfaced as a per-platform skill that an agent invokes only when relevant.
Context
S1 established that sync is project-based (process.cwd()), materializes each declared rulebook's neutral body to .agents/rulebooks/<slug>.md, inlines ambient rulebooks into PROJECT.md between idempotent sentinel markers, and derives all installed state from the filesystem (no manifest). The platform layer (src/lib/platform.ts) already gates platform-specific output via resolvePlatformIds() / resolvePlatformPaths().
expandIncludes only resolves paths under contentDir, and platform skill directories live outside it, so a live include directive cannot be emitted into a skill file; the neutral body must be copied in.
Three pieces of the original S2 scope are split out to keep this slice focused and leave its highest-risk module (sentinel-inliner.ts) untouched: the author-provided nudge (#744), project-scope rovodev prompts.yml generation (#747), and persistent declarative platform selection (#745).
Proposed solution
Extend the sync resolver to handle delivery: skill and the multi-modal [ambient, skill] case.
For each rulebook whose delivery includes skill, sync writes a thin-wrapper skill to each targeted platform's project-local skills directory at {projectRoot}/{platformHome}/skills/<slug>/SKILL.md, carrying normal skill frontmatter (name, description, user-invocable) followed by the copied neutral body. Project-local placement (not the home directory) is what makes the scope per-project and keeps the feature consistent with S1's project-based sync.
Platform targeting reuses resolvePlatformIds(options.platform, projectRoot): the default detects project-local platform directories; --platform claude forces a single platform; no detected platform writes no skill files. The neutral file at .agents/rulebooks/<slug>.md is written regardless of platform detection.
Generated skills carry a provenance marker identifying them as sync-owned. Sync uses this marker to retract skill directories when a rulebook is no longer declared or no longer delivers as a skill, without disturbing hand-authored skills. Writes are guarded so re-running sync with unchanged content does not rewrite skill files.
The multi-modal [ambient, skill] case needs no special handling — the ambient and skill paths reconcile independently. content/guidance/rulebooks/shell-conventions.md is set to delivery: [ambient, skill] to exercise both paths end to end; the legacy content/skills/shell-conventions/ is left for S3 cleanup.
Acceptance criteria
Must have
Problem
The rulebook library's walking skeleton (S1, #731) delivers rulebooks only in
ambientmode, inlining their bodies into.agents/PROJECT.md. Theskilldelivery mode — the on-demand, scoped counterpart to ambient guidance — is unimplemented, so a rulebook cannot yet be surfaced as a per-platform skill that an agent invokes only when relevant.Context
S1 established that
syncis project-based (process.cwd()), materializes each declared rulebook's neutral body to.agents/rulebooks/<slug>.md, inlinesambientrulebooks intoPROJECT.mdbetween idempotent sentinel markers, and derives all installed state from the filesystem (no manifest). The platform layer (src/lib/platform.ts) already gates platform-specific output viaresolvePlatformIds()/resolvePlatformPaths().expandIncludesonly resolves paths undercontentDir, and platform skill directories live outside it, so a live include directive cannot be emitted into a skill file; the neutral body must be copied in.Three pieces of the original S2 scope are split out to keep this slice focused and leave its highest-risk module (
sentinel-inliner.ts) untouched: the author-provided nudge (#744), project-scope rovodevprompts.ymlgeneration (#747), and persistent declarative platform selection (#745).Proposed solution
Extend the
syncresolver to handledelivery: skilland the multi-modal[ambient, skill]case.For each rulebook whose delivery includes
skill, sync writes a thin-wrapper skill to each targeted platform's project-local skills directory at{projectRoot}/{platformHome}/skills/<slug>/SKILL.md, carrying normal skill frontmatter (name,description,user-invocable) followed by the copied neutral body. Project-local placement (not the home directory) is what makes the scope per-project and keeps the feature consistent with S1's project-based sync.Platform targeting reuses
resolvePlatformIds(options.platform, projectRoot): the default detects project-local platform directories;--platform claudeforces a single platform; no detected platform writes no skill files. The neutral file at.agents/rulebooks/<slug>.mdis written regardless of platform detection.Generated skills carry a provenance marker identifying them as sync-owned. Sync uses this marker to retract skill directories when a rulebook is no longer declared or no longer delivers as a skill, without disturbing hand-authored skills. Writes are guarded so re-running sync with unchanged content does not rewrite skill files.
The multi-modal
[ambient, skill]case needs no special handling — the ambient and skill paths reconcile independently.content/guidance/rulebooks/shell-conventions.mdis set todelivery: [ambient, skill]to exercise both paths end to end; the legacycontent/skills/shell-conventions/is left for S3 cleanup.Acceptance criteria
Must have
delivery: skill(or[ambient, skill]) writes<slug>/SKILL.mdinto each targeted platform's project-local skills directory, carryingname/description/user-invocablefrontmatter and the copied neutral body.skill, retracts the platform skill files; hand-authored skills (without the sync provenance marker) are never removed.--platform claudewrites only the Claude skills dir; no detected platform writes no skill files; the neutral file is always written.shell-conventionsis set to[ambient, skill]and delivered via both paths.skilland[ambient, skill], idempotency, and retraction.