Make shared skill references runtime-neutral while preserving skill handoffs #1772

What should happen

Shared Magpie instructions should reference skills without assuming a runtime-specific invocation syntax, while still resolving to the intended skill and preserving arguments and handoff requirements. User-facing invocation guidance should match the current runtime and the installed skill name.

Why

Codex uses $ skill mentions, while shared preflight instructions still recommend Claude Code-style slash commands. Installation methods also affect naming: setup is documented as /magpie-setup:setup for Claude Code marketplace installs, /magpie-setup for pinned-snapshot installs, and $magpie-setup for Codex. The Codex adapter already documents this difference, but shared guidance can still recommend the wrong invocation.

Which layer

Skill (.claude/skills/<name>/)

Boundary conditions (optional)

• Skill references must remain unambiguous and resolvable across supported installation layouts; a relative link working in the source tree does not establish that it works after installation.
• Preserve arguments such as config and verify.
• If the runtime or registered name is unknown, give neutral guidance rather than guess a command.
• Report missing or ambiguous target skills instead of silently selecting another.
• Preserve explicit user invocation, approval, and manual handoff requirements; reading SKILL.md is not authorization to execute the skill.

Out of scope (optional)

• Removing valid runtime-specific examples or changing built-in commands such as /skills, URLs, filesystem paths, or shell commands.
• Changing skill behavior or authorization rules.
• Creating runtime-specific skill copies or a new execution framework.

References (optional)

• docs/adapters/codex.md — Invoke a Magpie skill
• docs/quick-start.md — installation-specific setup naming
• plugins/magpie-security/skills/cve-allocate/SKILL.md — shared preflight references to /magpie-setup:setup config and verify