flowcore-io · jbiskur · Aug 11, 2026 · Aug 11, 2026
@@ -0,0 +1,20 @@
+{
+  "name": "usable",
+  "description": "Knowledge-first workflow for coding agents, backed by Usable.",
+  "owner": {
+    "name": "Flowcore",
+    "email": "support@usable.dev",
+    "url": "https://www.usable.dev"
+  },
+  "plugins": [
+    {
+      "name": "usable",
+      "source": "./",
+      "description": "Search your team's knowledge before you build. Retrieves complete sources, separates evidence from assumptions, and verifies before claiming success.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Flowcore"
+      }
+    }
+  ]
+}
@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "usable",
+  "description": "Knowledge-first workflow backed by Usable. Search team knowledge before implementing, retrieve complete sources, separate evidence from assumptions, and verify before claiming success.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Flowcore",
+    "email": "support@usable.dev",
+    "url": "https://www.usable.dev"
+  },
+  "homepage": "https://www.usable.dev",
+  "repository": "https://github.com/flowcore-io/usable-agent-plugin",
+  "license": "MIT",
+  "keywords": [
+    "usable",
+    "knowledge",
+    "memory",
+    "mcp",
+    "retrieval",
+    "verification"
+  ]
+}
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "usable": {
+      "type": "http",
+      "url": "https://usable.dev/api/mcp",
+      "oauth": {
+        "clientId": "mcp_oauth_client"
+      }
+    }
+  }
+}
@@ -8,27 +8,49 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ## Unreleased
 
 ### Added
+- Claude Code support alongside the Agent Plugins standard: `.claude-plugin/marketplace.json`,
+  `.claude-plugin/plugin.json`, and `.mcp.json`. Only `skills/` is shared between the two
+  formats; filenames and one transport identifier differ, so both sets ship.
+- The public OAuth client ID `mcp_oauth_client` is declared for Claude Code in `.mcp.json`
+  under `oauth.clientId`, and documented for both clients' `add` commands.
+- Drift guards for the duplicated configuration: the validator asserts `mcp.json` and
+  `.mcp.json` declare the same servers pointing at the same URLs, and that the two plugin
+  manifests agree on name and version.
+- `oauth` blocks are validated fail-closed: only `clientId`, `callbackPort`, and `scopes` are
+  permitted, so a client secret cannot ship by being an unrecognised field.
 - Usable brand assets: `assets/usable-icon.svg` (composer icon) and `assets/usable-logo.png`
   (600×600 logo), taken from the Usable brand kit.
 - Codex interface metadata under the `extensions["com.openai"]` namespace in `plugin.json`:
   display name, short and long descriptions, developer name, category, website, privacy and
   terms URLs, brand colour `#347cbf`, icon and logo paths, and a default prompt.
 - Validation of client-extension file references: paths must be plugin-relative, must stay
-  inside the plugin root, and must exist. Three new self-tests cover a missing asset, a path
-  escaping the root, and a namespace without a reverse domain.
+  inside the plugin root, and must exist.
+- Twelve further self-tests covering all of the above; the suite is now 27 cases.
 
 ### Changed
 - `assets/` is now included in the release archive allowlist.
 - `homepage` and author URL now use the canonical `https://www.usable.dev`, which is where
   the apex domain redirects.
 
