Feature: adopt/claim workflow for CLI-bundled skills (~/.agents convention)

[salmonumbrella]

Context

A growing set of tools now ship their own skills as part of install/setup — writing canonical files to ~/.agents/skills/<name>/ (the shared "agents" convention, tracked via ~/.agents/.skill-lock.json) and placing symlinks in each detected AI agent's target dir (~/.claude/skills/, ~/.continue/skills/, ~/.codex/skills/, etc.).

Confirmed examples in the wild:

Tool	Install	Ships
firecrawl/cli	npx -y firecrawl-cli@latest init	12 skills (sources: firecrawl/cli, firecrawl/skills)
googleworkspace/cli (gws)	brew install googleworkspace-cli, then npx skills add https://github.com/googleworkspace/cli	100+ skills
obra/superpowers-marketplace	Claude Code plugin marketplace	multi-skill bundle
backnotprop/plannotator	Claude Code plugin marketplace	multi-skill bundle

Different install mechanisms (npx postinstall, npx skills add, Claude Code plugins), same end state: canonical files in ~/.agents/skills/, symlinks in agent target dirs, entries in ~/.agents/.skill-lock.json.

Conflict with skillshare

Skillshare's model: ~/.config/skillshare/skills/ is source of truth, target dirs are synced copies, "never edit targets directly." Bundled skills break this:

1. They write straight to ~/.agents/skills/ + agent target dirs, bypassing skillshare source
2. skillshare audit flags them as local/unmanaged
3. Adding exclude: firecrawl* silences audit but then only the subset of agents the installer detected gets the skills (firecrawl wrote to Claude + Continue only, missed Codex/Gemini/Pi which skillshare does manage)
4. If the user moves them into skillshare source manually, a future <tool> setup skills (or re-install) silently overwrites the target-dir symlinks, drifting from source

Proposed: skillshare adopt

skillshare adopt "firecrawl*" --source-repos "firecrawl/cli,firecrawl/skills"
skillshare adopt "gws-*"      --source-repos "googleworkspace/cli"

Would:

1. Detect matching skills in ~/.agents/skills/ (or target dirs) not already in skillshare source
2. Move canonical files into ~/.config/skillshare/skills/
3. Clean broken symlinks across all agent target dirs (including unmanaged ones like ~/.continue/skills/)
4. Prune matching entries from ~/.agents/.skill-lock.json by source / sourceUrl prefix
5. Run skillshare sync

Questions

1. Does this fit inside Add plugin support as a first-class resource type #133's plugin-support scope, or warrant a separate lighter command focused on the ~/.agents/skills/ convention specifically?
2. Is there an idiomatic skillshare way to claim target-local skills today that I'm missing? collect looked close but I wasn't sure whether it handles the lock-file pruning piece or cross-agent symlink cleanup.
3. Would skillshare doctor --suggest-adopt (detecting these and offering to absorb them) be a lighter alternative to a dedicated command?

[alessandrocornacchia]

Also popular marketplaces such as https://skills.sh use npx skills add installer.
Agree with @runkids

[runkids]

@salmonumbrella Great proposal as always — thanks for the research and examples.

I want to make sure I understand the core problem before committing to a solution. Today you can already do:

skillshare target add universal
skillshare collect universal --force
skillshare sync --force

This pulls everything from ~/.agents/skills/ into skillshare's source and syncs to all targets. After that, you'd use skillshare install / skillshare update going forward instead of npx skills add.

Does this cover your use case, or is there a specific gap I'm missing? For example:

• Is the issue that some tools bundle skill installation into their setup and you can't opt out?
• Or is it more about wanting a single discoverable command instead of the 3-step flow above?

Want to make sure I build the right thing here.

[salmonumbrella]

For example—Superpowers. To install:

1. /plugin marketplace add obra/superpowers-marketplace
2. /plugin install superpowers@superpowers-marketplace

Now we're installed for Claude Code. We want to use Superpowers in Codex, and voila, Skillshare collect + sync works!

BUT

One week goes by, and Superpowers pushes an update. Our source is truth is Claude Code's marketplace because we used it to install the plugin. Now the SKILL.md files are new, there's a new .py file for something added to the Superpowers repo. Since the update was automatic and I'm unaware of changes. I continue calling the plugin, which is now outdated, because my system looks at Skillshare as the source of truth.

There needs to be some kind of automatic(?) collection process that keeps plugins, and perhaps CLI skills in sync with Skillshare. If someone installs a plugin on Claude Code, or if they install a plugin on Codex, or whatever harness they use for the entry-point, future updates collect into Skillshare.