minasarustamyan efc607f3ee

feat(cli): agnes marketplace search/detail/add/remove + retire stale subcommands (#280 )

* feat(cli): agnes marketplace search/detail/add/remove + retire stale subcommands

Unified CLI surface for the v28+ marketplace: search across Curated and
Flea Market (RBAC-filtered server-side), drill into a single item's
detail, add/remove from your stack. Replaces opt-out era commands that
no longer reflect how users compose their stack.

CLI changes:
- Added: agnes marketplace {search,detail,add,remove}
- Removed: agnes my-stack toggle (opt-out semantics, curated-only)
- Removed: agnes store {list,show,install,uninstall} (consumer-side ops
  moved under marketplace; store now covers only creator-side upload,
  update, delete, mine)

ID format unifies curated and flea: marketplace_id/plugin_name (slash)
routes to /api/marketplace/curated/..., bare UUID routes to
/api/store/entities/... (flea bundles skills/agents into a synthetic
plugin server-side, so the analyst sees a single add/remove surface).

Templates:
- claude_md_template.txt: rewritten marketplace section as operational
  guidance for Claude Code (discovery, stack management, behaviour
  notes). Dropped the static {% if marketplaces %} listing — the CLI is
  the source of truth for what's in the stack at any moment, so a
  snapshot rendered at init time would lie the moment the user runs
  agnes marketplace add/remove. Same discipline already applied to
  tables and metrics.
- agnes_workspace_template.txt: cheat sheet adds 5 marketplace
  one-liners; keeps the file's reference-doc tone (the original
  commit's intent: 'what is this thing, how does it work, how do I
  uninstall it').

Docs: HOWTO/05-customizing-skills.md rewritten around the new CLI flow;
the opt-out section is replaced by 'Removing items from your stack'.

Tests: new test_cli_marketplace.py covers all four subcommands incl.
RBAC/409 paths (system plugin guard, not-approved flea entity);
test_cli_store.py trimmed to the retained creator-side commands.

* release: 0.54.1 — agnes marketplace CLI redesign + retire stale subcommands

Last commit on the PR per CLAUDE.md hard rule. Patch bump (0.54.0 →
0.54.1) bundling the BREAKING removals of `agnes my-stack toggle` and
`agnes store {list,show,install,uninstall}` plus the new unified
`agnes marketplace {search,detail,add,remove}` surface.

No DB migration; no operator-facing config change. Operators on
floating tags (`:stable`) auto-upgrade transparently. Analyst CLI
upgrade prompt fires on next `agnes pull`; users invoking the
retired commands get "No such command" with the new `agnes
marketplace` substitution called out in the BREAKING bullets.

---------

Co-authored-by: Minas Arustamyan <arustamyan.minas@gmail.com>
Co-authored-by: ZdenekSrotyr <zdenek.srotyr@keboola.com>

2026-05-13 05:20:56 +00:00

4.2 KiB

Raw Blame History

Customising your skills

Agnes serves a curated set of Claude Code skills, agents, and plugins through your instance's marketplace. You can extend your personal stack in two ways: adding items from the Curated and Flea Market tabs, and uploading your own.

Surface 1: Discovering and adding from the marketplace

You have two paths: the web UI at /marketplace, or the agnes marketplace CLI from any workspace.

Curated tab (admin-managed)

Your admin has registered one or more git repos as marketplaces. The plugins from those repos appear on the Curated tab at /marketplace (only those visible to your RBAC groups).

The Most Popular section (top of /marketplace) shows the 8 most-invoked plugins over the last 30 days.
Sort options: Recent (default), Most used (30d), Trending (week-over-week).

Flea tab (community uploads)

The Flea Market tab shows skills, agents, and plugins uploaded by any analyst on the instance, after admin approval.

Using the CLI

# Search across Curated + Flea Market
agnes marketplace search -q "pdf"
agnes marketplace search --type skill --source curated

# Full detail — use cases, contents, examples
agnes marketplace detail <id>

# Add to / remove from your stack
agnes marketplace add <id>
agnes marketplace remove <id>

# What's currently in my stack?
agnes my-stack show

ID format: curated items are marketplace_id/plugin_name, Flea items are UUIDs.

Applying changes to Claude Code

After add / remove, run inside Claude Code:

/update-agnes-plugins

That installs/updates/removes the corresponding plugins in your local Claude Code session. The SessionStart hook detects pending updates automatically and surfaces a hint, so you can wait for the next session if you prefer.

Surface 2: Uploading your own plugin

If you've built a Claude Code plugin (a .claude-plugin/ directory with plugin.json + commands), you can share it on the flea market.

Step 1: Prepare your plugin

Your plugin directory should contain at minimum:

my-plugin/
└── .claude-plugin/
    ├── plugin.json       # name, description, version
    └── commands/         # one .md file per command
        └── my-command.md

Step 2: Submit via the upload form

Navigate to /store/new on your Agnes instance.
Fill in the name, description, and upload the plugin archive (.zip or a git repo URL).
Submit. Your submission enters the approval queue.

Step 3: Guardrails review

Submissions go through src/store_guardrails/ — an LLM-gated review that checks for:

Harmful or policy-violating content
Malformed plugin.json
Commands that look dangerous or misleading

If the guardrail rejects your submission, you'll see a reason. Fix and resubmit.

Step 4: Admin approval

After guardrails pass, your submission lands in the admin approval queue at /admin/store. An admin reviews and approves or rejects it. There is no per-team or self-serve approval in v1 — admin sign-off is required.

Once approved, the plugin appears on the Flea tab and becomes installable by other analysts.

After approval

# Add it to your stack (or do it from the Flea tab on the web)
agnes marketplace add <entity-id>

# Verify it's in your stack
agnes my-stack show

Then run /update-agnes-plugins inside Claude Code to install/activate the bundle.

Removing items from your stack

If you no longer want a plugin/skill/agent in your stack:

agnes marketplace remove <id>

Or click "Remove from stack" on the marketplace detail page in the web UI.

System plugins (admin-pinned for the org) cannot be removed — the API returns 409. Your admin's RBAC grants are unaffected by your own add/remove choices.

Notes

Same-named plugins from two upstream marketplaces collide by design: RBAC decides which one your feed serves. If you see unexpected behaviour after an admin adds a second marketplace, check /marketplace/info — it exposes both name and prefixed_name for disambiguation.
No team-level ACL in v1 for flea market plugins — guardrails + admin approval are the gatekeepers.
Curated > flea precedence: if a curated plugin and a flea plugin share the same name, the curated one wins in your stack.

4.2 KiB Raw Blame History