-### Notes
-- Codex surfaced the plugin with a generic icon and "Website: Unavailable" because it reads
-  presentation metadata from an `interface` object, not from the Agent Plugins `homepage`
-  field. **Whether Codex reads that object from the inline `com.openai` extension has not been
-  verified visually** — the CLI exposes no way to inspect resolved interface metadata. If the
-  icon and website still do not render, the fallback is a `.codex-plugin/plugin.json` overlay,
-  which must be added carefully because a malformed overlay could disturb skill discovery that
+### Fixed
+- `.claude-plugin/` and `.mcp.json` added to the release-archive allowlist. Without this the
+  published artifact would have shipped a package Claude Code could not install.
+
+### Verified
+- Claude Code 2.1.227 on macOS: `claude plugin marketplace add ./` registers the marketplace
+  and `claude plugin install usable@usable` installs and enables the plugin at 0.1.0.
+
+### Known limitations
+- **A user-level MCP server named `usable` shadows the plugin's declaration.** Confirmed on
+  Claude Code, where no `plugin:usable:usable` server appeared while other plugins' servers did.
+  This upgrades the Codex-side collision risk from hypothesis to confirmed behaviour, and it
+  means neither client's MCP step can be verified on a machine that already has such an entry.
+- Claude Code skills are not yet confirmed reaching the model. The plugin installs, but Claude
+  Code exposes no CLI listing of available skills, so this needs an interactive check.
+- Whether Codex reads the `interface` object from the inline `com.openai` extension is still
+  **unverified visually** — the CLI exposes no way to inspect resolved interface metadata. If the
+  icon and website do not render, the fallback is a `.codex-plugin/plugin.json` overlay, which
+  must be added carefully because a malformed overlay could disturb skill discovery that
   currently works.
 
 ## 0.1.0 — 2026-08-07

@@ -17,6 +17,7 @@ assumptions, and verify before claiming success.
 | [`usable-knowledge-workflow`](skills/usable-knowledge-workflow/SKILL.md) | Read-first loop: search Usable, fetch complete sources, rank by verification and freshness, write a knowledge receipt, verify before claiming done |
 | [`usable-knowledge-capture`](skills/usable-knowledge-capture/SKILL.md) | Write verified outcomes back to Usable — gated on verification, deduplication, and explicit user confirmation |
 | [`mcp.json`](mcp.json) | Declares the hosted Usable MCP server at `https://usable.dev/api/mcp` over `streamable-http` |
+| [`.mcp.json`](.mcp.json) | The same server for Claude Code, which uses transport `http` and reads a different filename |
 
 No credentials ship in this package, anywhere. The **release archive** contains only Markdown
 and JSON — no executable code, no dependencies, no install hooks. A **marketplace or Git
@@ -27,22 +28,34 @@ All instruction text is in `skills/`. Read it before enabling.
 
 ## Install
 
-**Codex** (verified — loads the package and both skills):
+The package ships manifests for both the Agent Plugins standard and Claude Code's own format,
+so it installs in either.
+
+**Codex** — loads the package and both skills:
 
 ```bash
 codex plugin marketplace add flowcore-io/usable-agent-plugin --ref main
 codex plugin add usable@usable
 ```
 
-Confirm the model can see them:
-
 ```bash
 codex exec "List the names of every skill available to you, one per line, then stop."
 # expect: usable:usable-knowledge-workflow / usable:usable-knowledge-capture
 ```
 
-Other clients, tagged releases with checksum verification, upgrade, rollback, and uninstall:
-[`docs/installation.md`](docs/installation.md) and [`examples/codex/README.md`](examples/codex/README.md).
+**Claude Code** — marketplace registers, plugin installs and enables:
+
+```bash
+claude plugin marketplace add flowcore-io/usable-agent-plugin
+claude plugin install usable@usable
+```
+
+Per-client detail: [`examples/codex/`](examples/codex/README.md) and
+[`examples/claude-code/`](examples/claude-code/README.md). Tagged releases with checksum
+verification, upgrade, rollback, and uninstall: [`docs/installation.md`](docs/installation.md).
+
+If your client already has an MCP server named `usable`, it shadows the plugin's declaration —
+see [authentication](docs/authentication.md).
 
 ## Authentication
 

@@ -59,8 +59,32 @@ GET https://usable.dev/.well-known/oauth-authorization-server
 | `grant_types_supported` | `authorization_code`, `refresh_token`, `client_credentials`, `device_code` |
 | `token_endpoint_auth_methods_supported` | `client_secret_basic`, `client_secret_post`, `none` |
 
