Usable Agent Plugin

A portable Agent Plugins 1.0.0 package that gives coding agents a knowledge-first workflow backed by Usable: search what the team already decided before implementing, retrieve complete sources, separate evidence from assumptions, and verify before claiming success.

Status: pre-release (0.2.0). Codex is partially verified — the package loads and both skills reach the model. No client has completed all five acceptance steps, so none is listed as fully supported. See docs/supported-clients.md.

Component	What it does
`usable-knowledge-workflow`	Read-first loop: search Usable, fetch complete sources, rank by verification and freshness, write a knowledge receipt, verify before claiming done
`usable-knowledge-capture`	Write verified outcomes back to Usable — gated on verification, deduplication, and explicit user confirmation
`mcp.json`	Declares the hosted Usable MCP server at `https://usable.dev/api/mcp` over `streamable-http`
`.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 install materialises the repository, so scripts/ and tests/ are present in the installed copy; the client does not execute them, but they are there.

All instruction text is in skills/. Read it before enabling.

Install

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:

codex plugin marketplace add flowcore-io/usable-agent-plugin --ref main
codex plugin add usable@usable

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

Claude Code — marketplace registers, plugin installs and enables:

claude plugin marketplace add flowcore-io/usable-agent-plugin
claude plugin install usable@usable

Per-client detail: examples/codex/ and examples/claude-code/. Tagged releases with checksum verification, upgrade, rollback, and uninstall: docs/installation.md.

If your client already has an MCP server named usable, it shadows the plugin's declaration — see authentication.

Authentication

Nothing to configure by hand. The plugin declares a URL; your client performs OAuth 2.1 with PKCE and stores the tokens itself.

For a read-only install, grant fragments.read and workspace.read. Add fragments.create and fragments.update only if you want the capture skill to work.

Details and the verified discovery chain: docs/authentication.md.

Never add a token, API key, client secret, or static Authorization header to mcp.json. CI rejects it.

Documentation

Installation — install, upgrade, rollback, uninstall
Authentication — OAuth 2.1 discovery chain, scopes, revocation
Supported clients — compatibility matrix and known deviations
Permissions and data flow — for security review
Threat model — threats, mitigations, residual risk
Troubleshooting — diagnosis by symptom
OpenAI submission — ZIP upload, review cases, and remaining dashboard gates

Validate locally

node scripts/validate-package.mjs
node tests/smoke/validator.test.mjs
node scripts/build-release.mjs

Checks manifest and MCP schema conformance, skill frontmatter and layout, path containment and symlink safety, credential patterns, and OpenAI listing limits. The build produces both tar.gz and an OpenAI submission ZIP with checksums. Requires Node 20+, tar, gzip, zip, and unzip; no Node dependencies. See the submission guide before uploading.

Trust boundary

Agent Plugins 1.0.0 standardizes package structure and loading. It does not define installation, registries, trust, permissions, sandboxing, signatures, portable secrets, updates, or rollback.

Schema validity therefore implies nothing about safety — for this package or any other. Evaluate contents, not conformance. The strongest control available to you is the set of OAuth scopes you actually grant; prompt instructions are not an enforcement boundary.

Open decisions

Tracked from the PRD, unresolved:

~~Repository name~~ — resolved: flowcore-io/usable-agent-plugin
Launch client targets — Codex partially verified; a second client must reach ✅ before 1.0.0
~~License~~ — resolved: MIT
~~Read-only or writeback in v1~~ — resolved: v1 includes verified writeback. Both skills ship, and usable-knowledge-capture is a supported v1 capability rather than a deferred experiment. Writes stay gated on verification, deduplication, redaction, and explicit user confirmation, and they require write scopes the user grants deliberately.
Headless authorization profile — client_credentials and device_code are advertised but neither is wired up or tested
Public data-processing, retention, and revocation disclosure wording
Whether releases need signed attestations in addition to tags and checksums
Ownership of client compatibility testing as client plugin loaders change
Whether the OAuth resource indicator should be https://usable.dev (as the metadata advertises) or https://usable.dev/api/mcp (the endpoint served), and whether token audiences validate either way — untested, needs a real authorization flow

Contributing

See CONTRIBUTING.md. Skill wording changes agent behavior, so those changes get reviewed as carefully as code. Security issues go through SECURITY.md, not public issues.

License

MIT