fix(claude-code): create-only skill registration with a PUT update route (LIT-4110)

[ryan-crabbe-berri]

Relevant issues

Linear ticket

Resolves LIT-4110

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Screenshots / Proof of Fix

Backend, against a local proxy on :4000 with an admin key (the marketplace mutation routes are admin-gated by RouteChecks, so use a PROXY_ADMIN key):

1. Create a skill, then try to create it again under the same name; the second POST now returns 409 instead of silently overwriting the first

curl -sS -X POST http://localhost:4000/claude-code/plugins -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"demo-skill","source":{"source":"url","url":"https://gitlab.com/group/repo"}}'
curl -sS -X POST http://localhost:4000/claude-code/plugins -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"demo-skill","source":{"source":"url","url":"https://gitlab.com/group/other"}}'
# second call -> 409 {"detail":{"error":"A skill named 'demo-skill' already exists. Update the existing skill instead of adding it again."}}

2. Update it through the new PUT, then PUT a name that does not exist

curl -sS -X PUT http://localhost:4000/claude-code/plugins/demo-skill -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"source":{"source":"github","repo":"org/demo"},"version":"2.0.0"}'
# -> {"status":"success","action":"updated", ...}
curl -sS -X PUT http://localhost:4000/claude-code/plugins/does-not-exist -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"source":{"source":"github","repo":"org/x"}}'
# -> 404 {"detail":{"error":"Plugin 'does-not-exist' not found"}}

UI: open http://localhost:4000/ui/?page=skills, click Add Skill and register a name, then Add Skill again with the same name; the toast now reads the backend reason ("A skill named '...' already exists. ...") rather than a generic failure or a raw JSON blob

Type

🐛 Bug Fix
🆕 New Feature

Changes

POST /claude-code/plugins upserted by name, so re-adding a skill whose name already existed silently overwrote the stored skill's source and metadata while still reporting success. The "Add New Skill" button posts here, so a name collision clobbered an unrelated skill with no signal to the user. This makes POST create-only: it returns 409 when the name exists, with a unique-violation guard so a concurrent insert that slips past the existence pre-check maps to the same 409 rather than a 500. Updates move to a new explicit PUT /claude-code/plugins/{plugin_name} that returns 404 when the name is missing. Both routes stay admin-gated exactly as before through RouteChecks (the route is not an LLM API route and is in no non-admin allowlist), so only PROXY_ADMIN, or a key that lists the route in its own allowed_routes, can mutate the marketplace

PUT is a full replace, not a merge, and the docstring says so; an omitted optional field resets to its default. To avoid a silent version downgrade on a partial edit, the shared mutable fields live on a PluginSpec base where RegisterPluginRequest keeps the create-time version default of 1.0.0 while UpdatePluginRequest defaults version to None. RegisterPluginRequest's generated schema is unchanged, so the dashboard's existing type alias is unaffected; the dashboard types (schema.d.ts) and the lazy OpenAPI snapshot are regenerated for the new route

On the dashboard, the add-skill form rendered the raw HTTPException envelope on any failure because deriveErrorMessage did not unwrap an object-shaped detail ({"detail": {"error": ...}}), so the new 409 would have reached the user as a JSON blob. That is fixed at the client layer for every handler that returns detail={"error": ...}, and the form surfaces the message directly so the conflict reads as a sentence

Tests cover the create-only 409 (and that the stored record is left untouched on conflict), the unique-violation race mapping to 409, the PUT replacing the source, the PUT 404, the client unwrapping object-shaped detail, and the form surfacing the conflict message

Both mutation handlers now return the typed RegisterPluginResponse model and declare it as response_model, so the OpenAPI spec, the lazy snapshot, and the dashboard's schema.d.ts carry the real 200 shape instead of unknown; the JSON on the wire is unchanged. The stored manifest is built from model_dump rather than a hand-rolled field list, and update_plugin drops an unused auth parameter since the route dependency already enforces auth. The branch also merges litellm_internal_staging; the client-side detail unwrapping landed there concurrently as deriveDetailMessage, so this PR's client change reduces to the detail.error.message and detail.message fallbacks

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_lit_4110_skill_create_only_409 (1d84555) with litellm_internal_staging (e64536c)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (24dbd2b) during the generation of this report, so c93a336 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[greptile-apps]