-Dynamic client registration is available, so clients do not need a pre-registered client ID.
-Public clients may register with `none` and use PKCE.
+Dynamic client registration is available, so a client can obtain its own ID. Public clients may
+register with `none` and use PKCE.
+
+### The default client ID
+
+Usable's default MCP configuration uses the public client ID **`mcp_oauth_client`**. Clients
+that do not implement dynamic registration, or that prefer a fixed ID, should use it:
+
+```bash
+# Claude Code
+claude mcp add --transport http usable https://usable.dev/api/mcp --client-id mcp_oauth_client
+
+# Codex
+codex mcp add usable --url https://usable.dev/api/mcp --oauth-client-id mcp_oauth_client
+```
+
+An OAuth `client_id` is a public identifier, not a secret — it is safe in a shared config and
+in this repository. This package declares it for Claude Code in `.mcp.json` under
+`oauth.clientId`, which is the field Claude Code reads.
+
+A client **secret** is a different thing entirely and must never be packaged. CI enforces the
+distinction: the validator permits only `clientId`, `callbackPort`, and `scopes` inside an
+`oauth` block and fails on anything else, so a secret cannot slip in by being unrecognised.
+
+The Agent Plugins `mcp.json` stays URL-only. Its schema does not define an `oauth` field, and
+inventing one risks rejection by a strict client.
 
 **4. Authorize with PKCE**
 
