Skip to content

Cursor plugin specification and official plugins

TypeScript

Point at the new docs anchors

Cursor Agentbfd034de172b
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index bfa17d3a..837c5c86 100644
--- a/origin-apps/skills/origin-api/SKILL.md
+++ b/origin-apps/skills/origin-api/SKILL.md
@@ -19,9 +19,8 @@ which rules to check first. It restates nothing you can read there.
## Fetch first. Never name an endpoint, scope, slug, header, or limit from memory.
-- `https://cursor.com/docs/api/origin/openapi.yaml`: the contract. Every
- operation carries `x-origin-scopes`; every webhook payload schema carries
- `x-origin-webhook-events`, the list of slugs that deliver it.
+- `https://cursor.com/docs/api/origin/openapi.yaml`: the contract. Its
+ `x-origin-*` extensions are summarized under `#endpoint-reference`.
- `https://cursor.com/docs/api/origin/llms-full.txt`: the prose reference.
Anchors below are sections of this file.
- `https://cursor.com/docs/api/origin/llms.txt` (index) and
@@ -40,8 +39,11 @@ docs disagree, the docs win.
| What an installation can do on a mirrored repository | `#mirrored-repositories` |
| Webhook headers, signature, envelope, retries, pausing, recovery | `#webhooks` and its subsections |
| Which events exist and which are delivered without subscribing | `#events` |
-| Payload shapes | `#event-payloads` and the schema's `x-origin-webhook-events` |
-| Pagination, errors, request IDs, repository paths, ID form | `#common-conventions` |
+| Payload shapes and the `x-origin-webhook-events` extension | `#event-payloads` |
+| Pagination, errors, request IDs, repository paths | `#common-conventions` |
+| ID form and stability | `#ids` |
+| What a `PREVIEW` badge means | `#preview` |
+| GitHub features Origin does not have | `#coming-from-github` |
| Rate limits and headers | `#rate-limits` |
| Check-run keys, attempts, stale writes | `#check-runs` |
| What is not there yet | `#current-limitations` |
@@ -57,8 +59,8 @@ week.
state an installation can only read, and pushes are not delivered
(`#mirrored-repositories`, `#events`).
2. **Subscribe.** Only the `installation.*` events arrive without a
- subscription. Select every other event the app needs; a missing
- subscription is silence, not an error (`#events`).
+ subscription. `#events` says what else delivery needs; a missing
+ subscription is silence, not an error.
3. **Verify, dedupe, acknowledge.** Verify the signature over the raw body
before parsing, dedupe on the delivery ID, return `2xx`, then process
(`#signature-verification`, `#retries`, `#automatic-disable`). The digest
@@ -66,20 +68,11 @@ week.
verifier passes.
4. **Scopes from the spec.** Request the union of `x-origin-scopes.scopes`
over the operations the app calls, and nothing else (`#scopes`).
+5. **Opaque tokens and IDs.** Page tokens and IDs are not yours to build or
+ parse (`#pagination`, `#ids`).
## Coming from GitHub
-Origin does not have these. Build the Origin idiom instead of emulating the
-GitHub one. Until the docs carry this list, it lives here:
-
-- Issues. Conversation is pull request comments, threads, reviews, labels.
-- Commit statuses. Check runs with a stable `key` (`#check-runs`).
-- GraphQL. REST only.
-- Per-repository webhook CRUD. Subscriptions are app settings.
-- User, email, team, or member directory. Actors are IDs, plus a handle
- where the payload exposes one.
-- `/user`-style flows. Discover repositories through the installation.
-- Reviews keyed by commit SHA. Reviews reference a pull request version.
-- Numeric IDs and page numbers. IDs and page tokens are opaque strings; do
- not parse or construct them, and cache repository IDs rather than slugs
- (`#repository-paths`, `#pagination`).
+GitHub habits do not carry over. Before mapping a GitHub feature onto Origin,
+read `#coming-from-github` for what Origin does not have and what to use
+instead.
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 876fb506..e2c6b384 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
@@ -22,7 +22,7 @@ card per gap. The team will argue over it in one sitting.
| `by-design-absent` | Origin deliberately does not reproduce it (`origin-isms.md`). Names the idiom or "no equivalent; decision needed". |
| `gap` | No workaround, or one that fails `gap-bar.md`. Has a card in § 6. |
| `unknown` | Discovery or the spec could not answer. Has a question in § 7. |
-| `preview` (suffix) | The Origin operation is `x-cursor-visibility: PREVIEW`. Usable. The shape may move. |
+| `preview` (suffix) | The row touches an element badged `x-cursor-visibility: PREVIEW` (`llms-full.txt#preview`). |
**Size** (kind of change, never time)
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 3342bdfd..1be7fe4d 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
@@ -2,10 +2,8 @@
Check here before labeling anything `gap`. A row below is `by-design-absent`
or `reshaped`. The brief points at the idiom and never files a card. The
-third column says where the Origin answer lives: an anchor in
-`llms-full.txt`, or "Coming from GitHub" in the `origin-api` skill for items
-the docs do not yet carry. Read the source; do not copy this table into the
-brief.
+third column is the `llms-full.txt` anchor where the Origin answer lives.
+Read the source; do not copy this table into the brief.
| GitHub call, event, or permission | Label | Where the Origin answer lives |
| --- | --- | --- |
@@ -13,24 +11,24 @@ brief.
| Install callback query parameters (`installation_id`, `setup_action`) | `reshaped` | `#installation-receipt` |
| RS256 app JWT | `reshaped` | `#app-jwt` |
| Long-lived installation tokens | `reshaped` | `#installation-access-token` |
-| User OAuth, `/user`, `/user/installations`, install-by-user picker | `by-design-absent` | `#scopes` (user-credential operations); Coming from GitHub. Ask what the flow should do. |
+| User OAuth, `/user`, `/user/installations`, install-by-user picker | `by-design-absent` | `#coming-from-github`; `#scopes` (user-credential operations). Ask what the flow should do. |
| Permissions `<noun>: read\|write` | `reshaped` | `#scopes`; `x-origin-scopes` per operation |
-| Numeric IDs, `/repositories/{id}` | `reshaped` | `#repository-paths` |
+| Numeric IDs, `/repositories/{id}` | `reshaped` | `#ids`, `#repository-paths` |
| `Link` / `page` / `per_page` pagination, total counts | `reshaped` | `#pagination` |
-| GraphQL | `by-design-absent` | Coming from GitHub. Decompose and count the fan-out. |
-| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `reshaped` | `#check-runs`; Coming from GitHub |
-| Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a pull request) | `by-design-absent` | Coming from GitHub. Ask what the pull-request-scoped behavior should be. |
+| GraphQL | `by-design-absent` | `#coming-from-github`. Decompose and count the fan-out. |
+| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `reshaped` | `#coming-from-github`, `#check-runs` |
+| Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a pull request) | `by-design-absent` | `#coming-from-github`. Ask what the pull-request-scoped behavior should be. |
| `/issues/{n}/comments`, `/issues/{n}/labels` used on a pull request | `reshaped` | Pull requests endpoint reference; same calls under `/pulls/{n}/…` |
-| Repository webhook CRUD (`/repos/…/hooks`) | `by-design-absent` | Coming from GitHub; subscriptions are app settings (`#events`) |
+| Repository webhook CRUD (`/repos/…/hooks`) | `by-design-absent` | `#coming-from-github`, `#events` |
| App-manifest conversion, OAuth-app token mints | `by-design-absent` | `#installation`, Create App in the endpoint reference |
| Git Data API tree/blob writes | `by-design-absent` | `#git-https-authentication`; Git data endpoint reference |
| Standalone review-thread objects | `reshaped` | `#current-limitations`; Pull requests endpoint reference |
-| User, email, team, and member lookups | `by-design-absent` | `#resource-references`; Coming from GitHub |
+| User, email, team, and member lookups | `by-design-absent` | `#coming-from-github`, `#resource-references` |
| Single `pull_request` event with an `action` field, `previous_attributes` | `reshaped` | `#events`, `#event-payloads` |
| `x-github-*` headers, HMAC `x-hub-signature-256` | `reshaped` | `#headers`, `#signature-verification` |
| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `reshaped` | `#current-limitations`, `#resource-references`. Name the follow-up call per field and count the fan-out. |
| All events delivered after app creation | `reshaped` | `#events` |
-| Reviews keyed by `commit_id` | `reshaped` | Coming from GitHub; `pullRequestVersion` in the review schema |
+| Reviews keyed by `commit_id` | `reshaped` | `#coming-from-github` |
| Finding own check runs or comments by actor | `reshaped` | `#check-runs` (`key`); comments and reviews by a marker the app controls |
| Requested-reviewer team pages, `created_via` | `by-design-absent` | Pull requests endpoint reference (reviewers by identifier) |
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 87851051..fb5826de 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
@@ -7,9 +7,9 @@ table here. Build the index once. Every later step looks things up in it.
| Extension | Where | Use |
| --- | --- | --- |
-| `x-origin-scopes` | every operation | The scope, credential, and ambient rules for that operation. Rules in `llms-full.txt#scopes`. |
-| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape. A schema carrying it is a webhook family. Infer the embedded resource from its `$ref`s; some families (pushes, deletions, reviewer changes) have no REST twin. |
-| `x-cursor-visibility` | some schema fields | A stability badge on a field. Carry it into the brief as a `preview` suffix on rows that read the field. |
+| `x-origin-scopes` | every operation | The scope and credential rules for that operation. `llms-full.txt#scopes`, `#endpoint-reference`. |
+| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape; a schema carrying it is a webhook family. `#event-payloads`. Infer the embedded resource from its `$ref`s; some families have no REST twin. |
+| `x-cursor-visibility: PREVIEW` | operations, parameters, schemas, fields | `#preview`. Carry it into the brief as a `preview` suffix on any row that touches a badged element. |
## Build the index
@@ -39,7 +39,7 @@ match is a candidate, never a result.
**REST calls**
1. Look for the same resource path under the Origin base path
- (`llms-full.txt#repository-paths` gives the path shape). Most GitHub
+ (`llms-full.txt#repository-paths` and `#ids` give the path forms). Most GitHub
repository, pull request, check, label, branch, and commit paths have a
direct or near-direct counterpart.
2. Re-home GitHub's issue-flavored pull request calls (`/issues/{n}/comments`,