Skip to content

Cursor plugin specification and official plugins

TypeScript

Apply skill-authoring audit picks

Cursor Agentcc906921c14e
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index eb6e1ae5..e139d265 100644
--- a/origin-apps/skills/origin-api/SKILL.md
+++ b/origin-apps/skills/origin-api/SKILL.md
@@ -1,8 +1,8 @@
---
name: origin-api
description: >-
- Build on the Cursor Origin API. Create an Origin App, authenticate as it,
- call the REST API, receive webhooks. Use whenever code or a plan touches
+ Guides building on the Cursor Origin API: creating an Origin App,
+ authenticating as it, calling the REST API, receiving webhooks. Use whenever code or a plan touches
Origin endpoints, installation tokens, scopes, webhook subscriptions or
signatures, page tokens, or an Origin App manifest. Lists the sources to
fetch first and the Origin rules that GitHub habits get wrong.
@@ -70,8 +70,8 @@ docs disagree, the docs win.
every request, including continuations. There is no `Link` header and no
total.
- **IDs are TypeIDs** (`repo_…`, `i_…`, `cmt_…`), never integers. Cache IDs,
- not slugs. `/repos/_/{repoId}` survives renames. 64-bit integers (PR
- numbers, versions) are JSON strings. Defaults are present (`false`, `0`,
+ not slugs. `/repos/_/{repoId}` survives renames. 64-bit integers (pull
+ request numbers, versions) are JSON strings. Defaults are present (`false`, `0`,
`[]`), so a present `false` is a value.
- **`404` means not found or no access.** Branch on status and `code`, never
on message text. Quote `X-Request-ID` when escalating.
@@ -79,7 +79,7 @@ docs disagree, the docs win.
`429`. Git HTTPS is metered separately. Cursor raises per-app budgets on
request.
- **These are decisions, not gaps.** No commit statuses (check runs upsert on
- a caller-stable `key`). No Issues (conversation is PR comments, threads,
+ a caller-stable `key`). No Issues (conversation is pull request comments, threads,
reviews, and labels). No GraphQL. No per-repository webhook CRUD. No user or
email directory. Reviews anchor to a pull request version, not a SHA. A
thread materializes from its first diff-anchored comment.
diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.md
index 0f17e23e..3f1b2446 100644
--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -1,7 +1,7 @@
---
name: port-github-app-to-origin
description: >-
- Plan the port of an existing GitHub App to a Cursor Origin App. Use when a
+ Plans the port of an existing GitHub App to a Cursor Origin App. Use when a
repo is a GitHub App (manifest, Probot, Octokit or another GitHub SDK, webhook
signature handlers) and the task is to bring it to Origin or compare it with
the Origin API. Maps what the app uses from GitHub onto the live Origin spec
@@ -61,6 +61,22 @@ GitHub. Follow it first. Nothing here repeats it. Two rules on top:
5. **Close with the questions**, pruned to what discovery left open. The
first is always native or mirror, because it decides whether the app
receives events at all.
+6. **Check the brief and fix.** Copy this list, tick each line, fix what
+ fails, and repeat until a pass changes nothing. Both validation runs found
+ a missed row on this pass.
+
+ - [ ] Every Origin cell names an `operationId`, slug, or anchor that
+ exists in the files fetched in step 1.
+ - [ ] Every `gap` row has a card, and the card quotes one of the five
+ tradeoff tests in `gap-bar.md`.
+ - [ ] Every `unknown` row has a question in § 7.
+ - [ ] No `origin-isms.md` row is labeled `gap`.
+ - [ ] Every event the code handles has a § 4 row for each payload field
+ it reads, including log-only fields.
+ - [ ] Calls the framework makes on the app's behalf appear as rows.
+ - [ ] The scopes line equals the union of `x-origin-scopes.scopes` over
+ the § 3 operations.
+ - [ ] Question 1 is native or mirror.
## Not in scope
@@ -72,7 +88,7 @@ cards to Cursor. The brief carries them and the team decides.
| File | Read when |
| --- | --- |
-| `../origin-api/SKILL.md` | First. Sources and fundamentals. |
+| `origin-api` skill (install both) | First. Sources and fundamentals. |
| `references/discovery.md` | Scanning the codebase. |
| `references/spec-mapping.md` | Building the index. Matching calls, events, and fields. |
| `references/origin-isms.md` | Labeling a missing GitHub feature. |
diff --git a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
index 04c9e23f..5f893c11 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
@@ -1,5 +1,8 @@
# Porting brief template
+Contents: [Labels](#labels) (parity, size) and [Template](#template)
+(provenance, §§ 1-8).
+
Write one Markdown file at the repository root (`ORIGIN-PORTING-BRIEF.md`
unless the team's docs convention says otherwise) and print its path. Fill
every section. An empty section says so in one line rather than disappearing.
@@ -122,7 +125,7 @@ spec-silent behavior the brief depends on, stated as the observation to make.
6. Perform the smallest action in § 3 and confirm the slug and the § 4
fields arrive. If the ping arrived and this did not, re-check steps 2 and
3 first.
-7. Smallest write from § 3 (check run with a stable `key`, PR comment),
+7. Smallest write from § 3 (check run with a stable `key`, pull request comment),
confirming its scope is in the grant.
## 6. Gaps worth raising
@@ -140,8 +143,8 @@ Always the first three, then what discovery left open.
which payload fields are hard requirements?
3. Which flows depend on a user credential today, and what should they do on
Origin?
-4. Does anything key approvals or reviews by commit SHA rather than PR
- version?
+4. Does anything key approvals or reviews by commit SHA rather than pull
+ request version?
5. How do you identify your own check runs, comments, and reviews today? Can
a key or marker you control replace actor matching?
6. Do you generate clients from OpenAPI? (Read the changelog for renames.)
diff --git a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
index 60ee0d17..0fff925d 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
@@ -5,7 +5,7 @@ two or three things Cursor needs to hear. When in doubt, write the row as
`workaround` with the tradeoff and an open question, not as a card.
- A difference is any row whose parity label is not `same`.
-- A workaround reaches the same outcome with today's API by another route. A
+- A workaround reaches the same outcome with the current API by another route. A
follow-up read, a re-keyed identifier, a path change, a client-side filter,
a marker the app controls.
- A gap is a difference with no workaround, or a workaround whose tradeoff
@@ -18,7 +18,7 @@ At least one must hold. Quote it on the card.
| Tradeoff | Test |
| --- | --- |
| Fan-out at scale | Calls per event multiply by a factor that grows with repository or activity size (N commits × M files, or a full list scan to find one row), and the app's volume makes that budget-relevant. One bounded extra read per event is trivial. |
-| Correctness risk | The workaround can return a wrong answer, not only a slower one. Heuristic "my own row" matching. Inferring a PR from a SHA several versions share. Assembling a URL whose format is not contractual. |
+| Correctness risk | The workaround can return a wrong answer, not only a slower one. Heuristic "my own row" matching. Inferring a pull request from a SHA several versions share. Assembling a URL whose format is not contractual. |
| Security posture | The workaround needs a broader scope, a longer-lived token, or a user credential where an installation token should do. |
| Customer-visible behavior | The workaround changes what the team's users see or can do, not how the code is organized. |
| Load-bearing | The capability sits on the hello-world path or the team's stated core flow. |
@@ -58,7 +58,7 @@ can act without a call.
- **GitHub call, event, or permission:** `<METHOD /path>` / `<event.action>` / `<permission>`, at `<file:line>`.
- **What the app needs from it:** <data or effect, one sentence>.
- **Why:** <what the app does with it, one sentence>.
-- **Closest Origin operation today:** `<operationId>` / `<slug>` / none, and what it lacks.
+- **Closest Origin operation:** `<operationId>` / `<slug>` / none, and what it lacks.
- **Workaround considered:** <it, or "none found">.
- **Tradeoff that fails the bar:** <one of the five, with the number or risk>.
- **Shape that would close it:** <a capability, not a design. "List pull requests whose head is this SHA", not a route or field name.>
diff --git a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
index c4ca2326..3bbda21a 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
@@ -17,7 +17,7 @@ and the idiom. Confirm current wording in `llms-full.txt`.
| `Link` / `page` / `per_page` pagination, total counts | `reshaped` | `pageSize` / `pageToken` / `nextPageToken`; opaque; no total. |
| GraphQL | `by-design-absent` | REST; decompose and count the fan-out. |
| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `reshaped` | Check runs upserting on a caller-stable `key`; rulesets bind on the key. |
-| Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a PR) | `by-design-absent` | PR comments, threads, reviews, labels on pull requests. Ask what the PR-scoped behavior should be. |
+| Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a pull request) | `by-design-absent` | Pull request comments, threads, reviews, and labels. Ask what the pull-request-scoped behavior should be. |
| `/issues/{n}/comments`, `/issues/{n}/labels` used on a pull request | `reshaped` | Same calls under `/pulls/{n}/…`. |
| Repository webhook CRUD (`/repos/…/hooks`) | `by-design-absent` | Subscriptions are app settings. |
| App-manifest conversion, OAuth-app token mints | `by-design-absent` | App creation form (accepts prefill params) or user-credential `CreateApp`. |
diff --git a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
index a3928bfd..836743a8 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
@@ -43,7 +43,7 @@ match is a candidate, never a result.
(`{owner}/{repo}` → `{ownerSlug}/{repoName}`, `{pull_number}` →
`{pullNumber}`; custom verbs are `:verb` suffixes such as
`…/contents:batchGet`).
-2. Re-home GitHub's issue-flavored PR calls: `/issues/{n}/comments` and
+2. Re-home GitHub's issue-flavored pull request calls: `/issues/{n}/comments` and
`/issues/{n}/labels` used *on a pull request* live under `/pulls/{n}/…`.
That is a path change, not a gap. When the code uses them on real issues,
see `origin-isms.md`.
@@ -90,6 +90,6 @@ event.
has not declined it, and never `by-design-absent`, because only
`origin-isms.md` rows earn that.
- A behavior the code depends on that the docs do not state (does an event
- fire for a draft PR? does `updatedAt` move on a comment?) becomes an open
+ fire for a draft pull request? does `updatedAt` move on a comment?) becomes an open
question plus a hello-world step that observes it on a native repository.
Do not settle it from GitHub's behavior.