@@ -98,6 +122,27 @@ Do **not** work around a headless client by committing a shared static credentia
 `mcp.json` — that defeats per-user authorization and rotation. Track this in
 [open decision #5](../README.md#open-decisions).
 
+## A user-level server of the same name shadows this one
+
+If your client already has an MCP server named `usable` at user or project scope, that entry
+takes precedence and the plugin's declaration is silently ignored. Confirmed on both Claude
+Code and Codex.
+
+Two consequences worth knowing:
+
+- You cannot tell from `claude mcp list` or `codex mcp list` whether a `usable` server came
+  from this plugin or from your own config. On Claude Code a plugin-provided server appears as
+  `plugin:usable:usable`; a bare `usable` is yours, not the plugin's.
+- If your existing entry authenticates with a static bearer token rather than OAuth, you keep
+  that behaviour — and none of this package's credential hygiene applies to it. A long-lived
+  token in a client config is worth replacing with the OAuth flow.
+
+To let the plugin's declaration take effect, remove or rename the user-level entry:
+
+```bash
+claude mcp remove usable      # or: codex mcp remove usable
+```
+
 ## Revoking access
 
 Revoke the client's grant in your Usable account settings, then remove the stored

@@ -18,10 +18,10 @@ support based on a client advertising Agent Plugins compatibility.
 
 Legend: ✅ verified · ⚠️ partial · ❌ not supported · ⏳ untested
 
-| Client | Plugin loading | Agent Skills | `streamable-http` MCP | OAuth 2.1 + PKCE | OS tested | Last tested | Status |
+| Client | Plugin loading | Agent Skills | Remote MCP | OAuth 2.1 + PKCE | OS tested | Last tested | Status |
 |---|---|---|---|---|---|---|---|
-| Codex CLI 0.146.0 | ✅ | ✅ | ⏳ | ⏳ | macOS | 2026-08-07 | Partial (steps 1 of 5) |
-| Claude Code | ⏳ | ⏳ | ⏳ | ⏳ | — | — | Untested |
+| Codex CLI 0.146.0 | ✅ | ✅ | ⏳ | ⏳ | macOS | 2026-08-07 | Partial (1 of 5) |
+| Claude Code 2.1.227 | ✅ | ⏳ | ⏳ | ⏳ | macOS | 2026-08-11 | Partial (1 of 5) |
 | Warp / Oz | ⏳ | ⏳ | ⏳ | ⏳ | — | — | Untested |
 | Cursor | ⏳ | ⏳ | ⏳ | ⏳ | — | — | Untested |
 | Opencode | ⏳ | ⏳ | ⏳ | ⏳ | — | — | Untested |
@@ -30,9 +30,29 @@ Launch targets are [open decision #2](../README.md#open-decisions). Two clients
 ✅ across all columns before `1.0.0`.
 
 Agent Plugins 1.0.0 was published on 2026-08-06 with launch support announced for ChatGPT and
-Codex, Cursor, GitHub Copilot, Kiro, and VS Code. Claude Code is not among them — it uses its
-own `.claude-plugin/plugin.json` format — so Claude Code support should be treated as
-unlikely until tested, not merely unverified.
+Codex, Cursor, GitHub Copilot, Kiro, and VS Code. Claude Code is not among them and uses its
+own manifest format, so this package ships both sets of manifests — see
+[Supporting two formats](#supporting-two-formats).
+
+## Supporting two formats
+
+The two clients disagree on filenames and on one transport identifier, so both are shipped.
+Only `skills/` is genuinely shared.
+
+| Concern | Agent Plugins | Claude Code |
+|---|---|---|
+| Plugin manifest | `plugin.json` | `.claude-plugin/plugin.json` |
+| Marketplace catalogue | `.agents/plugins/marketplace.json` (Codex) | `.claude-plugin/marketplace.json` |
+| MCP config | `mcp.json` | `.mcp.json` |
+| Remote transport | `streamable-http` | `http` |
+| Skills | `skills/` | `skills/` |
+
+The duplication is a drift risk, so CI guards it: the validator asserts the two MCP documents
+declare the same servers pointing at the same URLs, and that the two plugin manifests agree on
+name and version. Editing one and forgetting the other fails the build.
+
+This mirrors what other multi-client plugins do — Slack's official Claude Code plugin ships
+`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/` and `.agents/` side by side.
 
 ## Per-client notes
 
@@ -70,9 +90,29 @@ executed by the client, but the "Markdown and JSON only" property holds strictly
 release archive, not for a marketplace install.
 
 ### Claude Code
-Untested, and expected to need a separate format. Claude Code uses `.claude-plugin/plugin.json`
-and reads project skills from `.claude/skills/`; it was not part of the Agent Plugins launch
-lineup. Supporting it may require a client extension namespace or a distinct package.
+Partially verified on 2026-08-11 against Claude Code 2.1.227 on macOS.
+
+**Step 1 passed.** The marketplace registers and the plugin installs and enables:
+
+```
+usable@usable   Version: 0.1.0   Scope: user   Status: ✔ enabled
+```
+
+See [`../examples/claude-code/README.md`](../examples/claude-code/README.md) for exact steps.
+Note `claude plugin marketplace add ./` — a bare `.` is rejected.
+
+**Skills not yet confirmed reaching the model.** The package installs, but we have not yet
+observed `usable:usable-knowledge-workflow` and `usable:usable-knowledge-capture` offered in a
+session. Claude Code exposes no CLI listing of available skills, so this needs an interactive
+check.
+
+**Step 2 inconclusive, and for an identified reason.** The test machine had a user-level
+`[mcpServers.usable]` entry in `~/.claude.json` pointing at the same URL, which shadows the
+plugin's declaration — no `plugin:usable:usable` server appeared, while other plugins' servers
+did show under that prefix. This is direct evidence of the collision risk previously recorded
+as a hypothesis for Codex. Re-test on a machine with no pre-existing `usable` server.
+
+**Steps 3–5 untested.**
 
 ### Warp / Oz
 Untested. Supports MCP servers and skills natively; needs verification of whether an Agent

@@ -7,9 +7,11 @@ client advertising Agent Plugins compatibility.
 
 - [`codex/`](codex/) — verified 2026-08-07 on Codex CLI 0.146.0. Loads the package and both
   skills; MCP and OAuth steps still outstanding.
+- [`claude-code/`](claude-code/) — verified 2026-08-11 on Claude Code 2.1.227. Marketplace
+  registers and the plugin installs and enables; skills-reaching-the-model and MCP steps still
+  outstanding.
 
-Still to test: Cursor, Warp / Oz, Opencode, and Claude Code (which uses its own plugin format
-and was not part of the Agent Plugins launch lineup).
+Still to test: Cursor, Warp / Oz, Opencode.
 
 Each entry records the install commands, how to verify, the tested client version, and any
 deviations found. See [`../docs/supported-clients.md`](../docs/supported-clients.md) for the