unknownskl · xuasir · Feb 27, 2026
diff --git a/skills/xbox-webapi-guide/SKILL.md b/skills/xbox-webapi-guide/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: "xbox-webapi-guide"
+description: "Guide for using xbox-webapi in Node/TS. Invoke when integrating or debugging Xbox profile, achievements, presence, media APIs, or handling XSTS auth and pagination."
+---
+
+# Xbox WebAPI Provider Index
+
+This skill provides an index of providers. Detailed capabilities and method docs live in the references directory. Before using any provider, make sure you have:
+- uhs: Xbox User Hash (from XSTS)
+- token: XSTS token (XBL3.0)
+
+Create client:
+- new XboxWebApi({ uhs, token })
+
+## Providers
+
+> - [achievements (Achievements & title history, contract: 2)](references/achievements.md)
+> - [catalog (Store catalog search/products, MS-CV: 1.0)](references/catalog.md)
+> - [gameclips (Game clips, contract: 3)](references/gameclips.md)
+> - [screenshots (Screenshots, contract: 3)](references/screenshots.md)
+> - [gamepass (Game Pass products/lists)](references/gamepass.md)
+> - [messages (Messaging)](references/messages.md)
+> - [people (Friends/recent players)](references/people.md)
+> - [pins (User lists: PINS/Saved for later)](references/pins.md)
+> - [profile (User profile, contract: 3)](references/profile.md)
+> - [social (Social summary/relationships)](references/social.md)
+> - [titlehub (Title history & details)](references/titlehub.md)
+> - [userpresence (Presence, contract: 3)](references/userpresence.md)
+> - [usersearch (User search, contract: 1)](references/usersearch.md)
+> - [userstats (User stats, contract: 2)](references/userstats.md)
+> - [smartglass (Console remote control/status, contract: 4)](references/smartglass.md)
+> - [xnotify (Xbox Live service status)](references/xnotify.md)
+> - [rest (Generic GET proxy)](references/rest.md)
+
+See the corresponding docs under references for detailed endpoints, headers, contracts, and method signatures.
diff --git a/skills/xbox-webapi-guide/references/achievements.md b/skills/xbox-webapi-guide/references/achievements.md
@@ -0,0 +1,86 @@
+# achievements
+
+- Endpoint: achievements.xboxlive.com
+- Contract: x-xbl-contract-version = 2
+- Description: Query user achievements, title history, and achievement item details. Supports pagination.
+
+## Methods
+- getAchievements(xuid, continuationToken?, maxItems?, skipItems?)
+  - GET /users/xuid({xuid})/history/titles
+- getTitleId(xuid, titleId, continuationToken?, maxItems?, skipItems?)
+  - GET /users/xuid({xuid})/achievements?titleid={titleId}
+- getItemDetail(xuid, serviceConfigId, achievementId, continuationToken?, maxItems?, skipItems?)
+  - GET /users/xuid({xuid})/achievements/{serviceConfigId}/{achievementId}
+
+## Parameters
+- xuid: string — Target user XUID
+- titleId: string — Xbox title ID (for per-title queries)
+- serviceConfigId: string — SCID for a title/service
+- achievementId: string — Achievement identifier within SCID
+- continuationToken?: string — Token to continue pagination
+- maxItems?: number — Page size
+- skipItems?: number — Offset for pagination
+
+## 返回值
+- 返回类型：HttpResponse<T>
+- 分页：当支持分页时，响应头包含 x-continuation-token；可调用 response.next() 拉取下一页
+- 常见形态：
+  - /history/titles 返回包含 titles 数组的对象
+  - /achievements?... 返回包含 achievements 数组的对象
+
+示例（标题历史 /history/titles）：
+
+```json
+{
+  "titles": [
+    {
+      "titleId": 1292135258,
+      "name": "Halo Infinite",
+      "displayImage": "https://images-eds.xboxlive.com/image.png",
+      "platforms": ["XboxOne", "Scarlett"]
+    }
+  ]
+}
+```
+
+示例（按 titleId 查询成就 /achievements）：
+
+```json
+{
+  "achievements": [
+    {
+      "id": "1",
+      "name": "First Steps",
+      "description": "Complete the tutorial",
+      "progressState": "Achieved",
+      "progression": {
+        "timeUnlocked": "2023-10-01T12:34:56Z"
+      },
+      "mediaAssets": [],
+      "rewards": []
+    }
+  ]
+}
+```
+
+## Example
+```ts
+import XboxWebApi from 'xbox-webapi'
+
+async function listAchievements(uhs: string, xsts: string, xuid: string) {
+  const api = new XboxWebApi({ uhs, token: xsts })
+  const page = await api.providers.achievements.getAchievements(xuid, undefined, 20)
+  console.log(page.data)
+
+  try {
+    const next = await page.next()
+    console.log(next.data)
+  } catch {
+    // no more pages
+  }
+}
+```
+
+## Notes
+- Returns HttpResponse<AchievementsResponse | AchievementsTitleResponse>
+- Use response.next() to fetch the next page when continuationToken is present
diff --git a/skills/xbox-webapi-guide/references/catalog.md b/skills/xbox-webapi-guide/references/catalog.md
@@ -0,0 +1,84 @@
+# catalog
+
+- Endpoint: displaycatalog.mp.microsoft.com
+- Headers: MS-CV = 1.0
+- Description: Store catalog search and product info, supports market/language parameters.
+
+## Methods
+- searchTitle(query, market='us', language='en-us', continuationToken?, maxItems?, skipItems?)
+  - GET /v7.0/productFamilies/autosuggest?…
+- getProductId(query, market='us', language='en-us', continuationToken?, maxItems?, skipItems?)
+  - GET /v7.0/productFamilies/autosuggest?…
+- getProductFromAlternateId(titleId, titleType, market='us', language='en-us', continuationToken?, maxItems?, skipItems?)
+  - GET /v7.0/productFamilies/autosuggest?…
+
+## Parameters
+- query: string — Search keyword or product bigId
+- titleId: string — Alternate identifier value
+- titleType: string — Alternate identifier type
+- market?: string — Region (default 'us')
+- language?: string — Locale (default 'en-us')
+- continuationToken?: string — Continue pagination
+- maxItems?: number — Page size
+- skipItems?: number — Offset
+
+## 返回值
+- 返回类型：HttpResponse<CatalogResponse>
+- 常见字段：
+  - Products：产品列表，包含 ProductId、LocalizedProperties、Images、DisplaySkuAvailabilities 等
+  - Items：在 autosuggest 场景下为建议项数组，包含 Title/ProductId/ImageUrl 等
+- 分页：多数 autosuggest 接口一次性返回；若提供 max/skip，将以分页形式返回相应范围
+
+示例（autosuggest 简化）：
+
+```json
+{
+  "Items": [
+    {
+      "Title": "Forza Horizon 5",
+      "ProductId": "9NKX70BBCDRN",
+      "ImageUrl": "https://store-images.microsoft.com/boxart.png"
+    }
+  ]
+}
+```
+
+示例（产品信息简化）：
+
+```json
+{
+  "Products": [
+    {
+      "ProductId": "9NKX70BBCDRN",
+      "LocalizedProperties": [
+        { "ProductTitle": "Forza Horizon 5" }
+      ],
+      "Images": [
+        { "Uri": "https://store-images.microsoft.com/boxart.png", "ImagePurpose": "BoxArt" }
+      ],
+      "DisplaySkuAvailabilities": [
+        {
+          "Sku": { "SkuId": "0000" },
+          "Availabilities": [
+            { "Actions": ["Purchase"], "Market": "US" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Example
+```ts
+import XboxWebApi from 'xbox-webapi'
+
+async function searchCatalog(uhs: string, xsts: string) {
+  const api = new XboxWebApi({ uhs, token: xsts })
+  const res = await api.providers.catalog.searchTitle('Forza', 'us', 'en-us', undefined, 25)
+  console.log(res.data)
+}
+```
+
+## Notes
+- Calls resetDefaultHeaders() to remove default auth headers; this domain typically does not require XBL3 contract headers.
diff --git a/skills/xbox-webapi-guide/references/gameclips.md b/skills/xbox-webapi-guide/references/gameclips.md
@@ -0,0 +1,62 @@
+# gameclips
+
+- Endpoint: mediahub.xboxlive.com
+- Contract: x-xbl-contract-version = 3
+- Description: Query user game clips. Supports pagination.
+
+## Methods
+- getGameclips(xuid, continuationToken?, maxItems?, skipItems?)
+-  - POST /gameclips/search (Body: { query: "OwnerXuid eq {xuid}", max?, skip? })
+
+## Parameters
+- xuid: string — Owner XUID
+- continuationToken?: string — Continue pagination
+- maxItems?: number — Page size (also used in body as max)
+- skipItems?: number — Offset (also used in body as skip)
+
+## 返回值
+- 返回类型：HttpResponse<GameclipsResponse>
+- 常见字段：
+  - gameClips：数组，每项代表一个录制片段
+  - gameClips[].gameClipId：唯一标识
+  - gameClips[].titleId / xuid / state / datePublished
+  - gameClips[].thumbnails[]：缩略图 uri 列表
+  - gameClips[].gameClipUris[]：视频文件 uri 列表（含 fileType）
+- 分页：响应头可包含 x-continuation-token；可通过 response.next() 获取下一页
+
+示例：
+
+```json
+{
+  "gameClips": [
+    {
+      "gameClipId": "3d6f9a0a-0000-0000-0000-000000000000",
+      "titleId": 1292135258,
+      "xuid": "2533274981234567",
+      "state": "Published",
+      "datePublished": "2023-10-01T12:34:56Z",
+      "thumbnails": [
+        { "uri": "https://clips.xboxlive.com/thumb.jpg" }
+      ],
+      "gameClipUris": [
+        { "uri": "https://clips.xboxlive.com/clip.mp4", "fileType": "mp4" }
+      ]
+    }
+  ]
+}
+```
+
+## Example
+```ts
+import XboxWebApi from 'xbox-webapi'
+
+async function listClips(uhs: string, xsts: string, xuid: string) {
+  const api = new XboxWebApi({ uhs, token: xsts })
+  const clips = await api.providers.gameclips.getGameclips(xuid, undefined, 20)
+  console.log(clips.data)
+}
+```
+
+## Notes
+- Returns HttpResponse<GameclipsResponse>
+- response.next() fetches the next page
diff --git a/skills/xbox-webapi-guide/references/gamepass.md b/skills/xbox-webapi-guide/references/gamepass.md
@@ -0,0 +1,76 @@
+# gamepass
+
+- Endpoint: catalog.gamepass.com
+- Headers: MS-CV = 1.0, calling-app-name/version preset
+- Description: Query Game Pass SIGL and product information.
+
+## Methods
+- getSigl(siglId, market='us', language='en-us')
+  - GET /sigls/v2?id={siglId}&market={market}&language={language}
+- getProducts(products: string[], market='us', language='en-us')
+-  - POST /v3/products?market={market}&language={language} (Body: { Products: [...] })
+- getProductsDetailed(products: string[])
+-  - POST /v3/products (hydration = RemoteHighSapphire0; ≤ 20 products per request)
+
+## Parameters
+- siglId: string — SIGL identifier
+- products: string[] — Product IDs to hydrate
+- market?: string — Region (default 'us')
+- language?: string — Locale (default 'en-us')
+
+## 返回值
+- 返回类型：HttpResponse<SiglResponse | ProductsResponse | any>
+- 常见形态：
+  - SIGL（/sigls/...）：包含产品集合或清单的对象（如包含产品 ID 列表、分组/分区信息）
+  - Products（/v3/products）：返回 Products 数组，含基本信息与可用性（Availabilities）
+- 注：getProductsDetailed 会返回更完整的 hydration 字段（如 Offers、Media、Tags 等）
+
+示例（SIGL 简化）：
+
+```json
+{
+  "Sigl": {
+    "Id": "f4c9b1e7-0000-0000-0000-000000000000",
+    "Market": "US",
+    "Language": "en-us",
+    "IncludedProductIds": ["9NKX70BBCDRN", "9P8CP1Q7PS4N"]
+  }
+}
+```
+
+示例（Products 简化）：
+
+```json
+{
+  "Products": [
+    {
+      "ProductId": "9NKX70BBCDRN",
+      "LocalizedProperties": [
+        { "ProductTitle": "Forza Horizon 5" }
+      ],
+      "DisplaySkuAvailabilities": [
+        {
+          "Sku": { "SkuId": "0000" },
+          "Availabilities": [
+            { "Actions": ["Purchase"], "Market": "US" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Example
+```ts
+import XboxWebApi from 'xbox-webapi'
+
+async function getSigl(uhs: string, xsts: string, siglId: string) {
+  const api = new XboxWebApi({ uhs, token: xsts })
+  const res = await api.providers.gamepass.getSigl(siglId, 'us', 'en-us')
+  console.log(res.data)
+}
+```
+
+## Notes
+- Returns HttpResponse<SiglResponse | ProductsResponse | any>