codex-xai-oauth 0.2.0 → 0.2.2

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-xai-oauth",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Use xAI/Grok OAuth or API-key credentials from Codex through local MCP tools.",
   "author": {
     "name": "ilseoblee"

package/README.md

@@ -29,6 +29,8 @@ npm run build
 python3 /Users/ilseoblee/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
 ```
 
+Release notes are tracked in [RELEASE_NOTES.md](RELEASE_NOTES.md).
+
 ## Install / Doctor
 
 From a checkout:
@@ -57,6 +59,8 @@ codex-xai-oauth doctor
 
 ## Authentication
 
+The default OAuth store is the shared xAI OIDC file at `~/.grok/auth.json`. This project reads and writes that shared store by default; it does not require a specific Grok CLI build. `CODEX_XAI_OAUTH_AUTH_FILE` is available only when you intentionally want a separate package-specific auth file.
+
 Browser OAuth login:
 
 ```bash
@@ -93,22 +97,30 @@ Save generated image payloads to local artifacts:
 npx codex-xai-oauth image --prompt "minimal blue dot icon" --response-format b64_json --artifact-dir .codex-xai-artifacts
 ```
 
-OAuth credentials are stored at:
+OAuth credentials are stored by default as an xAI OIDC entry in:
 
 ```text
-~/.config/codex-xai-oauth/auth.json
+~/.grok/auth.json
 ```
 
-If that file is absent and no custom auth file is configured, the tools also read the Grok CLI OIDC session from:
+Legacy package-specific OAuth credentials are still read as a fallback from:
 
 ```text
-~/.grok/auth.json
+~/.config/codex-xai-oauth/auth.json
 ```
 
+Credential precedence:
+
+- `CODEX_XAI_OAUTH_AUTH_FILE`, when explicitly set.
+- `~/.grok/auth.json`.
+- `~/.config/codex-xai-oauth/auth.json` legacy fallback.
+- `XAI_API_KEY`.
+- Codex model provider `experimental_bearer_token`.
+
 Overrides:
 
-- `CODEX_XAI_OAUTH_AUTH_FILE`: custom OAuth auth JSON path.
-- `CODEX_XAI_OAUTH_GROK_AUTH_FILE`: custom Grok CLI auth JSON path, mainly for tests or nonstandard installs.
+- `CODEX_XAI_OAUTH_AUTH_FILE`: custom package-format OAuth auth JSON path.
+- `CODEX_XAI_OAUTH_GROK_AUTH_FILE`: custom shared xAI OIDC auth JSON path, mainly for tests or nonstandard installs.
 - `XAI_API_KEY`: API-key fallback.
 - `XAI_BASE_URL`: custom xAI-compatible base URL.
 
@@ -141,6 +153,50 @@ The proxy exposes:
 - `.mcp.json` starts the stdio MCP server from `dist/mcp/server.js`.
 - `skills/xai-grok/SKILL.md` tells Codex when to use the tools and how to avoid leaking secrets.
 
+## Built-In Skills
+
+The plugin bundles a general skill plus one dedicated skill for each MCP tool listed in What Works:
+
+- `xai-grok`: umbrella skill for plugin overview, setup orientation, or multi-tool requests when no dedicated `xai_*` skill is a better fit.
+- `xai_status`: dedicated trigger for `xai_status`.
+- `xai_login_instructions`: dedicated trigger for `xai_login_instructions`.
+- `xai_generate_text`: dedicated trigger for `xai_generate_text`.
+- `xai_web_search`: dedicated trigger for `xai_web_search`.
+- `xai_x_search`: dedicated trigger for `xai_x_search`.
+- `xai_image_generate`: dedicated trigger for `xai_image_generate`.
+- `xai_tts`: dedicated trigger for `xai_tts`.
+- `xai_video_generate`: dedicated trigger for `xai_video_generate`.
+
+The dedicated `xai_image_generate` skill lets Codex route natural-language image requests to `xai_image_generate`.
+
+MCP tool arguments:
+
+```json
+{
+  "prompt": "tiny minimalist blue dot icon on white background",
+  "resolution": "2k",
+  "artifact_dir": ".codex-xai-artifacts"
+}
+```
+
+Equivalent CLI:
+
+```bash
+npx codex-xai-oauth image \
+  --prompt "tiny minimalist blue dot icon on white background" \
+  --resolution 2k \
+  --artifact-dir .codex-xai-artifacts
+```
+
+For base64 image payloads saved locally:
+
+```bash
+npx codex-xai-oauth image \
+  --prompt "a cinematic robot reading a book" \
+  --response-format b64_json \
+  --artifact-dir .codex-xai-artifacts
+```
+
 Build before installing or using the MCP server:
 
 ```bash

package/RELEASE_NOTES.md

@@ -0,0 +1,13 @@
+# Release Notes
+
+## 0.2.2
+
+- Changed the default OAuth read/write path to the shared xAI OIDC store at `~/.grok/auth.json`.
+- Kept `CODEX_XAI_OAUTH_AUTH_FILE` as an explicit package-format override and `~/.config/codex-xai-oauth/auth.json` as a legacy fallback.
+- Updated README, MCP login instructions, and bundled skills to explain that `~/.grok/auth.json` is a shared xAI OIDC auth store, not a requirement to use a specific Grok CLI build.
+
+## 0.2.1
+
+- Added dedicated built-in skills for every README-listed MCP tool: `xai_status`, `xai_login_instructions`, `xai_generate_text`, `xai_web_search`, `xai_x_search`, `xai_image_generate`, `xai_tts`, and `xai_video_generate`.
+- Narrowed `xai-grok` to an umbrella skill for plugin overview, setup orientation, and multi-tool requests so specific `xai_*` skills can load only when needed.
+- Updated README skill documentation to match the plugin surface promised by the MCP tool list.

package/dist/cli.js

@@ -3386,7 +3386,7 @@ import { randomBytes as randomBytes2 } from "node:crypto";
 import { createServer } from "node:http";
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.0";
+var PACKAGE_VERSION = "0.2.2";
 
 // src/xai/constants.ts
 var XAI_BASE_URL = "https://api.x.ai/v1";
@@ -4756,7 +4756,7 @@ function defaultAuthPath() {
   return join(configHome(), "codex-xai-oauth", "auth.json");
 }
 function authPath() {
-  return process.env["CODEX_XAI_OAUTH_AUTH_FILE"] || defaultAuthPath();
+  return process.env["CODEX_XAI_OAUTH_AUTH_FILE"] || grokAuthPath();
 }
 function defaultGrokAuthPath() {
   return join(homedir(), ".grok", "auth.json");
@@ -4765,10 +4765,13 @@ function grokAuthPath() {
   return process.env["CODEX_XAI_OAUTH_GROK_AUTH_FILE"] || defaultGrokAuthPath();
 }
 function readStoredAuth(path2 = authPath()) {
+  if (path2 === grokAuthPath()) {
+    return readGrokStoredAuth(path2) || (!process.env["CODEX_XAI_OAUTH_AUTH_FILE"] ? readPackageStoredAuth(defaultAuthPath()) : void 0);
+  }
+  return readPackageStoredAuth(path2);
+}
+function readPackageStoredAuth(path2) {
   if (!existsSync(path2)) {
-    if (path2 === defaultAuthPath() && !process.env["CODEX_XAI_OAUTH_AUTH_FILE"]) {
-      return readGrokStoredAuth();
-    }
     return void 0;
   }
   try {
@@ -4797,6 +4800,9 @@ function readStoredAuth(path2 = authPath()) {
     throw error51;
   }
 }
+function grokEntryKey() {
+  return `${XAI_OAUTH_ISSUER}::${XAI_OAUTH_CLIENT_ID}`;
+}
 function parseGrokExpiry(value) {
   const parsed = Date.parse(value);
   return Number.isNaN(parsed) ? void 0 : parsed;
@@ -4851,9 +4857,40 @@ function readGrokStoredAuth(path2 = grokAuthPath()) {
   }
 }
 function writeStoredAuth(auth, path2 = authPath()) {
+  if (path2 === grokAuthPath()) {
+    writeGrokStoredAuth(auth, path2);
+    return;
+  }
   mkdirSync(dirname(path2), { recursive: true, mode: 448 });
   writeFileSync(path2, JSON.stringify(auth, null, 2), { mode: 384 });
 }
+function readGrokAuthFile(path2) {
+  if (!existsSync(path2)) {
+    return {};
+  }
+  try {
+    const data = JSON.parse(readFileSync(path2, "utf8"));
+    return isRecord(data) ? data : {};
+  } catch (error51) {
+    if (error51 instanceof Error) {
+      return {};
+    }
+    throw error51;
+  }
+}
+function writeGrokStoredAuth(auth, path2) {
+  const data = readGrokAuthFile(path2);
+  data[grokEntryKey()] = {
+    auth_mode: "oidc",
+    expires_at: new Date(auth.expires).toISOString(),
+    key: auth.access,
+    oidc_client_id: XAI_OAUTH_CLIENT_ID,
+    oidc_issuer: XAI_OAUTH_ISSUER,
+    refresh_token: auth.refresh
+  };
+  mkdirSync(dirname(path2), { recursive: true, mode: 448 });
+  writeFileSync(path2, JSON.stringify(data, null, 2), { mode: 384 });
+}
 function oauthExpiry(timestampSeconds) {
   return Date.now() + Number(timestampSeconds || 3600) * 1e3;
 }
@@ -5209,7 +5246,7 @@ async function resolveXaiCredentials() {
     };
   }
   throw new Error(
-    "xAI credentials not found. Run `codex-xai-oauth login --device`, set XAI_API_KEY, or configure a Codex model provider with experimental_bearer_token."
+    "xAI credentials not found. Run `codex-xai-oauth login` to write ~/.grok/auth.json, run `codex-xai-oauth login --device`, set XAI_API_KEY, or configure a Codex model provider with experimental_bearer_token."
   );
 }
 async function credentialStatus() {
@@ -20508,7 +20545,9 @@ program2.command("image").description("Generate an image through xAI /images/gen
     console.log(JSON.stringify(result, null, 2));
   }
 );
-program2.command("login").description("Start xAI OAuth login and save credentials for Codex tools").option("--device", "use device-code login for headless environments").option("--no-browser", "print the URL without opening a browser").action(
+program2.command("login").description(
+  "Start xAI OAuth login and save credentials to the shared ~/.grok auth store"
+).option("--device", "use device-code login for headless environments").option("--no-browser", "print the URL without opening a browser").action(
   async (options) => {
     try {
       const flow = options.device ? await beginDeviceOAuth() : await beginOAuth();

package/dist/mcp/server.js

@@ -30948,7 +30948,7 @@ var StdioServerTransport = class {
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.0";
+var PACKAGE_VERSION = "0.2.2";
 
 // src/xai/constants.ts
 var XAI_BASE_URL = "https://api.x.ai/v1";
@@ -32309,7 +32309,7 @@ function defaultAuthPath() {
   return join(configHome(), "codex-xai-oauth", "auth.json");
 }
 function authPath() {
-  return process.env["CODEX_XAI_OAUTH_AUTH_FILE"] || defaultAuthPath();
+  return process.env["CODEX_XAI_OAUTH_AUTH_FILE"] || grokAuthPath();
 }
 function defaultGrokAuthPath() {
   return join(homedir(), ".grok", "auth.json");
@@ -32318,10 +32318,13 @@ function grokAuthPath() {
   return process.env["CODEX_XAI_OAUTH_GROK_AUTH_FILE"] || defaultGrokAuthPath();
 }
 function readStoredAuth(path = authPath()) {
+  if (path === grokAuthPath()) {
+    return readGrokStoredAuth(path) || (!process.env["CODEX_XAI_OAUTH_AUTH_FILE"] ? readPackageStoredAuth(defaultAuthPath()) : void 0);
+  }
+  return readPackageStoredAuth(path);
+}
+function readPackageStoredAuth(path) {
   if (!existsSync(path)) {
-    if (path === defaultAuthPath() && !process.env["CODEX_XAI_OAUTH_AUTH_FILE"]) {
-      return readGrokStoredAuth();
-    }
     return void 0;
   }
   try {
@@ -32350,6 +32353,9 @@ function readStoredAuth(path = authPath()) {
     throw error51;
   }
 }
+function grokEntryKey() {
+  return `${XAI_OAUTH_ISSUER}::${XAI_OAUTH_CLIENT_ID}`;
+}
 function parseGrokExpiry(value) {
   const parsed = Date.parse(value);
   return Number.isNaN(parsed) ? void 0 : parsed;
@@ -32404,9 +32410,40 @@ function readGrokStoredAuth(path = grokAuthPath()) {
   }
 }
 function writeStoredAuth(auth, path = authPath()) {
+  if (path === grokAuthPath()) {
+    writeGrokStoredAuth(auth, path);
+    return;
+  }
   mkdirSync(dirname(path), { recursive: true, mode: 448 });
   writeFileSync(path, JSON.stringify(auth, null, 2), { mode: 384 });
 }
+function readGrokAuthFile(path) {
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    return isRecord(data) ? data : {};
+  } catch (error51) {
+    if (error51 instanceof Error) {
+      return {};
+    }
+    throw error51;
+  }
+}
+function writeGrokStoredAuth(auth, path) {
+  const data = readGrokAuthFile(path);
+  data[grokEntryKey()] = {
+    auth_mode: "oidc",
+    expires_at: new Date(auth.expires).toISOString(),
+    key: auth.access,
+    oidc_client_id: XAI_OAUTH_CLIENT_ID,
+    oidc_issuer: XAI_OAUTH_ISSUER,
+    refresh_token: auth.refresh
+  };
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  writeFileSync(path, JSON.stringify(data, null, 2), { mode: 384 });
+}
 function oauthExpiry(timestampSeconds) {
   return Date.now() + Number(timestampSeconds || 3600) * 1e3;
 }
@@ -32574,7 +32611,7 @@ async function resolveXaiCredentials() {
     };
   }
   throw new Error(
-    "xAI credentials not found. Run `codex-xai-oauth login --device`, set XAI_API_KEY, or configure a Codex model provider with experimental_bearer_token."
+    "xAI credentials not found. Run `codex-xai-oauth login` to write ~/.grok/auth.json, run `codex-xai-oauth login --device`, set XAI_API_KEY, or configure a Codex model provider with experimental_bearer_token."
   );
 }
 async function credentialStatus() {
@@ -32918,8 +32955,22 @@ function createXaiMcpServer() {
     async () => textJson({
       auth_file: authPath(),
       grok_auth_file: grokAuthPath(),
+      legacy_auth_file: defaultAuthPath(),
+      shared_auth_store: "~/.grok/auth.json",
+      base_url: xaiBaseUrl(),
+      browser_login: "codex-xai-oauth login",
       device_login: "codex-xai-oauth login --device",
-      api_key: "Set XAI_API_KEY in the environment."
+      status: "codex-xai-oauth status",
+      doctor: "codex-xai-oauth doctor",
+      api_key: "Set XAI_API_KEY in the environment.",
+      credential_precedence: [
+        "CODEX_XAI_OAUTH_AUTH_FILE",
+        "~/.grok/auth.json",
+        "~/.config/codex-xai-oauth/auth.json",
+        "XAI_API_KEY",
+        "Codex model provider experimental_bearer_token"
+      ],
+      note: "Default OAuth login writes a shared xAI OIDC entry to ~/.grok/auth.json; this is a shared auth store, not a requirement to use a specific Grok CLI build."
     })
   );
   registerGenerationTools(server);

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PACKAGE_VERSION = "0.2.0";
+export declare const PACKAGE_VERSION = "0.2.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/xai/constants.d.ts

@@ -12,6 +12,6 @@ export declare const XAI_REDIRECT_PATH = "/callback";
 export declare const OPENAI_COMPAT_HOST = "127.0.0.1";
 export declare const OPENAI_COMPAT_PORT = 8787;
 export declare const REFRESH_SKEW_MS: number;
-export declare const USER_AGENT = "codex-xai-oauth/0.2.0";
+export declare const USER_AGENT = "codex-xai-oauth/0.2.2";
 export declare function xaiBaseUrl(): string;
 //# sourceMappingURL=constants.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-xai-oauth",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Codex plugin exposing xAI/Grok OAuth and API-key tools through a local MCP server.",
   "type": "module",
   "main": "./dist/mcp/server.js",

package/skills/xai-generate-text/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: xai_generate_text
+description: Use when the user asks to generate, draft, answer, rewrite, summarize, or reason with xAI/Grok text generation through xai_generate_text.
+---
+
+# xAI Generate Text
+
+Use `xai_generate_text` for text generation with Grok through xAI Responses.
+
+Preferred MCP call:
+
+```json
+{
+  "prompt": "Write a concise release note for artifact-backed image generation.",
+  "reasoning_effort": "medium"
+}
+```
+
+Options:
+
+- `prompt`: required user request.
+- `model`: optional Grok model.
+- `reasoning_effort`: `low`, `medium`, or `high`.
+
+Use `xai_web_search` instead when the user asks for current web information. Use `xai_x_search` instead when the user asks to search X/Twitter.

package/skills/xai-grok/SKILL.md

@@ -1,11 +1,20 @@
 ---
 name: xai-grok
-description: Use xAI/Grok OAuth or API-key MCP tools for text generation, web search, X search, image generation, TTS, video generation, or credential status from Codex.
+description: Use only for general codex-xai-oauth/xAI Grok plugin overview, setup orientation, or multi-tool requests when no dedicated xai_* skill is a better fit.
 ---
 
 # xAI Grok
 
-Use the bundled MCP tools when the user asks for xAI, Grok, Grok Imagine, xAI image generation, xAI web search, X search, TTS, video generation, or xAI credential status.
+Use this umbrella skill only for general plugin overview, setup orientation, or multi-tool xAI/Grok requests. For a specific tool request, prefer the dedicated skill:
+
+- `xai_status`
+- `xai_login_instructions`
+- `xai_generate_text`
+- `xai_web_search`
+- `xai_x_search`
+- `xai_image_generate`
+- `xai_tts`
+- `xai_video_generate`
 
 ## Tools
 
@@ -20,10 +29,10 @@ Use the bundled MCP tools when the user asks for xAI, Grok, Grok Imagine, xAI im
 
 ## Credential Rules
 
-- Prefer existing OAuth credentials in `~/.config/codex-xai-oauth/auth.json`.
-- If package OAuth credentials are absent, use the Grok CLI OIDC session in `~/.grok/auth.json`.
-- `CODEX_XAI_OAUTH_AUTH_FILE` overrides the auth-file path.
-- `CODEX_XAI_OAUTH_GROK_AUTH_FILE` overrides the Grok CLI auth-file path.
+- Prefer the shared xAI OIDC auth store at `~/.grok/auth.json`. It is a shared auth file, not a requirement to use a specific Grok CLI build.
+- `CODEX_XAI_OAUTH_AUTH_FILE` overrides the auth-file path with a package-format OAuth file.
+- `CODEX_XAI_OAUTH_GROK_AUTH_FILE` overrides the shared xAI OIDC auth-file path.
+- Legacy package OAuth credentials at `~/.config/codex-xai-oauth/auth.json` are read only when the shared store is absent.
 - `XAI_API_KEY` is the fallback credential.
 - `XAI_BASE_URL` can override the API base URL.
 - Do not print, quote, summarize, or store access tokens, refresh tokens, or API keys in chat.
@@ -52,6 +61,34 @@ codex-xai-oauth status
 
 Use `xai_image_generate` when the user asks to generate an image, Grok Imagine image, or xAI image. Defaults are `model: grok-imagine-image`, `response_format: url`, and `n: 1`.
 
+Preferred MCP call:
+
+```json
+{
+  "prompt": "tiny minimalist blue dot icon on white background",
+  "resolution": "2k",
+  "artifact_dir": ".codex-xai-artifacts"
+}
+```
+
+Direct CLI equivalent:
+
+```bash
+codex-xai-oauth image \
+  --prompt "tiny minimalist blue dot icon on white background" \
+  --resolution 2k \
+  --artifact-dir .codex-xai-artifacts
+```
+
+For base64 image payloads saved locally:
+
+```bash
+codex-xai-oauth image \
+  --prompt "a cinematic robot reading a book" \
+  --response-format b64_json \
+  --artifact-dir .codex-xai-artifacts
+```
+
 Supported image options:
 
 - `prompt`: required image prompt.

package/skills/xai-image-generate/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: xai_image_generate
+description: Use when the user asks to generate, create, make, or save images with xAI, Grok Imagine, xai_image_generate, or codex-xai-oauth image artifacts.
+---
+
+# xAI Image Generate
+
+Use `xai_image_generate` for xAI/Grok Imagine image requests.
+
+## Preferred MCP Call
+
+```json
+{
+  "prompt": "tiny minimalist blue dot icon on white background",
+  "resolution": "2k",
+  "artifact_dir": ".codex-xai-artifacts"
+}
+```
+
+## CLI Equivalent
+
+```bash
+codex-xai-oauth image \
+  --prompt "tiny minimalist blue dot icon on white background" \
+  --resolution 2k \
+  --artifact-dir .codex-xai-artifacts
+```
+
+For base64 image payloads saved locally:
+
+```bash
+codex-xai-oauth image \
+  --prompt "a cinematic robot reading a book" \
+  --response-format b64_json \
+  --artifact-dir .codex-xai-artifacts
+```
+
+## Options
+
+- `prompt`: required image prompt.
+- `model`: defaults to `grok-imagine-image`.
+- `n`: number of images.
+- `resolution`: `1k` or `2k`.
+- `response_format`: `url` or `b64_json`.
+- `size`: provider-specific size string.
+- `artifact_dir`: local directory for saved image artifacts.
+
+When `artifact_dir` is present, return the upstream JSON plus `artifacts`. Saved artifacts include `path`, `mime_type`, `source`, and `status`. If a remote URL cannot be downloaded, preserve its upstream `url` with `status: remote`.
+
+## Credential Safety
+
+Use existing credentials. If credentials are missing, ask the user to run:
+
+```bash
+codex-xai-oauth login --device
+```
+
+or set `XAI_API_KEY`. Never print or expose OAuth tokens or API keys.

package/skills/xai-login-instructions/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: xai_login_instructions
+description: Use when the user asks how to log in, authenticate, configure OAuth, set up XAI_API_KEY, or fix missing xAI/Grok credentials for codex-xai-oauth.
+---
+
+# xAI Login Instructions
+
+Use `xai_login_instructions` when the user needs setup commands or auth-file paths.
+
+Default OAuth login writes a shared xAI OIDC entry to `~/.grok/auth.json`. This is a shared auth store, not a requirement to use a specific Grok CLI build.
+
+For browser login:
+
+```bash
+codex-xai-oauth login
+```
+
+For OAuth device login:
+
+```bash
+codex-xai-oauth login --device
+```
+
+For API-key fallback:
+
+```bash
+export XAI_API_KEY=xai-...
+```
+
+Credential safety:
+
+- Do not expose token material.
+- Prefer `~/.grok/auth.json` unless `CODEX_XAI_OAUTH_AUTH_FILE` is explicitly set.
+- Treat `~/.config/codex-xai-oauth/auth.json` as a legacy fallback.
+- Mention `XAI_API_KEY` only as an environment variable name, never as a value.

package/skills/xai-status/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: xai_status
+description: Use when the user asks to check xAI, Grok, codex-xai-oauth, OAuth, API-key, or credential status without exposing secrets.
+---
+
+# xAI Status
+
+Use `xai_status` to check whether xAI credentials are available.
+
+Return a concise status summary. Never print, quote, or expose OAuth tokens, refresh tokens, bearer tokens, or API keys.
+
+CLI equivalent:
+
+```bash
+codex-xai-oauth status
+```

package/skills/xai-tts/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: xai_tts
+description: Use when the user asks to generate speech, text-to-speech, audio narration, voice output, or TTS with xAI/Grok through xai_tts.
+---
+
+# xAI TTS
+
+Use `xai_tts` to generate speech audio.
+
+Preferred MCP call:
+
+```json
+{
+  "input": "Hello from Grok.",
+  "voice_id": "eve",
+  "language": "auto",
+  "codec": "mp3"
+}
+```
+
+Options:
+
+- `input`: required text to speak.
+- `voice_id`: optional voice, default `eve`.
+- `language`: optional language, default `auto`.
+- `codec`: optional output codec.
+
+Return the content type and explain that the audio bytes are returned as base64 in the tool output.

package/skills/xai-video-generate/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: xai_video_generate
+description: Use when the user asks to generate video, Grok Imagine video, text-to-video, image-to-video, or xAI video through xai_video_generate.
+---
+
+# xAI Video Generate
+
+Use `xai_video_generate` for Grok Imagine video generation.
+
+Preferred text-to-video MCP call:
+
+```json
+{
+  "prompt": "A serene mountain lake at sunrise with slow camera pan, cinematic lighting"
+}
+```
+
+Image-to-video MCP call:
+
+```json
+{
+  "prompt": "Animate this image with a slow camera push-in",
+  "image_url": "https://example.com/start-frame.jpg"
+}
+```
+
+Reference-image MCP call:
+
+```json
+{
+  "prompt": "Create a short cinematic shot using these reference images for style consistency",
+  "reference_image_urls": [
+    "https://example.com/reference-1.jpg",
+    "https://example.com/reference-2.jpg"
+  ]
+}
+```
+
+Options:
+
+- `prompt`: required video prompt.
+- `image_url`: optional starting image for image-to-video.
+- `reference_image_urls`: optional array of up to 7 reference images.

package/skills/xai-web-search/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: xai_web_search
+description: Use when the user asks xAI/Grok to search the web, find current information, answer with citations, or use server-side web_search.
+---
+
+# xAI Web Search
+
+Use `xai_web_search` for web-backed answers through xAI Responses server-side `web_search`.
+
+Preferred MCP call:
+
+```json
+{
+  "prompt": "Find the latest xAI model announcement and summarize it with citations."
+}
+```
+
+Options:
+
+- `prompt`: required search question.
+- `model`: optional Grok model.
+
+Return a concise answer and include citations from the tool output when available.

package/skills/xai-x-search/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: xai_x_search
+description: Use when the user asks to search X, Twitter, posts, handles, or tweets through xAI/Grok server-side x_search.
+---
+
+# xAI X Search
+
+Use `xai_x_search` for X/Twitter search through xAI Responses server-side `x_search`.
+
+Preferred MCP call:
+
+```json
+{
+  "prompt": "Summarize recent posts from @xai",
+  "allowed_x_handles": ["xai"]
+}
+```
+
+Options:
+
+- `prompt`: required X search request.
+- `allowed_x_handles`: optional handles to include.
+- `excluded_x_handles`: optional handles to exclude.
+
+Do not pass both `allowed_x_handles` and `excluded_x_handles` in the same call.