Skip to content

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.md
index 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 docs
disagree, 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 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 (`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 body
before 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 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 (`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 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 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 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
- (`reference/event-payloads.md`). Check `references/origin-isms.md` before calling
+ ("Event payloads"). 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
@@ -54,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 a `reference/<anchor>.md` page. When there is feedback, also write the
+ slug, or a docs section. 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 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 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 reference page it maps to, or a
+ with the Origin operation, slug, or docs section 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
- `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 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
- `reference/implementation-checklist.md`, not here. Skip for a read-only app
+ "Implementation checklist", 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 a reference page. Nothing from
+ `llms-full.txt`: an `operationId`, a slug, or a section. 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 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 documented
Origin 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 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 (`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 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 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 a
table 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 union
of scopes with the operations that need each, and separate
installation-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 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 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 delivered
without 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 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`,
@@ -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 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 on its reference page and record
+walk the mapped family's "Payload Fields" list in its docs section 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
@@ -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 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.