feat(marketplace): add the orpc plugin - #275
Merged
Merged
Conversation
Add the orpc plugin with four skills installed via skills.sh from middleapi/orpc: orpc, orpc-contract, orpc-openapi, and orpc-migrate. Wire the plugin into the Claude, Codex, and Cursor marketplaces, release-please config and manifest, and the README.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Up to standards ✅🟢 Issues
|
amondnet
marked this pull request as ready for review
September 15, 2026 11:52
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a new "orpc" plugin to the marketplace, adding its configuration across Claude, Codex, and Cursor plugin manifests, updating the release-please configuration, and adding the plugin's documentation in the README. It also installs the "orpc" skills (including "orpc", "orpc-contract", "orpc-migrate", and "orpc-openapi") under the ".agents/skills/" directory, managed by "skills-lock.json". Since there are no review comments to evaluate, I have no feedback to provide.
🔍 Tessl Skill Review
|
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | The body is dense and assumes competence, jumping straight to code without explaining what oRPC is, and each bullet carries a concrete technical rule that earns its place. It lands at 4 rather than 5 because the opening framing paragraph ('Contract-first oRPC splits an API into two artifacts...') and a few explanatory bullets could be trimmed further without losing clarity. |
| actionability | █████ 5/5 | Provides fully executable, copy-paste-ready code blocks for every common case — contract definition, implementation, RPC/OpenAPI clients, contract minification, npm SDK factory, and OpenAPI codegen config plus the 'npx @hey-api/openapi-ts' and 'tsdown --dts' commands — matching the level-5 anchor. |
| workflow clarity | ███░░ 3/5 | The body is sequenced by clear stages (Define → Implement → Consume → Ship → Generate), giving an implicit sequence, but there are no explicit validation or verification checkpoints (e.g. type-check the implementer against the contract, verify the shipped contract.json round-trips). No destructive batch operation triggers the hard cap, but the missing checkpoints fit the level-3 anchor better than level 4. |
| progressive disclosure | ████░ 4/5 | No bundle files exist (references/, scripts/, assets/ are absent), and the skill stays self-contained with a dedicated 'Full documentation' section that signals one-level-deep external references (orpc.dev pages and sibling skills) for detail beyond the overview. It is well-structured but the deferral of several in-topic details (OpenAPI routing, dedupe pattern, JsonifiedClient/Smart Coercion) to sibling skills keeps it just short of the level-5 anchor. |
Suggestions:
- Add explicit validation checkpoints to the implementation and shipping stages — e.g. after 'implementer.router({...})', run a type-check confirming handlers satisfy the contract, and after writing contract.json, verify it deserializes on the client before publishing.
- Tighten the opening framing paragraph ('Contract-first oRPC splits an API into two artifacts...') and a few explanatory bullets to push conciseness toward the top anchor.
- Consider bundling the full docs page list or a contract.json example into a references/ file so the in-skill overview can stay lean while keeping all navigation truly one level deep.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Names multiple concrete actions against specific APIs: 'defining the API shape with oc from @orpc/contract, implementing it with implement from @orpc/server, and consuming the contract from typesafe clients', plus 'sharing an API contract', 'generating a contract from an existing OpenAPI spec', and 'publishing a typed API client to npm' — comprehensive coverage matching the level-5 anchor. |
| completeness | █████ 5/5 | Explicitly states both what ('Design oRPC v2 APIs contract-first, defining... implementing... and consuming...') and when ('Use when a project depends on...') with concrete trigger phrases, matching the level-5 anchor that requires clearly answering both what and when. |
| trigger term quality | █████ 5/5 | The 'Use when' clause covers natural user phrasings with synonyms: 'a project depends on @orpc/contract', 'defining a contract with oc', 'implementing a contract with implement', 'sharing an API contract between server and client packages', 'generating a contract from an existing OpenAPI spec', and 'publishing a typed API client to npm' — comprehensive natural-term coverage. |
| distinctiveness conflict risk | █████ 5/5 | Occupies a clear niche (contract-first oRPC) and explicitly routes adjacent work away — 'for core builder, serving, and client work without a contract, use the orpc skill; for REST/OpenAPI exposure... use the orpc-openapi skill' — minimizing conflict risk as the level-5 anchor requires. |
plugins/orpc/.agents/skills/orpc-migrate/SKILL.md
An efficient, highly actionable migration playbook with strong sequencing and explicit validation guidance. Its one structural weakness is that all detail lives in one SKILL.md with no local reference files, relying on external docs for the omitted mapping tables.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | █████ 5/5 | Lean and information-dense with no padding about what oRPC or libraries are; the only meta-commentary ('Pretrained knowledge... is often wrong for v2') directly drives behavior rather than explaining basics Claude already knows. |
| actionability | █████ 5/5 | Copy-paste-ready code for toORPCRouter, the base file, fetch handler, client, and TanStack Query utils, plus a tRPC→oRPC concept-map table and concrete package/option renames covering the common migration cases. |
| workflow clarity | █████ 5/5 | Both migrations are numbered in explicit order with a verify-after-each-step rule, and the v1→v2 section specifies exactly which steps need typecheck/unit tests vs integration/e2e tests, providing clear validation checkpoints and a feedback loop for a batch/destructive operation. |
| progressive disclosure | ████░ 4/5 | Well-organized into clear sections with a dedicated 'Docs retrieval' block pointing one level deep to authoritative orpc.dev pages, deliberately offloading full mapping tables; held below 5 only because it is a single monolithic file with no in-skill bundle files to split detail into. |
Suggestions:
- Consider extracting the v1→v2 package-rename and option-rename tables into a local reference file (e.g. references/v1-v2-mapping.md) so the full mapping is available offline and the body can stay a lean overview.
- The 'Audit silent behavior changes' bullets are dense; splitting them into a short checklist file would aid navigation and let the body summarize the highest-risk items.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Names both migration paths and concrete sub-actions — 'incremental wrapping via the @orpc/trpc integration or a full rewrite with the concept mapping' and 'package renames, breaking changes, and a safe order of operations' — giving comprehensive, specific coverage rather than vague language. |
| completeness | █████ 5/5 | Explicitly answers both 'what' (the two migrations and their mechanics) and 'when' (a concrete 'Use when...' trigger list), and adds a negative boundary ('Not for greenfield oRPC work... use the orpc skill'). |
| trigger term quality | █████ 5/5 | The 'Use when...' clause packs in natural user phrases — 'migrate from tRPC to oRPC', 'convert or wrap a tRPC router', 'upgrade oRPC v1 to v2', 'fix oRPC v2 breaking changes', 'swap @trpc/* packages for @orpc/* equivalents' — with synonyms and package-pattern variants. |
| distinctiveness conflict risk | █████ 5/5 | Occupies a clear migration-only niche and explicitly disambiguates from the sibling 'orpc' skill for greenfield/new-feature work, minimizing wrong-skill trigger risk. |
plugins/orpc/.agents/skills/orpc-openapi/SKILL.md
A strong, actionable reference body with executable examples and an explicit verification step, well-structured for navigation. It is slightly verbose in places and, lacking any bundle files, relies on external docs rather than internal progressive disclosure.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | Dense and assumes Claude's competence — it never explains what OpenAPI or oRPC is — but a few explanatory sentences (e.g., the compact-mode illustration) could be trimmed, keeping it just short of fully lean. |
| actionability | █████ 5/5 | Multiple copy-paste-ready examples with real imports cover the common cases — routing with openapi() meta, OpenAPIHandler with SmartCoercionHandlerPlugin, OpenAPILink client, and OpenAPIGenerator with the reference plugin. |
| workflow clarity | ████░ 4/5 | Clear topic-sequenced sections with an explicit validation checkpoint ('Verify the wiring before declaring success: request /spec.json… and confirm the method, path, and status'), but the multi-task reference style lacks full feedback loops for each workflow. |
| progressive disclosure | ████░ 4/5 | Well-organized into labeled sections with one-level-deep references to external docs pages (llms.txt, per-page .md URLs) and sibling skills; no nested references. No bundle files exist, so splitting is N/A, leaving it just short of the ideal overview-plus-reference-file split. |
Suggestions:
- Trim illustrative prose (e.g., the compact-mode GET example sentence) to lift conciseness toward fully lean.
- Add a brief feedback-loop note for spec generation (regenerate after metadata changes) to strengthen workflow_clarity beyond the single verification checkpoint.
- Consider extracting the bracket-notation and paramsStyles/queryStyles detail into a references file so SKILL.md stays a tighter overview.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Lists multiple concrete actions tied to named APIs — 'openapi() metadata or .route with method, path, successStatus', 'OpenAPIHandler', 'OpenAPILink', 'OpenAPIGenerator', 'Smart Coercion', 'Scalar or Swagger docs with the OpenAPI Reference plugin' — giving comprehensive coverage. |
| completeness | █████ 5/5 | Explicitly answers both what ('Expose an oRPC router as a spec-compliant OpenAPI HTTP API') and when ('Use when a project depends on @orpc/openapi, or for defining REST-style routes…') with concrete trigger phrases. |
| trigger term quality | ████░ 4/5 | Good natural-term coverage a developer would say ('OpenAPI HTTP API', 'REST-style routes', '@orpc/openapi', 'Scalar or Swagger docs') with synonyms (3.2/3.1/3.0, Scalar/Swagger), but lacks file-extension-style variations, so it stops just short of comprehensive. |
| distinctiveness conflict risk | █████ 5/5 | Occupies a clear niche and explicitly disambiguates from siblings ('for contract-first work… use the orpc-contract skill; for plain RPC serving… use the orpc skill instead'), minimizing wrong-skill triggering. |
plugins/orpc/.agents/skills/orpc/SKILL.md
A dense, highly actionable oRPC v2 reference with executable examples and useful pre-flight/typecheck checkpoints. It is slightly held back by inline time-sensitive version guidance and a monolithic single-file structure with no local progressive split.
Full review details
Validation Checks
16/16 checks passed.
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ████░ 4/5 | Lean intro and tight, purposeful code blocks that mostly assume Claude's competence, but time-sensitive version/beta instructions sit outside any 'old patterns' section and a few explanatory clauses could be trimmed, so it is not the every-token-earns-its-place of anchor 5. |
| actionability | █████ 5/5 | Copy-paste-ready executable examples span every common case (procedures, router, middleware, errors, serving, calling, client error handling) plus concrete commands like 'npm ls @orpc/server' and 'npm install @orpc/server@beta'. |
| workflow clarity | ████░ 4/5 | Topic-ordered flow with real checkpoints ('Check what is installed before writing code', 'run the project's typecheck before declaring success'); not a destructive/batch skill so the cap-3 rule does not apply, but it reads as a reference rather than a linear workflow with explicit fix-retry feedback loops. |
| progressive disclosure | ████░ 4/5 | Well-sectioned single file with a clear end-of-doc map and one-level-deep external docs links, but no local bundle files exist and all content is inlined in one monolithic file rather than split, so it stops short of anchor 5. |
Suggestions:
- Move the version-detection and beta dist-tag instructions into a short 'Version & compatibility' or 'old patterns' subsection so time-sensitive content is isolated from the stable reference material.
- Add an explicit validate-fix-retry feedback loop (e.g., typecheck fails -> fix types -> re-run typecheck -> only then proceed) for the testing/serve steps to push workflow_clarity toward 5.
- Consider extracting the per-plugin and per-adapter detail into local reference files under references/ so the SKILL.md body can act as a leaner overview, improving progressive disclosure.
Description Review
| Dimension | Score | Detail |
|---|---|---|
| specificity | █████ 5/5 | Enumerates many concrete actions (procedures via os builder, routers, middleware/context, ORPCError, RPCHandler serving, server/client clients, TanStack Query, SSE), giving comprehensive coverage rather than the minor gaps of anchor 4. |
| completeness | █████ 5/5 | Explicitly answers both 'what' (build/serve/call end-to-end typesafe APIs plus enumerated actions) and 'when' ('Use for any task in a project that depends on @orpc/* packages, even a one-procedure change') with concrete trigger phrases. |
| trigger term quality | ████░ 4/5 | Strong domain terms oRPC users actually say (@orpc/*, oRPC v2, TanStack Query, RPCHandler, SSE), but jargon-heavy and missing some softer synonyms; not the full synonym/extension breadth of anchor 5. |
| distinctiveness conflict risk | █████ 5/5 | Clear niche tied to @orpc/* and oRPC v2, and it actively routes adjacent tasks to sibling skills (orpc-openapi, orpc-contract, orpc-migrate), minimizing wrong-skill triggering. |
To improve your score, point your agent at the Tessl optimization guide. Need help? Jump on our Discord.
Feedback
Report issues with this review at tesslio/skill-review, or send private feedback from your terminal with tessl feedback.
 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| "openapi", | ||
| "typescript" | ||
| ], | ||
| "skills": "./.agents/skills/" |
There was a problem hiding this comment.
The plugin stores its only functionality under ./.agents/skills/, but the multi-format generator only maps paths that normalize to ./skills/. It therefore emits a Codex manifest that advertises the Skill capability without a skills path. Users who install orpc from the generated Codex marketplace will not have access to any of its four skills. Move the skills to the supported root skills/ directory, reference ./skills/, and regenerate the manifests.
Prompt To Fix With AI
This is a comment left during a code review.
Path: plugins/orpc/.claude-plugin/plugin.json
Line: 20
Comment:
**Codex Skills Are Unavailable**
The plugin stores its only functionality under `./.agents/skills/`, but the multi-format generator only maps paths that normalize to `./skills/`. It therefore emits a Codex manifest that advertises the Skill capability without a `skills` path. Users who install `orpc` from the generated Codex marketplace will not have access to any of its four skills. Move the skills to the supported root `skills/` directory, reference `./skills/`, and regenerate the manifests.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.
Merged
|
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
orpcplugin to the marketplace, bundling the four official oRPC skills from middleapi/orpc (MIT, maintained by the oRPC project itself).The skills were installed via skills.sh —
bunx skills add middleapi/orpc --skill <name> --agent universal— so they live underplugins/orpc/.agents/skills/and are version-locked inplugins/orpc/skills-lock.json. No files were hand-copied, sobun run skills:update-lockskeeps them current.The four skills:
orpcosbuilder, routers, middleware/context, typesafe errors,RPCHandlerserving, server- and client-side clients, TanStack Query, SSE streamingorpc-contract@orpc/contract(oc/implement), sharing a contract between packagesorpc-openapiOpenAPIHandler, Smart Coercion,OpenAPILink, OpenAPI spec generation, Scalar/Swagger referenceorpc-migrateAll four target oRPC v2 and explicitly warn that pretrained oRPC knowledge describes v1 — which is the main reason this plugin is worth shipping.
Changes
plugins/orpc/(new) — 4SKILL.mdfiles,skills-lock.json,.claude-plugin/plugin.json(with"skills": "./.agents/skills/"), plus the multi-format-generated.codex-plugin/plugin.json, rootplugin.json(Antigravity), and.cursor-plugin/plugin.json.claude-plugin/marketplace.json— new entry with arelevanceblock (topic: "oRPC",manifestDepsmatching"@orpc/<pkg>":inpackage.json).agents/plugins/marketplace.json,.cursor-plugin/marketplace.json— regenerated bybun scripts/cli.ts multi-formatrelease-please-config.json+.release-please-manifest.json—plugins/orpcpackage at1.0.0, withextra-filescovering all four version-bearing manifestsREADME.md— entry under Built-in PluginsVerification
claude plugin validate plugins/orpc→ passedclaude plugin validate .claude-plugin/marketplace.json→ passed (13 warnings, all on pre-existing entries; none for orpc)relevance.manifestDepsregex tested against real dependency lines: matches"@orpc/server","@orpc/client","@orpc/tanstack-query"; does not match"trpc". Thefilepattern matches both POSIX and Windowspackage.jsonpaths.Note on scope
Per the repo's marketplace-sync rule,
bun scripts/cli.ts multi-formatrewrites all local plugins. It produced repo-wide churn from pre-existing drift (e.g.plugins/vue/plugin.jsonis committed at1.1.0but regenerates at1.3.0), so that unrelated churn was reverted withgit restore plugins/and this commit is scoped to orpc only. That pre-existing drift across other plugins is still uncommitted and likely deserves a separate follow-up PR.bun.lockwas already modified before this work and was deliberately left out of the commit.Related issue
None — this plugin addition was not tracked by an issue.
Checklist
bun run test) — no tests apply; plugin manifests are verified withclaude plugin validate(see Verification)bun run lint) — green (the turbo lint scope covers the JS/TS packages, not the markdown/JSON files changed here)BREAKING CHANGE:note is includedSummary by cubic
Adds the
orpcplugin to the marketplace, bundling the four official oRPC skills frommiddleapi/orpc. The skills target oRPC v2 and explicitly warn that pretrained oRPC knowledge describes v1, which is the main reason this plugin is worth shipping.New Features
plugins/orpc/directory with fourSKILL.mdfiles,skills-lock.json, and plugin manifests for Claude, Codex, Cursor, and Antigravity..claude-plugin/marketplace.json,.cursor-plugin/marketplace.json, and.agents/plugins/marketplace.json.plugins/orpcat1.0.0and a README entry.claude plugin validate; all warnings are on pre-existing entries.Note
bun scripts/cli.ts multi-formatrewrites all local plugins; unrelated churn from pre-existing drift was reverted, but that drift remains uncommitted and likely deserves a separate follow-up.bun.lockwas left out of the commit.Written for commit e501866. Summary will update on new commits.