Cursor plugin specification and official plugins
TypeScript
Name docs sections by heading instead of hardcoding page URLs
Cursor Agentf18177954a8f
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.mdindex 18fdb15d..5a336b65 100644--- a/origin-apps/skills/origin-api/SKILL.md+++ b/origin-apps/skills/origin-api/SKILL.md@@ -20,57 +20,58 @@ rules to check first; it does not restate the docs.Do not name an endpoint, scope, event slug, header, or limit from memory.-All paths below are under `https://cursor.com/docs/api/origin/`.+The docs live under `https://cursor.com/docs/api/origin/`:-- `llms.txt`: the index. Every section, endpoint, and webhook payload has its- own page at `reference/<anchor>.md`, and the index links to each.+- `llms.txt`: the index. It links every section, endpoint, and webhook+ payload page. Quoted names below ("Scopes", "Events") are section headings;+ find the current link for one in `llms.txt`.- `openapi.yaml`: the contract. Its `x-origin-*` extensions are summarized in- `reference/endpoint-reference.md`.-- `llms-full.txt`: every reference page in one file. `changelog`: what moved.+ "Endpoint reference".+- `llms-full.txt`: the whole reference in one file. `changelog`: what moved.-For one question, read `llms.txt`, then fetch the one `reference/<anchor>.md`-that answers it. Fetch the whole `llms-full.txt` or `openapi.yaml` only for-broad work, such as a porting brief.+For one question, read `llms.txt`, then fetch only the section that answers+it. Fetch the whole `llms-full.txt` or `openapi.yaml` for broad work, such as+a porting brief.-Cite `operationId`s and reference pages. Where this file and the docs+Cite `operationId`s and section names. Where this file and the docsdisagree, the docs win.## Where to look-| Question | Page |+| Question | Section || --- | --- |-| Which credential for which call; minting and lifetime | `reference/authentication.md` and its subsections through `reference/git-https-authentication.md` |-| Install flow and the callback receipt | `reference/installation.md`, `reference/installation-receipt.md` |-| Which scope an operation needs | `x-origin-scopes` on the operation; `reference/scopes.md` |-| What an installation can do on a mirrored repository | `reference/mirrored-repositories.md` |-| Webhook headers, signature, envelope, retries, pausing, recovery | `reference/webhooks.md` |-| Which events exist and which arrive without subscribing | `reference/events.md` |-| Payload shapes | `reference/event-payloads.md` |-| Pagination, errors, request IDs, repository paths | `reference/common-conventions.md` |-| ID form and stability | `reference/ids.md` |-| What a `PREVIEW` badge means | `reference/preview.md` |-| Rate limits | `reference/rate-limits.md` |-| Check-run keys, attempts, stale writes | `reference/check-runs.md` |-| What is not there yet | `reference/current-limitations.md` |-| A checklist to build against | `reference/implementation-checklist.md` |+| Which credential for which call; minting and lifetime | "Authentication" and its subsections |+| Install flow and the callback receipt | "Installation", "Installation receipt" |+| Which scope an operation needs | `x-origin-scopes` on the operation; "Scopes" |+| What an installation can do on a mirrored repository | "Mirrored repositories" |+| Webhook headers, signature, envelope, retries, pausing, recovery | "Webhooks" |+| Which events exist and which arrive without subscribing | "Events" |+| Payload shapes | "Event payloads" |+| Pagination, errors, request IDs, repository paths | "Common conventions" |+| ID form and stability | "IDs" |+| What a `PREVIEW` badge means | "Preview" |+| Rate limits | "Rate limits" |+| Check-run keys, attempts, stale writes | "Check runs" |+| What is not there yet | "Current limitations" |+| A checklist to build against | "Implementation checklist" |## Rules to check first1. **Native or mirror.** Confirm the target repositories are Origin-nativeor stable outbound mirrors. On any other mirror state an installation can- only read, and pushes are not delivered (`reference/mirrored-repositories.md`,- `reference/events.md`).+ only read, and pushes are not delivered ("Mirrored repositories",+ "Events").2. **Subscribe.** Only the `installation.*` events arrive without a- subscription; a missing subscription is silence, not an error (`reference/events.md`).+ subscription; a missing subscription is silence, not an error ("Events").3. **Verify, dedupe, acknowledge.** Verify the signature over the raw bodybefore parsing, dedupe on the delivery ID, return `2xx`, then process- (`reference/signature-verification.md`, `reference/retries.md`, `reference/automatic-disable.md`). The digest+ ("Signature verification", "Retries", "Automatic disable"). The digeststep differs from the Standard Webhooks spec; do not assume a genericverifier passes.4. **Scopes from the spec.** Request the union of `x-origin-scopes.scopes`- over the operations the app calls (`reference/scopes.md`).+ over the operations the app calls ("Scopes").5. **Opaque tokens and IDs.** Do not build or parse page tokens or IDs- (`reference/pagination.md`, `reference/ids.md`).+ ("Pagination", "IDs").Porting an existing GitHub App: the `port-github-app-to-origin` skill inthis plugin covers how its capabilities map onto Origin.diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.mdindex 4478a40d..1d708574 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -46,7 +46,7 @@ section.3. **Map** each capability (`references/spec-mapping.md`). Map the payloadfields the code reads, not only the event names; if a payload lacks afield the REST resource has, a follow-up read is the usual answer- (`reference/event-payloads.md`). Check `references/origin-isms.md` before calling+ ("Event payloads"). Check `references/origin-isms.md` before callinganything a gap, and `references/gap-bar.md` before writing feedback. Acapability the Origin docs do not mention is not available today and getsa question. A behavior the docs neither confirm nor deny becomes a@@ -54,7 +54,7 @@ section.carried over from the app's current platform.4. **Write the brief** per `references/brief-template.md`: guidance and adefault outline, not a form. Every Origin claim names an `operationId`, a- slug, or a `reference/<anchor>.md` page. When there is feedback, also write the+ slug, or a docs section. When there is feedback, also write theFeedback section to `ORIGIN-FEEDBACK.md` beside the brief.5. **Self-check** before finishing: every Origin claim resolves in thefetched files; every gap has a feedback entry that names a tradeoff fromdiff --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.mdindex b8f34deb..43c0e157 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@@ -14,17 +14,17 @@ headings to fit the app.rest (usually native or mirror), and whether there is feedback for Cursorand if any of it blocks.- **Maps what the app uses to Origin.** Every capability the code relies on,- with the Origin operation, slug, or reference page it maps to, or a+ with the Origin operation, slug, or docs section it maps to, or anote that nothing does. Where a webhook handler reads specific payloadfields, say per field whether it is present, comes from the envelope, needsa follow-up read (and how many per event), is derivable, or is absent.Group by facet if the table is long. End with the scopes to request: theunion of `x-origin-scopes.scopes` over the operations named, minus what- `reference/scopes.md` says is automatic or implied.+ "Scopes" says is automatic or implied.- **Gives an app-specific first-run path when it helps.** The events toselect by slug, the mirror-state check, the first event that should arriveand what it should carry, the first write. Generic setup steps belong to- `reference/implementation-checklist.md`, not here. Skip for a read-only app+ "Implementation checklist", not here. Skip for a read-only appwith one event.- **Adds plan notes.** What drives the size of the port (a few bullets, notime estimates) and how to roll it out: dual-run or cutover, what a mirror@@ -45,7 +45,7 @@ headings to fit the app.- Every claim about the app cites evidence: `file:line`, or "from`<dependency>` (documented behavior)". Team-facing sections only.- Every claim about Origin resolves in the fetched `openapi.yaml` or- `llms-full.txt`: an `operationId`, a slug, or a reference page. Nothing from+ `llms-full.txt`: an `operationId`, a slug, or a section. Nothing frommemory.- Behavior the docs do not state is a question plus a first-run step thatobserves it, never an assumption.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.mdindex 8acec6d4..160ddd10 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,39 +2,39 @@Check here before calling anything a gap. Each row says whether a documentedOrigin path exists (`maps`) or nothing in the current spec covers it-(`not-available`), and where the Origin answer lives (a page under-`https://cursor.com/docs/api/origin/` unless noted). A `maps` row is a question only if the team+(`not-available`), and where the Origin answer lives (a section heading in+the Origin docs unless noted; find its link in `llms.txt`). A `maps` row is a question only if the teamwants the old shape back. A `not-available` row is a question, and feedbackif it meets the bar in `gap-bar.md`. Read the source; do not copy this tableinto the brief.| What the app uses today | Mark | Where the Origin answer lives || --- | --- | --- |-| Writes or `push` events on a repository mirrored from GitHub | `maps` | Read-only until the mirror becomes a stable outbound mirror (`reference/mirrored-repositories.md`); pushes are not delivered for GitHub-sourced mirrors (`reference/events.md`). Transitioning is a user-credential operation. First question of every brief. |-| Install callback query parameters (`installation_id`, `setup_action`) | `maps` | `reference/installation-receipt.md` |-| RS256 app JWT | `maps` | `reference/app-jwt.md` |-| Long-lived installation tokens | `maps` | `reference/installation-access-token.md` |-| User OAuth, `/user`, `/user/installations`, install-by-user picker | `not-available` | No user-credential flow for apps in the current spec. Repository discovery is through the installation; namespace-wide listing is under `reference/current-limitations.md`. Ask what the flow should do. |-| Permissions `<noun>: read\|write` | `maps` | `reference/scopes.md`; `x-origin-scopes` per operation |-| Numeric IDs, `/repositories/{id}` | `maps` | `reference/ids.md`, `reference/repository-paths.md` |-| `Link` / `page` / `per_page` pagination, total counts | `maps` | `reference/pagination.md` |+| Writes or `push` events on a repository mirrored from GitHub | `maps` | Read-only until the mirror becomes a stable outbound mirror ("Mirrored repositories"); pushes are not delivered for GitHub-sourced mirrors ("Events"). Transitioning is a user-credential operation. First question of every brief. |+| Install callback query parameters (`installation_id`, `setup_action`) | `maps` | "Installation receipt" |+| RS256 app JWT | `maps` | "App JWT" |+| Long-lived installation tokens | `maps` | "Installation access token" |+| User OAuth, `/user`, `/user/installations`, install-by-user picker | `not-available` | No user-credential flow for apps in the current spec. Repository discovery is through the installation; namespace-wide listing is under "Current limitations". Ask what the flow should do. |+| Permissions `<noun>: read\|write` | `maps` | "Scopes"; `x-origin-scopes` per operation |+| Numeric IDs, `/repositories/{id}` | `maps` | "IDs", "Repository paths" |+| `Link` / `page` / `per_page` pagination, total counts | `maps` | "Pagination" || GraphQL | `not-available` | No GraphQL endpoint in the current spec. Decompose into REST calls and count the fan-out; a decomposition that meets the feedback bar earns an entry about that read. |-| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `maps` | `reference/check-runs.md` (check runs with a stable `key`) |+| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `maps` | "Check runs" (check runs with a stable `key`) || Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a pull request) | `not-available` | No Issues endpoints or events in the current spec. Pull request comments, threads, reviews, and labels cover the pull-request half. Ask what the team needs for the rest; an issue-driven app may earn a feedback entry. || `/issues/{n}/comments`, `/issues/{n}/labels` used on a pull request | `maps` | Pull requests endpoint reference; same calls under `/pulls/{n}/…` |-| Repository webhook CRUD (`/repos/…/hooks`) | `maps` | Subscriptions are set per app through Create App / Update App `events` (`reference/events.md`). |-| App-manifest conversion | `maps` | App creation form or `CreateApp` (`reference/installation.md`, endpoint reference) |+| Repository webhook CRUD (`/repos/…/hooks`) | `maps` | Subscriptions are set per app through Create App / Update App `events` ("Events"). |+| App-manifest conversion | `maps` | App creation form or `CreateApp` ("Installation", endpoint reference) || OAuth-app token mints | `not-available` | Nothing in the current spec. Ask what the flow was for. |-| Git Data API commit and ref writes | `maps` | Create Commit From Files, Create Git Ref (Git data endpoint reference); `reference/git-https-authentication.md` for pushes |+| Git Data API commit and ref writes | `maps` | Create Commit From Files, Create Git Ref (Git data endpoint reference); "Git HTTPS authentication" for pushes || Git Data API arbitrary blob or tree writes | `not-available` | Not in the current spec. Ask whether commit-from-files or a push covers the use. |-| Standalone review-thread objects | `maps` | A thread comes from its first diff-anchored comment (Pull requests endpoint reference); thread listing is under `reference/current-limitations.md`. |-| User, email, team, and member lookups | `not-available` | No directory reads in the current spec. Reviewer identifiers resolve by public id, user email, or group slug; `handle` is present when the profile is public (`reference/resource-references.md`). |-| Single `pull_request` event with an `action` field, `previous_attributes` | `maps` | `reference/events.md`, `reference/event-payloads.md` |-| `x-github-*` headers, HMAC `x-hub-signature-256` | `maps` | `reference/headers.md`, `reference/signature-verification.md` |-| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `maps` | `reference/resource-references.md`; the push commit list is under `reference/current-limitations.md` and may change. Name the follow-up call per field and count the fan-out. |-| All events delivered after app creation | `maps` | `reference/events.md` |+| Standalone review-thread objects | `maps` | A thread comes from its first diff-anchored comment (Pull requests endpoint reference); thread listing is under "Current limitations". |+| User, email, team, and member lookups | `not-available` | No directory reads in the current spec. Reviewer identifiers resolve by public id, user email, or group slug; `handle` is present when the profile is public ("Resource references"). |+| Single `pull_request` event with an `action` field, `previous_attributes` | `maps` | "Events", "Event payloads" |+| `x-github-*` headers, HMAC `x-hub-signature-256` | `maps` | "Headers", "Signature verification" |+| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `maps` | "Resource references"; the push commit list is under "Current limitations" and may change. Name the follow-up call per field and count the fan-out. |+| All events delivered after app creation | `maps` | "Events" || Reviews keyed by `commit_id` | `maps` | `pullRequestVersion` on the review schema |-| Finding own check runs or comments by actor | `maps` | `reference/check-runs.md` (`key`); comments and reviews by a marker the app controls |+| Finding own check runs or comments by actor | `maps` | "Check runs" (`key`); comments and reviews by a marker the app controls || Requested-reviewer team pages, `created_via` | `not-available` | Groups exist and resolve by slug; there is no group membership read in the current spec. |A capability that is not on this list and that the Origin docs do notdiff --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.mdindex fb728aea..9683511b 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@@ -1,6 +1,7 @@# Reading the Origin spec and matching GitHub calls and events to it-Paths like `reference/<anchor>.md` are under `https://cursor.com/docs/api/origin/`.+Quoted names ("Scopes", "Events") are section headings in the Origin docs;+find each one's link in `llms.txt`.Every mapping in the brief comes from the fetched `openapi.yaml`, not from atable here. Build the index once. Every later step looks things up in it.@@ -9,9 +10,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 and credential rules for that operation. `reference/scopes.md`, `reference/endpoint-reference.md`. |-| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape; a schema carrying it is a webhook family. `reference/event-payloads.md`. Infer the embedded resource from its `$ref`s; some families have no REST twin. |-| `x-cursor-visibility: PREVIEW` | operations, parameters, schemas, fields | `reference/preview.md`. Note it in the brief on any capability that touches a badged element. |+| `x-origin-scopes` | every operation | The scope and credential rules for that operation. "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". Note it in the brief on any capability that touches a badged element. |## Build the index@@ -19,19 +20,20 @@ table here. Build the index once. Every later step looks things up in it.prints every `operationId` with its scope block. From it, note the unionof scopes with the operations that need each, and separateinstallation-requestable scopes from ambient and user-only ones- (`reference/scopes.md` explains the difference). The user-only set tells+ ("Scopes" explains the difference). The user-only set tellsyou which GitHub flows have no app-side equivalent. Read parameters andresponse components from the spec when a rule below asks for them.2. **Webhook events**: `rg -A3 'x-origin-webhook-events:' openapi.yaml` lists- every slug with its payload schema. Each family has its own page with the- fields expanded to dotted paths (`reference/pull-request-events.md`; find- the page in `llms.txt`). In a broad run with `llms-full.txt` already- fetched, `rg -n '^### Pull Request Events$' llms-full.txt` and read to the- next `###`. From `reference/events.md`, note which slugs are delivered+ every slug with its payload schema. Each family has its own section, with+ the fields expanded to dotted paths ("Pull Request Events" and its+ siblings under "Event payloads"; find them in `llms.txt`). In a broad run+ with `llms-full.txt` already fetched, `rg -n '^### Pull Request Events$'+ llms-full.txt` and read to the next `###`. From "Events", note which slugs+ are deliveredwithout a subscription and which must be selected.-3. **Resources**: each endpoint's page lists its "Response Fields" with nested- objects expanded (`reference/get-pull-request.md`), for "does the Origin- object carry this field". Fallback in a broad run:+3. **Resources**: each endpoint's section lists its "Response Fields" with+ nested objects expanded ("Get Pull Request" under "Pull requests"), for+ "does the Origin object carry this field". Fallback in a broad run:`rg -n '^### Get Pull Request$' llms-full.txt`.## Matching@@ -44,7 +46,7 @@ match is a candidate, not a result.**REST calls**1. Look for the same resource path under the Origin base path- (`reference/repository-paths.md` and `reference/ids.md` give the path forms). Most GitHub+ ("Repository paths" and "IDs" give the path forms). Most GitHubrepository, pull request, check, label, branch, and commit paths have adirect or near-direct counterpart.2. Re-home GitHub's issue-flavored pull request calls (`/issues/{n}/comments`,@@ -73,12 +75,12 @@ the operations the code calls and take the union of *their*`workflows`, `deployments`) go through `origin-isms.md` first.**Events → slugs.** Each GitHub `event` + `action` pair maps to at most one-slug in `reference/events.md`; the action is part of the slug. A pair with+slug in "Events"; the action is part of the slug. A pair withno slug is not an event on Origin. Check whether the state change isobservable another way before classifying it.**Payload fields → schema properties.** For each field path a handler reads,-walk the mapped family's "Payload Fields" list on its reference page and record+walk the mapped family's "Payload Fields" list in its docs section and recordone of five outcomes, matching the brief template's "How" column.Present at `<path>`. Present in the envelope (`event.type` carries whatGitHub puts in `action`). Follow-up read via `<operationId>` with identifiers@@ -89,7 +91,7 @@ event.## Out of domain and spec-silent-- A concept neither the spec nor the reference pages mention is not available+- A concept neither the spec nor the docs mention is not availabletoday and gets a question rather than a gap: there is no Origin answer yetto compare against, and the question is how the team tells Cursor theyneed it.