Skip to content

Cursor plugin specification and official plugins

TypeScript

Drop the spec indexer; llms-full.txt already expands nested fields

Cursor Agent89b461d5a6cd
diff --git a/origin-apps/README.md b/origin-apps/README.md
index 6118ada1..92d10dc3 100644
--- a/origin-apps/README.md
+++ b/origin-apps/README.md
@@ -79,9 +79,6 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/
- For the porting skill, read access to the app's source. Producing the brief
needs no Origin credentials. You follow the brief's hello-world path
afterwards.
-- Optional: `python3` with PyYAML for the porting skill's
- `scripts/index-origin-spec.py`, which prints webhook payload fields with
- their references resolved. Without it the skill reads the spec directly.
## Where the brief goes
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index 4979deab..f0400dc0 100644
--- a/origin-apps/skills/origin-api/SKILL.md
+++ b/origin-apps/skills/origin-api/SKILL.md
@@ -26,6 +26,11 @@ which rules to check first. It restates nothing you can read there.
- `https://cursor.com/docs/api/origin/llms.txt` (index) and
`https://cursor.com/docs/api/origin/changelog` (what moved).
+Lookup order: for one question, read `llms.txt` to find the section, then
+fetch only that section of `llms-full.txt` or the page it links. Fetch the
+whole `llms-full.txt` or `openapi.yaml` only when the task needs broad
+coverage, such as a porting brief.
+
Cite `operationId`s and `llms-full.txt` anchors. If this file and the fetched
docs disagree, the docs win.
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 450753d5..897ba919 100644
--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -9,8 +9,6 @@ description: >-
license: MIT
compatibility: >-
Needs network access to https://cursor.com/docs/api/origin/* at run time.
- The optional payload-field script needs python3 with PyYAML; without it,
- read the spec directly.
---
# Port a GitHub App to an Origin App
@@ -33,11 +31,11 @@ scopes, webhooks, paging, IDs, and errors. Follow it first. Nothing here repeats
## Procedure
-1. **Load the spec** (`origin-api`, "Fetch first"). Record `info.version` and
- the fetch time for the brief's provenance. Build the mapping index per
- `references/spec-mapping.md`: two `rg` commands for operations, scopes,
- and slugs, and `scripts/index-origin-spec.py openapi.yaml` (needs PyYAML)
- for webhook payload fields.
+1. **Load the spec** (`origin-api`, "Fetch first"). A brief needs broad
+ coverage, so fetch the full `openapi.yaml` and `llms-full.txt`; the
+ narrow lookup order in `origin-api` is for later single questions. Record
+ `info.version` and the fetch time for the brief's provenance. Build the
+ mapping index per `references/spec-mapping.md`.
2. **Discover** per `references/discovery.md`. Record a file and line for
every fact, 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
@@ -95,4 +93,3 @@ cards to Cursor. The brief carries them and the team decides.
| `references/origin-isms.md` | Labeling a missing GitHub feature. |
| `references/gap-bar.md` | Deciding whether a difference earns a card, and writing it. |
| `references/brief-template.md` | Writing the output. |
-| `scripts/index-origin-spec.py` | Listing webhook payload families with their fields resolved. Optional. |
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 893c3222..16c22e67 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
@@ -21,13 +21,15 @@ table here. Build the index once. Every later step looks things up in it.
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. `scripts/index-origin-spec.py
- openapi.yaml` prints each payload family with its fields and `$ref`s
- resolved two levels deep; `schema <Name>` does the same for one component.
- From `llms-full.txt#events`, note which slugs are delivered without a
- subscription and which must be selected.
-3. **Resources**: component schemas returned by `Get…`/`List…`, with field
- names, for "does the Origin object carry this field".
+ 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
+ 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".
## Matching
@@ -73,7 +75,8 @@ 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 slug's payload schema and record one of four outcomes.
+walk the mapped family's "Payload Fields" list in `llms-full.txt` and record
+one of four outcomes.
Present at `<path>`. Follow-up read via `<operationId>` with identifiers the
payload carries. Derivable from present fields, saying how and whether the
format is contractual. Absent, which goes to the gap bar. A field on the REST
diff --git a/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py b/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py
deleted file mode 100644
index b50ab04e..00000000
--- a/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py
+++ /dev/null
@@ -1,125 +0,0 @@
-#!/usr/bin/env python3
-"""Print the Origin webhook payload families with their fields resolved.
-
-Usage:
- python3 index-origin-spec.py openapi.yaml # every payload family
- python3 index-origin-spec.py openapi.yaml schema PullRequest # one component
-
-Fetch the spec first:
- curl -sSL https://cursor.com/docs/api/origin/openapi.yaml -o openapi.yaml
-
-Operations and scopes do not need this script. Grep the spec directly:
- rg -B1 -A4 'x-origin-scopes:' openapi.yaml
- rg -A3 'x-origin-webhook-events:' openapi.yaml
-
-Read-only. Needs PyYAML (`pip install pyyaml`). Everything printed comes from
-the spec you pass in; nothing is pinned or embedded here.
-"""
-
-import sys
-
-try:
- import yaml
-except ImportError: # pragma: no cover
- sys.stderr.write(
- "PyYAML is not installed. Run `pip install pyyaml`, or read the spec "
- "directly (search for `x-origin-webhook-events:` and follow the "
- "`$ref`s by hand).\n"
- )
- sys.exit(2)
-
-# Field descriptions are cut to one sentence and this many characters so a
-# family fits on one screen.
-DESCRIPTION_CHARS = 140
-# How many `$ref` levels to expand under a payload. Two reaches the embedded
-# resource and its direct children, which is what field mapping needs.
-SCHEMA_DEPTH = 2
-
-
-def ref_name(node):
- if not isinstance(node, dict):
- return None
- if "$ref" in node:
- return node["$ref"].rsplit("/", 1)[-1]
- if "allOf" in node and node["allOf"] and "$ref" in node["allOf"][0]:
- return node["allOf"][0]["$ref"].rsplit("/", 1)[-1]
- if node.get("type") == "array":
- inner = ref_name(node.get("items", {}))
- return f"{inner}[]" if inner else "array"
- return None
-
-
-def first_sentence(text):
- return " ".join((text or "").split()).split(". ")[0][:DESCRIPTION_CHARS]
-
-
-def print_schema(components, name, depth=0, seen=None):
- seen = seen or set()
- schema = components.get(name)
- if not schema:
- print(f"{' ' * depth}(no component named {name})")
- return
- for field, node in (schema.get("properties") or {}).items():
- kind = ref_name(node) or node.get("type", "?")
- desc = first_sentence(node.get("description"))
- print(f"{' ' * depth}{field}: {kind}" + (f" -- {desc}" if desc else ""))
- inner = (ref_name(node) or "").rstrip("[]")
- if inner and inner in components and depth < SCHEMA_DEPTH and inner not in seen:
- seen.add(inner)
- print_schema(components, inner, depth + 1, seen)
-
-
-def print_events(components):
- print("== WEBHOOK PAYLOAD FAMILIES (schema | slugs | x-origin-webhook-resource)")
- for name, schema in components.items():
- slugs = schema.get("x-origin-webhook-events")
- if not slugs:
- continue
- print(f"{name} | {slugs} | resource={schema.get('x-origin-webhook-resource')}")
- print_schema(components, name, depth=1)
-
-
-def load_spec(path):
- try:
- with open(path, encoding="utf-8") as fh:
- spec = yaml.safe_load(fh)
- except FileNotFoundError:
- sys.stderr.write(f"{path}: not found. Fetch it first (command in --help).\n")
- return None
- except yaml.YAMLError as err:
- sys.stderr.write(f"{path}: not valid YAML ({err}).\n")
- return None
- if not isinstance(spec, dict) or "components" not in spec or "info" not in spec:
- sys.stderr.write(f"{path}: not an OpenAPI document (no `info` or `components`).\n")
- return None
- components = (spec.get("components") or {}).get("schemas") or {}
- if not any("x-origin-webhook-events" in s for s in components.values() if isinstance(s, dict)):
- sys.stderr.write(
- f"{path}: no schema carries `x-origin-webhook-events`; is this the Origin spec?\n"
- )
- return None
- return spec
-
-
-def main(argv):
- if len(argv) < 2 or argv[1] in ("-h", "--help"):
- print(__doc__)
- return 1
- spec = load_spec(argv[1])
- if spec is None:
- return 1
- components = spec["components"]["schemas"]
- schema_mode = len(argv) > 2 and argv[2] == "schema"
- if schema_mode and len(argv) < 4:
- sys.stderr.write("schema mode needs a component name.\n")
- return 1
- print(f"# {spec['info'].get('title')} {spec['info'].get('version')}")
- if schema_mode:
- print_schema(components, argv[3])
- else:
- print_events(components)
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(main(sys.argv))