Manage User Skills

Use Agent Bridge's existing shared-skill projection. Do not create another skill registry or provider-specific copy workflow.

A Skill is the installed capability. A Collection is only a curated list of ordinary Skill references used for discovery and bulk install/remove convenience; it does not define a second runtime, permission model, provider contract, or dependency graph.

Ownership

• Bundled Agent Bridge Skills live in the active release's skills/ directory and are managed by the release.
• Catalogue-managed Skills are ordinary installed Skills managed through npm run skills -- install <name> --catalogue <source> or the collections convenience commands. Do not edit them through the user-authored path.
• User-authored Skills live canonically at ~/.agents/skills/<skill-name>/SKILL.md (SHARED_MEMORY_HOME takes precedence over HOME when configured).
• User Skills project as symlinks into native provider directories so the canonical Skill remains authoritative:
  • Codex: ~/.codex/skills/<skill-name>
  • Claude: ~/.claude/skills/<skill-name>
  • Antigravity/Agy: ~/.gemini/antigravity-cli/skills/<skill-name>
• Cursor is excluded from that universal projection. The canonical Cursor-native path is ~/.cursor/skills/<skill-name>/SKILL.md and is created only when explicitly requested.
• Do not edit a bundled or catalogue-managed Skill when the user intends to create their own Skill.

Create or save

1. Choose a unique lowercase kebab-case name, 1-64 characters.
2. From the active Agent Bridge release, run npm run skills -- list and reject a name that collides with a bundled Skill.
3. Create ~/.agents/skills/<name>/SKILL.md with standards-compatible frontmatter:

---
name: my-skill
description: Use when ...
---

# My Skill

4. Keep the description non-empty and at most 1024 characters.
5. Project/register the canonical user Skill with:

npm run skills -- project-user <name>

6. If Cursor-native projection is explicitly required, add it with one of:

npm run skills -- project-user <name> --project-cursor
npm run skills -- project-cursor <name>

Do not create duplicate Claude/Codex/Cursor projections unless the operator accepts Cursor's cross-CLI discovery ambiguity. Never overwrite an unmanaged ~/.cursor/skills/<name> path.

7. Verify it:

npm run skills -- verify <name>

Update or repair

Edit only the canonical ~/.agents/skills/<name> content, then run project-user again so the lock hash and native symlinks are refreshed. Finish with verify.

If a managed native projection is missing, rerunning project-user repairs it. If a native path exists but is no longer the expected symlink to the canonical Skill, project-user fails closed instead of overwriting it; inspect that collision before changing or deleting anything.

Do not use verify --fix for user-authored Skills: the generic bundled-skill repair path can replace a conflicting native entry. project-user is the fail-closed repair path for user Skills.

Remove

Only when the user explicitly wants the user Skill removed:

npm run skills -- uninstall-user <name>

This removes the canonical shared Skill, its expected native symlink projections, and its lockfile record. It fails closed if a native path has been replaced with unrelated content. Never use the generic bundled uninstall command for a user-authored Skill.

Completion evidence

Report the canonical path and whether npm run skills -- verify <name> passed. Do not dump the full Skill body unless the user asks for it.