Align install with the skills CLI ecosystem (npx skills add, per-agent paths, multi-agent targeting)

[fujibee]

Motivation

vercel-labs/skills ships a unified installer that targets 70+ agents with a single command:

npx skills add vercel-labs/agent-skills -a claude-code -a cursor -a opencode

It maintains a per-agent path registry (project + global scope) and drops the skill/rule files into each agent's conventional location, e.g.:

agent	project	global
Claude Code	.claude/skills/	~/.claude/skills/
Cursor	.agents/skills/	~/.cursor/skills/
OpenCode	.agents/skills/	~/.config/opencode/skills/
…70+ more

agmsg today ships its own install.sh + npx bootstrapper that installs to ~/.agents/skills/agmsg/ and selects a SKILL.md template via --agent-type. Aligning with the skills convention would:

• make agmsg installable into any of those 70+ agents with one command (the Add Cursor (cursor-agent CLI) support #131 Cursor request, and every future runtime, comes "for free");
• reuse a maintained per-agent path registry instead of growing our own --agent-type map;
• lower onboarding friction and meet users where their agent already looks for skills.

This pairs naturally with the #181 manifest-driven type registry — we already describe each type as data.

Two directions (not mutually exclusive)

A. Make agmsg consumable by the skills CLI. Structure/publish agmsg so npx skills add fujibee/agmsg -a <agent> places it correctly. Lowest effort, maximum reach.

B. Adopt the same conventions in agmsg's own installer. Add -a/--agent multi-target, project+global scopes, and a per-agent path map, built on the type manifests.

Wrinkle to design around

agmsg is more than a static instruction file: it has runtime scripts + shared SQLite state under ~/.agents/skills/agmsg/, plus per-agent delivery hooks (SessionStart/Stop, .cursor/rules/agmsg.mdc, etc.). The skills model places instruction/skill files per agent; agmsg's shared runtime/state and delivery wiring need to map onto that. The likely shape: use the skills install path for the skill/instruction file while keeping one shared runtime + DB, and keep delivery-hook registration (delivery.sh set) as the per-project step.

Note a path collision worth reconciling: the skills CLI uses .agents/skills/ as the project skills dir for some agents, while agmsg's global runtime root is ~/.agents/skills/.

Asks

• Decide direction A vs B (or A-first, B-later).
• Scope target (1.2.0?).

Ref: https://github.com/vercel-labs/skills#supported-agents

[fujibee]

Decision: direction A first (B deferred)

Going with A-first: ship direction A (make agmsg consumable by npx skills add) in 1.1.1; defer direction B (reworking agmsg's own installer with -a multi-agent, project+global scopes, a per-agent path map) to 1.2.0. A gives the reach with low effort; B carries the installer rework and the path-collision design and is not needed for the reach.

Direction A — findings

• agmsg is already largely consumable: it ships a top-level SKILL.md with valid name + description frontmatter, plus openai.yaml and .claude-plugin/marketplace.json + plugin.json. The skills CLI discovers a repo by its SKILL.md (repo root, skills/, or agent dirs) and installs the whole skill directory. So npx skills add fujibee/agmsg already resolves and installs the instruction layer today.
• Reach: the skills CLI registry (src/agents.ts) defines ~104 agents (27 universal + 77 agent-specific); the README advertises "70+". Link to the supported-agents list rather than asserting a number.
• Key convergence: the skills CLI's global canonical store for universal agents is ~/.agents/skills/ — the same path as agmsg's runtime root. A global install lands the skill exactly where agmsg's runtime already lives. Convergence, not collision.

What direction A requires

1. Require/document global install (npx skills add fujibee/agmsg -g). The project-scope default writes to ./.agents/skills/agmsg/ inside the current project, which would create a second per-project copy and a second SQLite DB — breaking agmsg's one-machine-global-runtime model. The per-project concern must remain only delivery-hook registration (delivery.sh set <project_path>), never a per-project copy of the skill + DB.
2. Self-bootstrap without install.sh for skills-CLI installs. The current SKILL.md Step 0 bootstrap points at a Claude-plugin cache path; it must also handle the skills-CLI case (vendor a minimal bootstrap into the installed skill dir, or fetch/run it from there) so first invocation materializes the shared runtime/DB in place.
3. Keep DB / run/ / teams/ out of the installed skill payload — they belong only to the single shared runtime. Verify --copy mode (non-symlink) does not fork state and preserves executable bits on the shipped scripts.
4. Verify behavior when ~/.agents/skills/agmsg/ already exists (overwrite / merge / refuse / backup) before relying on it — agmsg installs commonly have a pre-existing runtime there.

The skills CLI has no post-install/lifecycle hook mechanism, which is why hook wiring stays a separate per-project step — consistent with how agmsg already separates skill content from delivery wiring.

Note on grok-build

grok-build is not in the skills CLI registry, so direction A does not cover it — Grok Build is added via agmsg's own type (tracked separately). A is reach for the ~104 skills-CLI agents; grok-build is its own path.

This issue tracks direction A; a follow-up will be opened for direction B (1.2.0).