@mkterswingman/5mghost-yonder 0.0.18 → 0.0.20

package/dist/cli/index.d.ts

@@ -5,6 +5,7 @@ export interface UnifiedUpdateDeps {
     getLatestVersion(): Promise<string>;
     installLatestPackage(): Promise<void>;
     updateRuntime(): Promise<import("../runtime/installers.js").RuntimeSummary>;
+    postUpdate?: () => Promise<void>;
 }
 export declare function compareVersions(currentVersion: string, latestVersion: string): number;
 export declare function runUnifiedUpdate(deps: UnifiedUpdateDeps): Promise<{

package/dist/cli/index.js

@@ -24,6 +24,7 @@ Commands:
   setup          Run first-time setup (OAuth + cookies + MCP registration)
   serve          Start the MCP server (stdio transport)
   smoke          Run installer smoke checks
+  install-skills Install the bundled yt-mcp analysis skill into supported AI clients
   setup-cookies  Refresh YouTube cookies using browser login
   runtime        Manage required runtimes
   check          Check auth, runtime, cookies, and connectivity
@@ -58,6 +59,9 @@ export async function runUnifiedUpdate(deps) {
         updated = true;
     }
     const runtime = await deps.updateRuntime();
+    if (deps.postUpdate) {
+        await deps.postUpdate();
+    }
     return {
         package: { currentVersion, latestVersion, updated },
         runtime,
@@ -81,6 +85,11 @@ async function main() {
             await runSmoke(process.argv.slice(3));
             break;
         }
+        case "install-skills": {
+            const { runInstallSkills } = await import("./installSkills.js");
+            await runInstallSkills();
+            break;
+        }
         case "setup-cookies": {
             const { runSetupCookies, parseSetupCookiesArgs } = await import("./setupCookies.js");
             await runSetupCookies({}, parseSetupCookiesArgs(process.argv.slice(3)));
@@ -107,6 +116,7 @@ async function main() {
             console.log("Checking for updates...\n");
             try {
                 const { updateAll } = await import("../runtime/installers.js");
+                const { runInstallSkills } = await import("./installSkills.js");
                 const summary = await runUnifiedUpdate({
                     getCurrentVersion: getVersion,
                     getLatestVersion: async () => execSync("npm view @mkterswingman/5mghost-yonder version", {
@@ -119,6 +129,7 @@ async function main() {
                         });
                     },
                     updateRuntime: updateAll,
+                    postUpdate: runInstallSkills,
                 });
                 if (summary.package.updated) {
                     console.log(`\n✅ Updated package to ${summary.package.latestVersion}`);

package/dist/cli/installSkills.d.ts

@@ -0,0 +1 @@
+export declare function runInstallSkills(): Promise<void>;

package/dist/cli/installSkills.js

@@ -0,0 +1,39 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { buildSkillInstallPlan, installSkillTarget, } from "../utils/skills.js";
+function detectCli(name) {
+    try {
+        execFileSync(name, ["--version"], { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolvePackageRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+export async function runInstallSkills() {
+    const packageRoot = resolvePackageRoot();
+    const availableCliNames = [
+        "claude-internal",
+        "claude",
+        "codex-internal",
+        "codex",
+        "gemini-internal",
+        "gemini",
+    ].filter(detectCli);
+    const plan = buildSkillInstallPlan(packageRoot, {
+        availableCliNames,
+        includeOpenClaw: process.env.YT_MCP_INSTALL_OPENCLAW_SKILL === "1",
+    });
+    if (plan.length === 0) {
+        console.log("[yt-mcp] No supported AI client detected for bundled skill install.");
+        return;
+    }
+    for (const target of plan) {
+        installSkillTarget(target);
+        console.log(`[yt-mcp] Installed bundled skill for ${target.label}: ${target.targetDir}`);
+    }
+}

package/dist/cli/setup.js

@@ -6,6 +6,7 @@ import { runOAuthFlow } from "../auth/oauthFlow.js";
 import { hasSIDCookies } from "../utils/cookies.js";
 import { buildLauncherCommand, writeLauncherFile } from "../utils/launcher.js";
 import { checkAll } from "../runtime/installers.js";
+import { runInstallSkills } from "./installSkills.js";
 import { getOpenClawConfigPath, isOpenClawInstallLikelyInstalled, writeOpenClawConfig, } from "../utils/openClaw.js";
 import { getCodexInternalConfigPath, writeCodexInternalConfig, } from "../utils/codexInternal.js";
 import { MCP_REGISTER_TIMEOUT_MS, classifyRegistrationFailure, } from "../utils/mcpRegistration.js";
@@ -267,6 +268,7 @@ export async function runSetup() {
     console.log("Step 5/5: Registering MCP in AI clients...");
     const launcherCommand = buildLauncherCommand();
     let registered = false;
+    let skillsInstalled = false;
     for (const { bin, label, command } of buildSetupCliCandidates({
         file: launcherCommand.command,
         args: launcherCommand.args,
@@ -299,6 +301,14 @@ export async function runSetup() {
             console.log(`  ⚠️  Codex CLI (internal) auto-register failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    try {
+        process.env.YT_MCP_INSTALL_OPENCLAW_SKILL = isOpenClawInstallLikelyInstalled(detectCli) ? "1" : "0";
+        await runInstallSkills();
+        skillsInstalled = true;
+    }
+    catch (err) {
+        console.log(`  ⚠️  Bundled skill install failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     if (!registered) {
         console.log("  ℹ️  No supported CLI found. Add manually to your AI client:");
     }
@@ -329,6 +339,9 @@ export async function runSetup() {
   }
 `);
     console.log(`  OpenClaw uses ${PATHS.sharedAuthJson} for PAT/JWT, so env.YT_MCP_TOKEN is optional after setup.`);
+    if (skillsInstalled) {
+        console.log("  ✅ Installed bundled yt-mcp analysis skill for detected AI clients");
+    }
     console.log("  Media downloads:");
     console.log("  - `start_download_job` / `poll_download_job` are job-based local tools");
     console.log("  - Batch limit: 5 YouTube videos per job");

package/dist/utils/launcher.js

@@ -26,6 +26,10 @@ const npmCacheDir = ${JSON.stringify(npmCacheDir)};
 const args = process.argv.slice(2);
 const targetArgs = args.length > 0 ? args : ["serve"];
 
+function isSkillInstallerMode(subArgs) {
+  return subArgs[0] === "install-skills";
+}
+
 function isRepairableNpxFailure(stderr) {
   const lower = stderr.toLowerCase();
   return (lower.includes("_npx/") || lower.includes("_npx\\\\"))
@@ -38,6 +42,7 @@ function runNpx(subArgs, captureStdErrOnly = false) {
   return spawnSync(npxBin, ["--yes", packageSpec, ...subArgs], {
     env: { ...process.env, npm_config_cache: npmCacheDir },
     // Why: probe runs before MCP starts; stdout must stay silent or it will corrupt stdio transport.
+    // The skill installer is an explicit one-shot CLI path, so it can inherit stdio safely.
     stdio: captureStdErrOnly ? ["ignore", "ignore", "pipe"] : "inherit",
   });
 }
@@ -70,6 +75,9 @@ function ensurePackageReady() {
 }
 
 ensurePackageReady();
+if (isSkillInstallerMode(targetArgs)) {
+  process.env.YT_MCP_INSTALL_SKILLS = "1";
+}
 const finalRun = runNpx(targetArgs, false);
 process.exit(finalRun.status ?? 0);
 `;

package/dist/utils/openClaw.d.ts

@@ -6,6 +6,7 @@ export interface OpenClawServerConfig {
     env?: Record<string, string>;
 }
 export declare function getOpenClawConfigPath(homeDir?: string): string;
+export declare function getOpenClawSkillsDir(homeDir?: string): string;
 export declare function buildOpenClawServerConfig(launcherCommand: LauncherCommand): OpenClawServerConfig;
 export declare function upsertOpenClawConfigText(currentText: string | null, serverName: string, launcherCommand: LauncherCommand): string;
 export declare function removeOpenClawConfigEntryText(currentText: string | null, serverName: string): {

package/dist/utils/openClaw.js

@@ -4,6 +4,9 @@ import { dirname, join } from "node:path";
 export function getOpenClawConfigPath(homeDir = homedir()) {
     return join(homeDir, ".openclaw", "workspace", "config", "mcporter.json");
 }
+export function getOpenClawSkillsDir(homeDir = homedir()) {
+    return join(homeDir, ".openclaw", "skills");
+}
 export function buildOpenClawServerConfig(launcherCommand) {
     return {
         transport: "stdio",

package/dist/utils/skills.d.ts

@@ -0,0 +1,16 @@
+import type { LauncherCommand } from "./launcher.js";
+export interface SkillInstallTarget {
+    client: string;
+    label: string;
+    sourceDir: string;
+    targetDir: string;
+}
+export interface SkillInstallPlanOptions {
+    homeDir?: string;
+    availableCliNames?: string[];
+    includeOpenClaw?: boolean;
+}
+export declare function getSkillPackageSourcePath(packageRoot: string): string;
+export declare function buildSkillLauncherCommand(launcherPath: string): LauncherCommand;
+export declare function buildSkillInstallPlan(packageRoot: string, options?: SkillInstallPlanOptions): SkillInstallTarget[];
+export declare function installSkillTarget(target: SkillInstallTarget): void;

package/dist/utils/skills.js

@@ -0,0 +1,56 @@
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { getOpenClawSkillsDir } from "./openClaw.js";
+const SKILL_NAME = "use-yt-mcp";
+export function getSkillPackageSourcePath(packageRoot) {
+    return join(packageRoot, "skills", SKILL_NAME);
+}
+export function buildSkillLauncherCommand(launcherPath) {
+    return {
+        command: "node",
+        args: [launcherPath, "install-skills"],
+    };
+}
+export function buildSkillInstallPlan(packageRoot, options = {}) {
+    const homeDir = options.homeDir ?? homedir();
+    const availableCliNames = new Set(options.availableCliNames ?? []);
+    const sourceDir = getSkillPackageSourcePath(packageRoot);
+    const plan = [];
+    const cliTargets = [
+        { client: "claude-internal", label: "Claude Code (internal)", dir: join(homeDir, ".claude-internal", "skills") },
+        { client: "claude", label: "Claude Code", dir: join(homeDir, ".claude", "skills") },
+        { client: "codex-internal", label: "Codex CLI (internal)", dir: join(homeDir, ".codex-internal", "skills") },
+        { client: "codex", label: "Codex CLI / Codex App", dir: join(homeDir, ".codex", "skills") },
+        { client: "gemini-internal", label: "Gemini CLI (internal)", dir: join(homeDir, ".gemini-internal", "skills") },
+        { client: "gemini", label: "Gemini CLI", dir: join(homeDir, ".gemini", "skills") },
+    ];
+    for (const target of cliTargets) {
+        if (!availableCliNames.has(target.client)) {
+            continue;
+        }
+        plan.push({
+            client: target.client,
+            label: target.label,
+            sourceDir,
+            targetDir: join(target.dir, SKILL_NAME),
+        });
+    }
+    if (options.includeOpenClaw) {
+        plan.push({
+            client: "openclaw",
+            label: "OpenClaw",
+            sourceDir,
+            targetDir: join(getOpenClawSkillsDir(homeDir), SKILL_NAME),
+        });
+    }
+    return plan;
+}
+export function installSkillTarget(target) {
+    if (!existsSync(target.sourceDir)) {
+        throw new Error(`Bundled skill not found: ${target.sourceDir}`);
+    }
+    mkdirSync(dirname(target.targetDir), { recursive: true });
+    rmSync(target.targetDir, { recursive: true, force: true });
+    cpSync(target.sourceDir, target.targetDir, { recursive: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-yonder",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Internal MCP client with local data tools and remote API proxy",
   "type": "module",
   "bin": {
@@ -34,6 +34,7 @@
   },
   "files": [
     "dist/",
+    "skills/",
     "scripts/download-ytdlp.mjs",
     "scripts/install.sh",
     "scripts/install.ps1",

package/skills/use-yt-mcp/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: use-yt-mcp
+preamble-tier: 3
+version: 1.2.0
+description: |
+  Use when the user wants YouTube analysis through yt-mcp: channel performance,
+  video stats, subtitles, comments, trending, or batch YouTube data work.
+  Also use when the user pastes YouTube links such as youtube.com/watch,
+  youtube.com/shorts, youtube.com/live, or youtu.be URLs.
+  Keywords: YouTube, 频道, 视频, 字幕, 评论, 均播, 播放量, trending, yt-mcp, youtube.com, youtu.be.
+---
+
+# Use yt-mcp
+
+Focus on YouTube analysis with yt-mcp MCP tools. Answer the analysis question first. Only switch into setup or troubleshooting when the user explicitly asks for it or a tool call fails.
+
+## 0. Hard Constraints
+
+- For YouTube data tasks, always use `mcp__yt-mcp__*` tools first.
+- Do not route YouTube queries to legacy MCPs or legacy setup skills such as `youtube-data`, `mcp_youtube_data`, `use-youtube-data-mcp`, or `Use YouTube Data MCP` when `yt-mcp` can answer.
+- Do not fetch YouTube metrics, subtitles, comments, channel data, or trending data by browsing the web, scraping pages, or using generic web search. Use `yt-mcp` instead.
+- If `yt-mcp` is unavailable or fails, stop and tell the user it needs setup or troubleshooting. Do not silently fall back to old MCPs or ad-hoc web lookup.
+
+## Trigger Hints
+
+- Treat pasted YouTube links as an automatic trigger for this skill, even if the user does not explicitly say "YouTube".
+- Common URL forms: `https://www.youtube.com/watch?v=...`, `https://youtu.be/...`, `https://www.youtube.com/shorts/...`, `https://www.youtube.com/live/...`.
+
+## 1. Intent -> Tool Routing
+
+| User Intent | Tool(s) |
+|---|---|
+| Search videos by keyword | `search_videos` |
+| Get video metrics in bulk | `get_video_stats` |
+| Large video stats job | `start_video_stats_job` -> `poll_video_stats_job` |
+| Get subtitles / transcript | `get_subtitles`, `batch_get_subtitles` |
+| Check subtitle languages | `list_available_subtitles` |
+| Get comments | `get_comments` |
+| Large comments export | `start_comments_job` -> `poll_comments_job` |
+| Get comment replies | `get_comment_replies` |
+| Channel stats | `get_channel_stats` |
+| List channel uploads | `list_channel_uploads` |
+| Trending videos | `get_trending` |
+| Local download | `start_download_job` -> `poll_download_job` |
+
+All tools are prefixed `mcp__yt-mcp__` in actual calls.
+
+## 2. Analysis Rules
+
+- Prefer batch-capable tools when comparing multiple videos or channels.
+- `get_video_stats` accepts up to 1000 items. If the response returns `mode: "file"`, then inline `preview_items` is only a preview sample from a larger dataset and must not be used as the full basis of analysis. Tell the user the complete result is in `output_file` or `download_url`.
+- For large video/comment analyses where completeness matters, prefer async jobs: `start_video_stats_job` -> `poll_video_stats_job`, or `start_comments_job` -> `poll_comments_job`.
+- When using async jobs, poll until status is `completed`, and tell the user if the result is still partial or in progress.
+- Use normalized response fields in analysis: `published_at`, `duration`, `view_count`, `like_count`, `comment_count`, `is_live_replay`.
+- Default channel analysis window to 30 days unless the user specifies another range.
+- Shorts heuristic: parsed ISO 8601 `duration` <= 90 seconds. Live replay: `is_live_replay === true`. Otherwise treat as long-form.
+- Follow the user's language. Use thousand separators like `1,234,567`; avoid `K/M/B` unless the user asks.
+- Do not dump raw JSON unless the user explicitly wants raw output.
+
+## 3. Common Workflows
+
+### Channel Average Views
+
+1. `list_channel_uploads(channel or channel_id, max_results=N)`
+2. For moderate sets, `get_video_stats(videos=[...ids])`; for large sets or when full coverage matters, `start_video_stats_job(videos=[...ids])` then `poll_video_stats_job(job_id)` until completed
+3. Filter by `published_at` within the requested window
+4. Segment into long-form, Shorts, live replay
+5. Report video count, total views, average views, max, min
+
+Default output:
+
+```md
+## {频道名} 均播分析（近 {N} 天）
+
+| 类型 | 视频数 | 总播放 | 均播 | 最高 | 最低 |
+|---|---:|---:|---:|---:|---:|
+| 长视频 | 12 | 1,234,567 | 102,880 | 456,789 | 12,345 |
+| Shorts | 24 | 2,345,678 | 97,736 | 234,567 | 23,456 |
+| 直播回放 | 3 | 345,678 | 115,226 | 200,000 | 45,678 |
+```
+
+### Video Summary
+
+1. `get_subtitles(video, format="csv")`
+2. Build a timestamped summary from the transcript
+3. Output section headers with timestamps, not a single long paragraph
+
+### Comment Analysis
+
+1. For normal analysis, `get_comments(video, max_comments=N, order="relevance")`; for larger exports, `start_comments_job` then `poll_comments_job`
+2. Cluster by sentiment or topic
+3. Quote representative comments and keep like counts when useful
+
+### Channel Stability
+
+1. Fetch uploads and stats
+2. Measure posting frequency, average views, and volatility
+3. Compare recent videos vs earlier videos to judge trend direction
+
+## 4. Output Rules
+
+- Answer the user's actual question first, then show supporting metrics.
+- For comparisons, prefer compact tables over long prose.
+- State assumptions when the time window, sample size, or language is inferred.
+- If data is partial, say so directly.
+
+## 5. Setup Boundary
+
+Only discuss CLI when the user asks to install or troubleshoot yt-mcp, or when a tool call fails because of auth/cookies/runtime.
+
+Useful commands:
+
+- `yt-mcp setup`
+- `yt-mcp setup-cookies`
+- `yt-mcp check`
+
+Do not turn a normal analysis request into a setup checklist.