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.1.0), not yet released. 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`

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

Codex (verified — loads the package and both skills):

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

Confirm the model can see them:

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 and examples/codex/README.md.

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

Validate locally

node scripts/validate-package.mjs

Checks manifest and MCP schema conformance, skill frontmatter and layout, path containment and symlink safety, and credential patterns. Requires Node 20+, no dependencies.

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