Greptile Summary

This PR fixes a silent-overwrite bug in the Claude Code plugin registry: POST /claude-code/plugins was an upsert that clobbered existing plugins on name collision; it is now create-only (returns 409 on duplicate, with a race guard mapping UniqueViolationError to 409). A new PUT /claude-code/plugins/{name} route handles explicit updates with 404-on-missing semantics. The dashboard's error-message unwrapping is improved so the 409 conflict reason reaches the user as a readable sentence rather than a raw JSON blob.

• Backend: PluginSpec base extracts shared mutable fields; register_plugin gains a pre-check + UniqueViolationError catch; update_plugin is a new full-replace handler; both return typed RegisterPluginResponse instead of raw dicts.
• Client: deriveDetailMessage gains fallbacks for detail.error.message / detail.message shapes; the add-skill form surfaces the backend message verbatim without a generic prefix.
• Tests: New unit tests cover the 409 duplicate, stored-record immutability on conflict, the concurrent unique-violation→409 mapping, PUT replace, PUT 404, and DB error→500; assertions in existing tests updated for the typed response model.

Confidence Score: 5/5

Safe to merge — the auth boundary is unchanged (both mutation routes remain admin-gated through the same RouteChecks dependency), and all new behaviour is covered by unit tests.

The change is narrowly scoped to the plugin registry: POST is now create-only with a correct TOCTOU guard, PUT is a straightforward full-replace with 404-on-missing, and the client unwrapping fix is additive. No critical path is touched, auth enforcement is preserved at the route level, and the new tests exercise all the added branches including the race condition.

Files Needing Attention: No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/anthropic_endpoints/claude_code_endpoints/claude_code_marketplace.py	Adds a create-only POST (returning 409 on duplicate name with a TOCTOU race guard via UniqueViolationError catch) and a new PUT update route with 404-on-missing; refactors manifest building into _build_plugin_manifest; response shape moved to typed Pydantic model
litellm/types/proxy/claude_code_endpoints.py	Introduces PluginSpec base with shared mutable fields; RegisterPluginRequest inherits and adds name; UpdatePluginRequest inherits and overrides version default to None so omitting it on PUT clears the field rather than defaulting to "1.0.0"
tests/test_litellm/proxy/anthropic_endpoints/test_claude_code_marketplace.py	Stateful mock upgraded to track stored records; existing update-on-duplicate test replaced with create-only 409 test (with stored-record immutability assertion), plus new tests for PUT replace, PUT 404, concurrent unique-violation→409 mapping, and DB error→500
ui/litellm-dashboard/src/lib/http/client.ts	Adds a fallback branch in deriveDetailMessage for object-shaped details that expose error.message or message, so the 409 conflict reason surfaces as a readable string instead of the raw JSON envelope
ui/litellm-dashboard/src/app/(dashboard)/skills/_components/add_plugin_form.tsx	Removes the "Failed to register skill: " prefix wrapper so the backend conflict message is shown verbatim to the user
tests/pass_through_unit_tests/test_claude_code_marketplace.py	Updates assertions from dict-access to typed model attribute access (response["status"] → response.status) to match the new RegisterPluginResponse return type
ui/litellm-dashboard/src/lib/http/client.test.ts	Adds a test verifying that {detail: {error: "..."}} shaped FastAPI HTTPException responses are unwrapped to the conflict string rather than JSON-dumped
ui/litellm-dashboard/src/lib/http/schema.d.ts	Generated OpenAPI snapshot updated: adds UpdatePluginRequest, PluginResponse, RegisterPluginResponse schemas and the new PUT operation; POST response typed as RegisterPluginResponse instead of unknown
ui/litellm-dashboard/src/app/(dashboard)/skills/_components/add_plugin_form.test.tsx	New test verifies that the 409 conflict reason from the backend is surfaced verbatim (not buried under a generic prefix)
ui/litellm-dashboard/src/components/networking.tsx	JSDoc comment updated to reflect create-only semantics (mentions 409 on duplicate name)

_{Reviews (4): Last reviewed commit: "Merge remote-tracking branch 'origin/lit..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ryan-crabbe-berri]

@greptileai re review

[ryan-crabbe-berri]

@greptileai re review

[ryan-crabbe-berri]

@greptileai re review