Agent-specific handling of skills was dropped during repo migration

[williamthorsen]

Problem

When agent skills were migrated from configs.macos to codeassembly, platform-specific skill handling was omitted. In the previous repo, Claude Code and Rovo Dev each had their own skill directories (agents/claude/skills/ and agents/rovodev/skills/) that the deployment script (sync-agent-files.sh) merged into the shared skills. In codeassembly, installSkills() installs ALL skills to ALL platforms with no filtering.

Additionally, the rovodev-generate-prompts.sh script that generated ~/.rovodev/prompts.yml (Rovo Dev's skill discovery file) was not migrated.

Impact:

• review-permissions skill is missing from Claude Code
• brainstorming and systematic-debugging skills (with supporting files) are missing from Rovo Dev
• Rovo Dev skill autocomplete is broken (no prompts.yml)

Relevant considerations

• The three missing skills exist in configs.macos under agents/claude/skills/ and agents/rovodev/skills/. The systematic-debugging skill has 10 files (SKILL.md + 9 supporting files).
• Currently installSkills() in packages/agents/src/commands/install.ts reads all entries from content/skills/ and installs them indiscriminately. Subagents already have platform-specific overlays (_data/claude.yml, _data/rovodev.yml), but no equivalent mechanism exists for skills.
• The prompts.yml format is a flat YAML list of skills where user-invocable is not false. brainstorming has user-invocable: false (internal skill); systematic-debugging has no user-invocable field (defaults to included).
• parseFrontmatter() from frontmatter-merger.ts is already exported and can be reused for reading skill frontmatter.

Proposed solution

Add a content/skills/_platforms/{platformId}/ directory convention (following the existing _data underscore-prefix pattern), modify installSkills() to skip _platforms in the main loop and separately install platform-specific skills, and add a generatePromptsYml() function that scans installed skills and writes prompts.yml for Rovo Dev.

Acceptance criteria

• The agent-specific skill directories, including all their files, are migrated to codeassembly under content/skills/_platforms/{platformId}/
• The skills are installed only to their respective agent's skill directory (review-permissions → Claude only; brainstorming, systematic-debugging → Rovo only)
• ~/.rovodev/prompts.yml is correctly populated by the install command with all invocable skills (shared + rovodev-specific)
• prompts.yml is tracked in the install manifest for drift detection and uninstall
• Existing tests updated; new tests cover platform filtering and prompts.yml generation
• _platforms/ convention documented in PROJECT.md

[williamthorsen]

Implementation plan

Context

When agent skills were migrated from configs.macos to codeassembly, two capabilities were dropped:

1. Platform-specific skills — In the old repo, agents/claude/skills/ and agents/rovodev/skills/ held skills that were merged into each platform's skill directory by sync-agent-files.sh. In codeassembly, all skills go to all platforms with no filtering.
2. prompts.yml generation — Rovo Dev needs ~/.rovodev/prompts.yml to discover invocable skills. The old repo generated this via rovodev-generate-prompts.sh. No equivalent exists here.

Result: review-permissions is missing from Claude, brainstorming and systematic-debugging are missing from Rovo, and Rovo's skill autocomplete is broken.

Approach

1. Add _platforms/ content directory

Create content/skills/_platforms/{platformId}/{skill-name}/ to hold platform-specific skills, following the _data convention (underscore-prefixed directories = not regular skills).

content/skills/_platforms/
  claude/
    review-permissions/SKILL.md
  rovodev/
    brainstorming/SKILL.md
    systematic-debugging/
      SKILL.md
      condition-based-waiting-example.ts
      condition-based-waiting.md
      defense-in-depth.md
      find-polluter.sh
      root-cause-tracing.md
      test-academic.md
      test-pressure-1.md
      test-pressure-2.md
      test-pressure-3.md

Source: Copy from configs.macos repo at agents/{claude,rovodev}/skills/.

2. Modify installSkills() for platform filtering

File: packages/agents/src/commands/install.ts

• Add platformId parameter to installSkills() (and update its call site on line 42)
• Skip _platforms in the main skills loop (line 91), analogous to how installSubagents skips _data
• After the main loop, read content/skills/_platforms/{platformId}/ and install those skills using the same copy/link/drift logic

The platform-specific loop mirrors the shared-skill loop's behavior (drift detection, copy/link, manifest entry creation). Keeping it inline is consistent with the existing code style.

3. Generate prompts.yml for Rovo Dev

File: packages/agents/src/commands/install.ts

Add generatePromptsYml() that:

1. Scans the installed skills directory (so it reflects shared + platform-specific skills, accounting for drift-skipped items)
2. For each {skill}/SKILL.md, parses frontmatter via the existing parseFrontmatter() from frontmatter-merger.ts
3. Includes skills where user-invocable is not explicitly false (absence = included)
4. Writes YAML matching the existing format:

   prompts:
     - name: 'skill-name'
       description: Description text
       content_file: skills/skill-name/SKILL.md

5. Returns a ManifestEntry so prompts.yml is tracked for drift detection and uninstall

Call from installCommand() only when platformId === 'rovodev' (Claude discovers skills from the filesystem).

YAML generation: Build manually with string templates (the structure is trivial — a flat list of 3-key objects) rather than js-yaml.dump(), to match the exact existing format.

4. Update tests

File: packages/agents/src/commands/__tests__/install.test.ts

• Fix skill count assertion (line 72–74) to exclude _platforms from expected count and add claude-specific skills
• Add tests for:
  • Platform-specific skills installed only to their platform (review-permissions → Claude only, brainstorming/systematic-debugging → Rovo only)
  • _platforms directory not installed to targets
  • prompts.yml generated for rovodev with correct content
  • prompts.yml NOT generated for claude
  • prompts.yml tracked in manifest
  • Link mode works for platform-specific skills

5. Update documentation

File: .agents/PROJECT.md (lines 55–74) — add _platforms/ to the content directory tree.

Files to modify

File	Change
packages/agents/content/skills/_platforms/	New — 3 skill directories (copied from old repo)
packages/agents/src/commands/install.ts	Add platformId to installSkills(), skip _platforms, install platform skills, add generatePromptsYml()
packages/agents/src/commands/__tests__/install.test.ts	Fix count assertion, add 6 new tests
.agents/PROJECT.md	Document _platforms/ convention

Existing code to reuse

• parseFrontmatter() from packages/agents/src/lib/frontmatter-merger.ts — parse skill YAML frontmatter
• copyItem() / linkItem() from packages/agents/src/lib/installer.ts — file operations
• detectDrift() / computeContentHash() from packages/agents/src/lib/manifest.ts — drift detection
• isEnoent() pattern from install.ts line 212 — graceful handling of missing platform directories

Verification

1. npx codeassembly-agents install --platform claude --dry-run → shows review-permissions but not brainstorming/systematic-debugging
2. npx codeassembly-agents install --platform rovodev --dry-run → shows brainstorming/systematic-debugging but not review-permissions, and shows prompts.yml generation
3. Full install and verify ~/.rovodev/prompts.yml contains systematic-debugging but not brainstorming (which has user-invocable: false)

[williamthorsen]

Implementation insights from orchestrated run 20260303-051945Z

I1 — parseFrontmatter() returns raw lines, not a parsed object. The utility returns { lines, agentName, body } where lines is an array of raw frontmatter lines. Extracting structured fields (like description and user-invocable) requires scanning lines for prefix matches. This is a deliberate design trade-off to avoid a YAML parsing dependency for frontmatter.

I2 — startsWith('_') guard is more robust than specific name checks. The planner improved the external plan's approach by using startsWith('_') to skip non-skill directories instead of checking for _platforms specifically. This future-proofs against additional underscore-prefixed directories without code changes.

I3 — Skill descriptions use varied quoting in YAML frontmatter. Descriptions may use single-quotes, double-quotes, or no quotes. generatePromptsYml normalizes all to single-quoted YAML scalars with proper escape handling ('' for internal single quotes).