Skip to content

Cursor plugin specification and official plugins

TypeScript

Point at per-section reference pages

Cursor Agente7f7503434b6
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index f45fa68e..18fdb15d 100644
--- a/origin-apps/skills/origin-api/SKILL.md
+++ b/origin-apps/skills/origin-api/SKILL.md
@@ -20,56 +20,57 @@ rules to check first; it does not restate the docs.
Do not name an endpoint, scope, event slug, header, or limit from memory.
-- `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
- `https://cursor.com/docs/api/origin/changelog` (what moved).
+All paths below are under `https://cursor.com/docs/api/origin/`.
-For one question, use `llms.txt` to find the section, then read only that
-section. Fetch the whole `llms-full.txt` or `openapi.yaml` when the task
-needs broad coverage, such as a porting brief.
+- `llms.txt`: the index. Every section, endpoint, and webhook payload has its
+ own page at `reference/<anchor>.md`, and the index links to each.
+- `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.
-Cite `operationId`s and `llms-full.txt` anchors. Where this file and the docs
+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.
+
+Cite `operationId`s and reference pages. Where this file and the docs
disagree, the docs win.
## Where to look
-| Question | Section of `llms-full.txt` |
+| Question | Page |
| --- | --- |
-| Which credential for which call; minting and lifetime | `#authentication` through `#git-https-authentication` |
-| 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` |
+| 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` |
## Rules to check first
1. **Native or mirror.** Confirm the target repositories are Origin-native
or stable outbound mirrors. On any other mirror state an installation can
- only read, and pushes are not delivered (`#mirrored-repositories`,
- `#events`).
+ only read, and pushes are not delivered (`reference/mirrored-repositories.md`,
+ `reference/events.md`).
2. **Subscribe.** Only the `installation.*` events arrive without a
- subscription; a missing subscription is silence, not an error (`#events`).
+ subscription; a missing subscription is silence, not an error (`reference/events.md`).
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
+ (`reference/signature-verification.md`, `reference/retries.md`, `reference/automatic-disable.md`). The digest
step differs from the Standard Webhooks spec; do not assume a generic
verifier passes.
4. **Scopes from the spec.** Request the union of `x-origin-scopes.scopes`
- over the operations the app calls (`#scopes`).
+ over the operations the app calls (`reference/scopes.md`).
5. **Opaque tokens and IDs.** Do not build or parse page tokens or IDs
- (`#pagination`, `#ids`).
+ (`reference/pagination.md`, `reference/ids.md`).
Porting an existing GitHub App: the `port-github-app-to-origin` skill in
this 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.md
index f40aabfe..4478a40d 100644
--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -37,15 +37,16 @@ Adapt the steps to the app. The brief format matters most in its Feedback
section.
1. **Load the spec.** A brief needs broad coverage, so fetch the full
- `openapi.yaml` and `llms-full.txt`. Record `info.version` and the fetch
- time for provenance. Build the index per `references/spec-mapping.md`.
+ `openapi.yaml` and `llms-full.txt` (see `origin-api` for URLs). Record
+ `info.version` and the fetch time for provenance. Build the index per
+ `references/spec-mapping.md`.
2. **Discover** per `references/discovery.md`, including payload fields read
only for logging and calls the framework makes on the app's behalf. Note
what you looked for and did not find.
3. **Map** each capability (`references/spec-mapping.md`). Map the payload
fields the code reads, not only the event names; if a payload lacks a
field the REST resource has, a follow-up read is the usual answer
- (`#event-payloads`). Check `references/origin-isms.md` before calling
+ (`reference/event-payloads.md`). Check `references/origin-isms.md` before calling
anything a gap, and `references/gap-bar.md` before writing feedback. A
capability the Origin docs do not mention is not available today and gets
a question. A behavior the docs neither confirm nor deny becomes a
@@ -53,7 +54,7 @@ section.
carried over from the app's current platform.
4. **Write the brief** per `references/brief-template.md`: guidance and a
default outline, not a form. Every Origin claim names an `operationId`, a
- slug, or an `llms-full.txt` anchor. When there is feedback, also write the
+ slug, or a `reference/<anchor>.md` page. When there is feedback, also write the
Feedback section to `ORIGIN-FEEDBACK.md` beside the brief.
5. **Self-check** before finishing: every Origin claim resolves in the
fetched files; every gap has a feedback entry that names a tradeoff from
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 8061f723..b8f34deb 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 Cursor
and if any of it blocks.
- **Maps what the app uses to Origin.** Every capability the code relies on,
- with the Origin operation, slug, or `llms-full.txt` anchor it maps to, or a
+ with the Origin operation, slug, or reference page it maps to, or a
note that nothing does. Where a webhook handler reads specific payload
fields, say per field whether it is present, comes from the envelope, needs
a 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: the
union of `x-origin-scopes.scopes` over the operations named, minus what
- `#scopes` says is automatic or implied.
+ `reference/scopes.md` says is automatic or implied.
- **Gives an app-specific first-run path when it helps.** The events to
select by slug, the mirror-state check, the first event that should arrive
and what it should carry, the first write. Generic setup steps belong to
- `llms-full.txt#implementation-checklist`, not here. Skip for a read-only app
+ `reference/implementation-checklist.md`, not here. Skip for a read-only app
with one event.
- **Adds plan notes.** What drives the size of the port (a few bullets, no
time 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 an anchor. Nothing from
+ `llms-full.txt`: an `operationId`, a slug, or a reference page. Nothing from
memory.
- Behavior the docs do not state is a question plus a first-run step that
observes 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.md
index 90304a1f..8acec6d4 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 documented
Origin path exists (`maps`) or nothing in the current spec covers it
-(`not-available`), and where the Origin answer lives (an anchor in
-`llms-full.txt` unless noted). A `maps` row is a question only if the team
+(`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
wants the old shape back. A `not-available` row is a question, and feedback
if it meets the bar in `gap-bar.md`. Read the source; do not copy this table
into 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 (`#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` |
+| 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` |
| 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` | `#check-runs` (check runs with a stable `key`) |
+| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `maps` | `reference/check-runs.md` (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` (`#events`). |
-| App-manifest conversion | `maps` | App creation form or `CreateApp` (`#installation`, endpoint reference) |
+| 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) |
| 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); `#git-https-authentication` for pushes |
+| 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 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 `#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` |
+| 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` |
| Reviews keyed by `commit_id` | `maps` | `pullRequestVersion` on the review schema |
-| Finding own check runs or comments by actor | `maps` | `#check-runs` (`key`); comments and reviews by a marker the app controls |
+| Finding own check runs or comments by actor | `maps` | `reference/check-runs.md` (`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 not
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 54c45634..fb728aea 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,5 +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/`.
+
Every mapping in the brief comes from the fetched `openapi.yaml`, not from a
table here. Build the index once. Every later step looks things up in it.
@@ -7,9 +9,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. `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`. 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. `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. |
## Build the index
@@ -17,19 +19,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 union
of scopes with the operations that need each, and separate
installation-requestable scopes from ambient and user-only ones
- (`llms-full.txt#scopes` explains the difference). The user-only set tells
+ (`reference/scopes.md` explains the difference). The user-only set tells
you which GitHub flows have no app-side equivalent. Read parameters and
response 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's fields, with nested
- objects expanded to dotted paths, are under its heading in
- `llms-full.txt` (`rg -n '^### Pull Request Events$' llms-full.txt`, then
- read to the next `###`). From `#events`, note which slugs are delivered
+ 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
without a subscription and which must be selected.
-3. **Resources**: each endpoint's "Response Fields" in `llms-full.txt`
- (`rg -n '^### Get Pull Request$' llms-full.txt`) lists the fields the
- object carries, nested objects expanded, for "does the Origin object carry
- this field".
+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:
+ `rg -n '^### Get Pull Request$' llms-full.txt`.
## Matching
@@ -41,7 +44,7 @@ match is a candidate, not a result.
**REST calls**
1. Look for the same resource path under the Origin base path
- (`llms-full.txt#repository-paths` and `#ids` give the path forms). Most GitHub
+ (`reference/repository-paths.md` and `reference/ids.md` 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`,
@@ -70,12 +73,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 `llms-full.txt#events`; the action is part of the slug. A pair with
+slug in `reference/events.md`; the action is part of the slug. A pair with
no slug is not an event on Origin. Check whether the state change is
observable another way before classifying it.
**Payload fields → schema properties.** For each field path a handler reads,
-walk the mapped family's "Payload Fields" list in `llms-full.txt` and record
+walk the mapped family's "Payload Fields" list on its reference page and record
one of five outcomes, matching the brief template's "How" column.
Present at `<path>`. Present in the envelope (`event.type` carries what
GitHub puts in `action`). Follow-up read via `<operationId>` with identifiers
@@ -86,7 +89,7 @@ event.
## Out of domain and spec-silent
-- A concept neither the spec nor `llms-full.txt` mentions is not available
+- A concept neither the spec nor the reference pages mention is not available
today and gets a question rather than a gap: there is no Origin answer yet
to compare against, and the question is how the team tells Cursor they
need it.