Claude Code plugin support — canonical skills path, install coexistence, and migration

[vl4duu]

Context

PR #275: plugin support for career-ops. Blocked — bundles 3 arch decisions affecting existing users:

1. Skills path: .claude/skills/career-ops/ → skills/career-ops/SKILL.md
2. Profile split: modes/_profile.md → config/_profile.md
3. Plugin manifest: .claude-plugin/plugin.json for claude plugin install career-ops

Consensus needed before split. Related: #412 (".skill no longer working") — blocked on canonical path.

---

(a) Canonical skills path

Proposal: skills/career-ops/SKILL.md at repo root.

• Plugin spec "skills": ["./skills/"] → marketplace resolves to ~/.claude/plugins/cache/career-ops/<version>/skills/career-ops/SKILL.md automatically.
• .claude/skills/ = user-local dir for personal skills. career-ops ships with repo → skills/ at root correct.
• SKILL.md resolves both: $PWD/modes/_shared.md (clone) and ~/.claude/plugins/cache/*/career-ops/*/modes/_shared.md (plugin).

Open question: Redirect stub at .claude/skills/career-ops/SKILL.md for manual-placers, or changelog note enough?

---

(b) Coexist or replace?

Proposal: coexist. Plugin install = recommended path going forward.

	git clone	plugin install
Modes	$PWD/modes/	~/.claude/plugins/cache/career-ops/<v>/modes/
Profile	config/_profile.md (project)	config/_profile.md (unchanged)
Updates	git pull	claude plugin update career-ops

Both converge on modes/ + config/_profile.md. No divergence.

Open question: Deprecate git-clone as primary in future major, or keep both?

---

(c) Migration

Group 1 — cloned repo (majority): No action. Local path takes priority.

Group 2 — manually copied SKILL.md to .claude/skills/career-ops/: Replace with skills/career-ops/SKILL.md. One file copy. Surface in CHANGELOG.md + new UPGRADING.md.

Profile migration (modes/_profile.md → config/_profile.md): handled in code — SKILL.md detects old path, copies silently. No user action.

---

(d) Compat window

Proposal: 2 minor versions (~4–6 weeks).

• v1.3.x: both paths work; deprecation warning on old path
• v1.4.x: old paths removed; UPGRADING.md entry added
• .skill no longer working #412 closes once canonical path confirmed

---

Questions for consensus

1. skills/career-ops/SKILL.md at root acceptable, or keep inside .claude/?
2. Plugin install eventually replace git clone as primary?
3. 2-minor-version compat window enough for 39K users?
4. .claude-plugin/plugin.json stays in .claude-plugin/ or move to root?

Once consensus reached, PR #275 splits into:

• PR A: skills path + SKILL.md resolution
• PR B: config/_profile.md split + migration
• PR C: plugin manifest + marketplace entry

[santifer]

Late close-the-loop: this largely happened, just via a different door. The repo adopted the open agent skill standard with AGENTS.md as canonical and CLI-specific wrappers importing it (#572 and follow-ups), and skills live in .agents/skills/ with per-CLI registration — OpenCode/Gemini/Qwen lanes all ship this way now. The specific install-UX ideas here (one-command plugin install) remain interesting for the future plugin story, but the canonical-path question this RFC raised is settled. Thanks for pushing the thinking early.