Converge windsurf skills onto .agents/skills/ (Cascade native cross-agent discovery)

[danielmeppiel]

Summary

Switch the windsurf target's skills primitive deploy path from .windsurf/skills/<name>/SKILL.md to .agents/skills/<name>/SKILL.md so windsurf joins the existing 5-target convergence (copilot, cursor, codex, gemini, opencode) on the cross-tool .agents/skills/ directory.

Why now

The Windsurf docs explicitly endorse this. From docs.windsurf.com/windsurf/cascade/skills#skill-scopes:

For cross-agent compatibility, Windsurf also discovers skills in .agents/skills/ and ~/.agents/skills/. If you have enabled Claude Code config reading, .claude/skills/ and ~/.claude/skills/ are scanned as well.

Cascade already scans .agents/skills/ natively at both workspace and user scope. The premise APM has been operating under -- captured verbatim in docs/src/content/docs/producer/author-primitives/skills.md:111-113:

Five harnesses converge on the cross-tool .agents/skills/ directory. Claude and Windsurf keep harness-native paths because their runtimes scan their own roots.

-- is out of date for the windsurf half. Cascade reads both. There is no longer a runtime reason for windsurf to stay on .windsurf/skills/.

Strategic framing

APM positions itself around the agentskills.io spec and the cross-tool .agents/skills/ convention (see README.md, docs/.../index.mdx, docs/.../skills.md). Every additional target on .agents/skills/ strengthens that positioning and reduces per-tool duplication for multi-IDE teams (the same argument that motivated the agent-skills target in #1103 and the 5-target convergence).

Windsurf upstream did the work for us. APM should accept it.

Proposed change

src/apm_cli/integration/targets.py -- windsurf TargetProfile:

 "windsurf": TargetProfile(
     name="windsurf",
     root_dir=".windsurf",
     primitives={
         "instructions": PrimitiveMapping("rules", ".md", "windsurf_rules"),
-        "skills": PrimitiveMapping("skills", "/SKILL.md", "skill_standard"),
+        "skills": PrimitiveMapping(
+            "skills", "/SKILL.md", "skill_standard",
+            deploy_root=".agents",   # converge per Cascade native discovery
+        ),
         "commands": PrimitiveMapping("workflows", ".md", "windsurf_workflow"),
         "hooks":    PrimitiveMapping("", "hooks.json", "windsurf_hooks"),
     },
     ...
 ),

(PrimitiveMapping.deploy_root already exists in the registry to redirect a primitive away from a target's root_dir; this is the same mechanism the 5 converged targets use.)

Scope checklist

• Flip windsurf skills mapping to .agents/skills/ at workspace scope
• Same flip at user scope (~/.agents/skills/ per the Windsurf doc quote; verify user_root_dir interaction)
• --legacy-skill-paths / APM_LEGACY_SKILL_PATHS=1 honored for windsurf (mirror the existing 5-target opt-out)
• One-time migration: uninstall stale .windsurf/skills/<pkg>/ directories deployed by prior APM versions, or document a rm -rf .windsurf/skills/<pkg>/ step
• Update docs/.../author-primitives/skills.md table (windsurf row) and the "Claude and Windsurf keep harness-native paths" sentence
• Update packages/apm-guide/.apm/skills/apm-usage/commands.md if it mentions the windsurf deploy path
• Add integration test pinning the new deploy path
• Add regression test that --legacy-skill-paths still produces .windsurf/skills/ for windsurf
• Detection: .agents/ is shared by multiple tools; windsurf's detect_by_dir=True should still key off .windsurf/, not .agents/. Verify no auto-detection regression.
• CHANGELOG entry under Unreleased flagged as breaking-change (deploy path moved) with migration note

Sequencing

Lands after #1486 (which fixes the uninstall directory-collision bug under the current .windsurf/skills/ shape; convergence builds on that fixed TargetProfile contract).

Out of scope

• Claude convergence onto .agents/skills/. The Windsurf doc quote notes Claude scanning is opt-in via "Claude Code config reading"; not a default-on guarantee. Track separately if/when Anthropic flips the default.

Refs

• Bug fix that unblocks this: Fix/windsurf uninstall skills cleanup #1486
• Original windsurf target: Feature/windsurf target #1066
• 5-target convergence precedent: feat(install): add --target agent-skills for cross-client .agents/skills/ deployment #1103 (agent-skills) and the skills.md routing table
• Windsurf docs (load-bearing citation): https://docs.windsurf.com/windsurf/cascade/skills#skill-scopes