geo-ai-search-optimization 1.2.5 → 1.2.6

package/README.md

@@ -24,6 +24,23 @@ npx geo-ai-search-optimization
 - installs the bundled GEO skills into your Codex skills directory
 - ships a local resource folder with `SKILL.md`, references, and a scanner script
 - provides a CLI for installing, locating, and scanning projects for GEO signals
+- now exposes the bundled skill package directly, so agents can discover which GEO sub-skill to use next
+
+## Skills 命令
+
+如果你想先看这个 npm 包里到底打包了哪些 skills，现在可以直接用：
+
+```bash
+geo-ai-search-optimization skills
+geo-ai-search-optimization skills --json
+```
+
+它会列出：
+
+- 核心 GEO skill
+- usage / onboarding skill
+- agent 执行闭环相关 skills
+- 分享 / 导出 / 最终交付相关 skills
 
 ## Quick Start
 
@@ -418,6 +435,7 @@ geo-ai-search-optimization onboard --url https://example.com --json --out ./repo
 geo-ai-search-optimization
 geo-ai-search-optimization install
 geo-ai-search-optimization install --target ./tmp/custom-skills --json
+geo-ai-search-optimization skills
 geo-ai-search-optimization where
 geo-ai-search-optimization doctor
 geo-ai-search-optimization quick-start
@@ -452,6 +470,13 @@ geo-ai-search-optimization version
 geo-ai-search-optimization help
 ```
 
+## New in 1.2.6
+
+- 新增 `skills` 命令，直接列出整套 GEO 技能包
+- 安装后会额外写入 `.skill-bundle.json`，方便 agent 自动发现技能
+- 为缺失的 skill 补齐 `agents/openai.yaml`
+- 主 skill 新增 `skill-bundle-map` 参考，usage skill 也同步纳入 `publish-pack` 和 `skills`
+
 ## New in 1.2.5
 
 - 新增 `publish-pack`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/resources/geo-ai-search-optimization/SKILL.md

@@ -163,3 +163,4 @@ When the user asks for the latest vendor behavior or policy:
 - `references/quick-start.md`: from-0-to-1 startup sequence for using the CLI and the skill together
 - `references/geo-playbook.md`: content patterns and GEO-first page design heuristics
 - `references/implementation-checklist.md`: technical, content, and measurement checklist
+- `references/skill-bundle-map.md`: bundled GEO sub-skills and when to use each one

package/resources/geo-ai-search-optimization/references/skill-bundle-map.md

@@ -0,0 +1,81 @@
+# GEO Skill Bundle Map
+
+## Table of Contents
+
+- Core skill
+- Usage guide
+- Agent execution loop
+- Delivery chain
+
+## Core skill
+
+### `geo-ai-search-optimization`
+
+Use this first when the task is still about diagnosing or improving GEO readiness itself.
+
+Best for:
+
+- auditing a website or codebase
+- improving answerability, structure, and citation readiness
+- deciding what the highest-impact GEO fixes are
+
+## Usage guide
+
+### `geo-ai-search-optimization-usage`
+
+Use this when the next agent or user does not know which command or skill to use next.
+
+Best for:
+
+- onboarding new users
+- explaining command order
+- translating a GEO request into concrete CLI steps
+
+## Agent execution loop
+
+Use these when the work is moving from analysis into action.
+
+### `geo-ai-search-optimization-agent-handoff`
+
+Turn GEO findings into a package that another agent can continue from.
+
+### `geo-ai-search-optimization-repair-loop`
+
+Continue from `apply-plan` style execution tasks and close the loop on actual fixes.
+
+### `geo-ai-search-optimization-completion-report`
+
+Summarize what finished, what still blocks progress, and what should happen next.
+
+### `geo-ai-search-optimization-handoff-bundle`
+
+Use when one artifact needs to contain handoff, execution, and closeout together.
+
+## Delivery chain
+
+Use these when the output needs to be shared, exported, or handed off to humans and agents.
+
+### `geo-ai-search-optimization-share-pack`
+
+Prepare role-specific views for PM, engineering, management, and the next agent.
+
+### `geo-ai-search-optimization-export-pack`
+
+Generate a disk folder with ready-to-send markdown or JSON deliverables.
+
+### `geo-ai-search-optimization-html-pack`
+
+Generate browsable HTML pages for quick sharing.
+
+### `geo-ai-search-optimization-publish-pack`
+
+Generate the final delivery folder that combines:
+
+- `site/` HTML pages
+- `documents/` markdown files
+- `data/` JSON artifacts
+- `START-HERE.md`
+- `AGENT-START.md`
+- `manifest.json`
+
+This is the best choice when the output should be directly handed to a PM, a stakeholder group, or another agent without further manual packaging.

package/resources/geo-ai-search-optimization-export-pack/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Export Pack"
+  short_description: "Export GEO deliverables into a shareable folder"
+  default_prompt: "Use $geo-ai-search-optimization-export-pack to generate a folder of GEO deliverables for PM, engineering, management, and agent handoff."

package/resources/geo-ai-search-optimization-handoff-bundle/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Handoff Bundle"
+  short_description: "Continue from one bundled GEO execution artifact"
+  default_prompt: "Use $geo-ai-search-optimization-handoff-bundle to continue from this combined GEO handoff, execution, and closeout artifact."

package/resources/geo-ai-search-optimization-html-pack/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO HTML Pack"
+  short_description: "Generate browsable HTML pages from GEO outputs"
+  default_prompt: "Use $geo-ai-search-optimization-html-pack to convert these GEO deliverables into browsable HTML pages for sharing."

package/resources/geo-ai-search-optimization-share-pack/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Share Pack"
+  short_description: "Prepare audience-specific GEO views for sharing"
+  default_prompt: "Use $geo-ai-search-optimization-share-pack to turn this GEO result into role-specific views for PM, engineering, management, and the next agent."

package/resources/geo-ai-search-optimization-usage/SKILL.md

@@ -13,20 +13,21 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as twelve layers:
-
-1. `onboard-url` / `onboard`: first look
-2. `scan`: raw signal check
-3. `audit` / `report`: diagnosis
-4. `fix-plan` / `owner-board`: execution planning
-5. `agent-handoff`: agent takeover package
-6. `apply-plan`: execution loop
-7. `completion-report`: closeout
-8. `handoff-bundle`: all-in-one package
-9. `share-pack`: audience-ready delivery
-10. `export-pack`: folder export
-11. `html-pack`: browsable output
-12. `pm-brief` / `roadmap`: stakeholder alignment
+The package is best explained as thirteen layers:
+
+1. `skills`: inspect the bundled skill package
+2. `onboard-url` / `onboard`: first look
+3. `scan`: raw signal check
+4. `audit` / `report`: diagnosis
+5. `fix-plan` / `owner-board`: execution planning
+6. `agent-handoff`: agent takeover package
+7. `apply-plan`: execution loop
+8. `completion-report`: closeout
+9. `handoff-bundle`: all-in-one package
+10. `share-pack`: audience-ready delivery
+11. `export-pack`: folder export
+12. `html-pack` / `publish-pack`: browsable and final delivery output
+13. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
@@ -51,6 +52,7 @@ npx geo-ai-search-optimization handoff-bundle ./your-site
 npx geo-ai-search-optimization share-pack ./your-site
 npx geo-ai-search-optimization export-pack ./your-site
 npx geo-ai-search-optimization html-pack ./your-site
+npx geo-ai-search-optimization publish-pack ./your-site
 npx geo-ai-search-optimization owner-board ./your-site
 npx geo-ai-search-optimization roadmap ./your-site
 ```
@@ -59,6 +61,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 
 - `onboard-url`: first-time website check from a live URL
 - `onboard`: interactive first-time onboarding
+- `skills`: list the bundled skills and decide which skill or command chain fits the task
 - `scan`: check raw technical signals across files
 - `audit`: get GEO score, issue areas, blockers, and PM action list
 - `report`: export audit/onboarding/scan into readable files
@@ -70,6 +73,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `share-pack`: prepare role-specific shareable outputs for PM, engineering, management, and agents
 - `export-pack`: generate a folder with multiple ready-to-send files
 - `html-pack`: generate static HTML pages for sharing and browsing
+- `publish-pack`: generate the final delivery folder for humans and agents together
 - `owner-board`: group tasks by PM / engineering / SEO / content
 - `pm-brief`: prepare a PM summary for meetings and prioritization
 - `roadmap`: turn tasks into a 2-week / 4-week execution sequence
@@ -88,6 +92,7 @@ When explaining the tool to a user:
 - if the user wants something ready to forward to multiple audiences, move them to `share-pack`
 - if the user wants actual files on disk for each audience, move them to `export-pack`
 - if the user wants browsable HTML pages, move them to `html-pack`
+- if the user wants one final package with HTML, markdown, JSON, and an agent entrypoint, move them to `publish-pack`
 - if the user already has a report, move them to `fix-plan`, `owner-board`, or `roadmap`
 
 Read [references/usage-patterns.md](references/usage-patterns.md) when you need response patterns and command selection examples.

package/src/cli.js

@@ -33,6 +33,7 @@ import {
 import { createQuickStartPlan, renderQuickStartMarkdown, writeQuickStartOutput } from "./quick-start.js";
 import { createSchemaTemplate } from "./schema.js";
 import { createSharePack, renderSharePackMarkdown, writeSharePackOutput } from "./share-pack.js";
+import { listBundledSkills, renderBundledSkillsMarkdown } from "./skills.js";
 import { analyzeWebsiteUrl, renderWebsiteOnboardingMarkdown, writeWebsiteOnboardingOutput } from "./url-onboarding.js";
 
 let cachedVersion;
@@ -56,6 +57,7 @@ function printHelp() {
       "Usage:",
       "  geo-ai-search-optimization",
       "  geo-ai-search-optimization install [--target <dir>] [--json]",
+      "  geo-ai-search-optimization skills [--json]",
       "  geo-ai-search-optimization where",
       "  geo-ai-search-optimization doctor [--json]",
       "  geo-ai-search-optimization quick-start [--json] [--out <file>]",
@@ -136,6 +138,16 @@ function handleWhere() {
   );
 }
 
+async function handleSkills(args) {
+  const bundle = await listBundledSkills();
+  if (hasFlag(args, "--json")) {
+    process.stdout.write(`${JSON.stringify(bundle, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(renderBundledSkillsMarkdown(bundle));
+}
+
 async function handleDoctor(args) {
   const report = await runDoctor();
   if (hasFlag(args, "--json")) {
@@ -655,6 +667,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "skills") {
+    await handleSkills(rest);
+    return;
+  }
+
   if (command === "where") {
     handleWhere();
     return;

package/src/index.js

@@ -27,4 +27,5 @@ export { createRoadmap, renderRoadmapMarkdown, writeRoadmapOutput } from "./road
 export { createSchemaTemplate } from "./schema.js";
 export { scanProject, renderScanMarkdown, writeScanOutput } from "./scan.js";
 export { createSharePack, renderSharePackMarkdown, writeSharePackOutput } from "./share-pack.js";
+export { listBundledSkills, renderBundledSkillsMarkdown } from "./skills.js";
 export { analyzeWebsiteUrl, renderWebsiteOnboardingMarkdown, writeWebsiteOnboardingOutput } from "./url-onboarding.js";

package/src/install-skill.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getBundledSkillPath, getInstalledSkillPath, getSkillName } from "./paths.js";
+import { listBundledSkills } from "./skills.js";
 
 async function pathExists(targetPath) {
   try {
@@ -11,10 +12,18 @@ async function pathExists(targetPath) {
   }
 }
 
+function resolveInstalledSkillPath(skillName, targetDir) {
+  if (skillName === getSkillName()) {
+    return targetDir;
+  }
+  return path.join(path.dirname(targetDir), skillName);
+}
+
 export async function installSkill(options = {}) {
   const sourceDir = getBundledSkillPath();
   const targetDir = options.targetDir || getInstalledSkillPath();
   const silent = Boolean(options.silent);
+  const bundle = await listBundledSkills();
 
   if (!(await pathExists(sourceDir))) {
     throw new Error(`Bundled skill folder not found: ${sourceDir}`);
@@ -48,6 +57,14 @@ export async function installSkill(options = {}) {
   const manifest = {
     skill: getSkillName(),
     installedSkills,
+    installedSkillDetails: bundle.skills
+      .filter((skill) => installedSkills.includes(skill.name))
+      .map((skill) => ({
+        name: skill.name,
+        displayName: skill.displayName,
+        shortDescription: skill.shortDescription,
+        installPath: resolveInstalledSkillPath(skill.name, targetDir)
+      })),
     installedAt: new Date().toISOString(),
     installedFrom: sourceDir,
     packageName: "geo-ai-search-optimization",
@@ -60,6 +77,30 @@ export async function installSkill(options = {}) {
     "utf8"
   );
 
+  const bundleManifestPath = path.join(targetDir, ".skill-bundle.json");
+  await fs.writeFile(
+    bundleManifestPath,
+    `${JSON.stringify(
+      {
+        kind: bundle.kind,
+        totalSkills: bundle.totalSkills,
+        groups: bundle.groups.map((group) => ({
+          category: group.category,
+          label: group.label,
+          skills: group.skills.map((skill) => ({
+            name: skill.name,
+            displayName: skill.displayName,
+            shortDescription: skill.shortDescription,
+            installPath: resolveInstalledSkillPath(skill.name, targetDir)
+          }))
+        }))
+      },
+      null,
+      2
+    )}\n`,
+    "utf8"
+  );
+
   if (!silent) {
     process.stdout.write(`Installed skills (${installedSkills.join(", ")}) to ${path.dirname(targetDir)}\n`);
   }
@@ -69,6 +110,7 @@ export async function installSkill(options = {}) {
     sourceDir,
     skillName: getSkillName(),
     installedSkills,
-    manifest
+    manifest,
+    bundleManifestPath
   };
 }

package/src/skills.js

@@ -0,0 +1,169 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getPackageRoot } from "./paths.js";
+
+const SKILL_ORDER = [
+  "geo-ai-search-optimization",
+  "geo-ai-search-optimization-usage",
+  "geo-ai-search-optimization-agent-handoff",
+  "geo-ai-search-optimization-repair-loop",
+  "geo-ai-search-optimization-completion-report",
+  "geo-ai-search-optimization-handoff-bundle",
+  "geo-ai-search-optimization-share-pack",
+  "geo-ai-search-optimization-export-pack",
+  "geo-ai-search-optimization-html-pack",
+  "geo-ai-search-optimization-publish-pack"
+];
+
+const SKILL_CATEGORY = {
+  "geo-ai-search-optimization": "core",
+  "geo-ai-search-optimization-usage": "guidance",
+  "geo-ai-search-optimization-agent-handoff": "execution",
+  "geo-ai-search-optimization-repair-loop": "execution",
+  "geo-ai-search-optimization-completion-report": "execution",
+  "geo-ai-search-optimization-handoff-bundle": "execution",
+  "geo-ai-search-optimization-share-pack": "delivery",
+  "geo-ai-search-optimization-export-pack": "delivery",
+  "geo-ai-search-optimization-html-pack": "delivery",
+  "geo-ai-search-optimization-publish-pack": "delivery"
+};
+
+const CATEGORY_LABELS = {
+  core: "核心 GEO 能力",
+  guidance: "使用引导",
+  execution: "Agent 执行闭环",
+  delivery: "交付与分享"
+};
+
+function stripQuotes(value) {
+  return String(value).trim().replace(/^['"]|['"]$/g, "");
+}
+
+function parseYamlBlock(raw) {
+  const record = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const separatorIndex = trimmed.indexOf(":");
+    if (separatorIndex === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, separatorIndex).trim();
+    const value = stripQuotes(trimmed.slice(separatorIndex + 1));
+    record[key] = value;
+  }
+  return record;
+}
+
+async function readSkillMetadata(skillDir) {
+  const skillPath = path.join(skillDir, "SKILL.md");
+  const raw = await fs.readFile(skillPath, "utf8");
+  const frontmatterMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+  const frontmatter = frontmatterMatch ? parseYamlBlock(frontmatterMatch[1]) : {};
+  const yamlPath = path.join(skillDir, "agents", "openai.yaml");
+
+  let interfaceMetadata = {};
+  try {
+    const yamlRaw = await fs.readFile(yamlPath, "utf8");
+    const interfaceMatch = yamlRaw.match(/interface:\n([\s\S]*)/);
+    if (interfaceMatch) {
+      interfaceMetadata = parseYamlBlock(interfaceMatch[1]);
+    }
+  } catch {
+    interfaceMetadata = {};
+  }
+
+  const directoryName = path.basename(skillDir);
+  const name = frontmatter.name || directoryName;
+
+  return {
+    name,
+    directoryName,
+    description: frontmatter.description || "",
+    displayName: interfaceMetadata.display_name || name,
+    shortDescription: interfaceMetadata.short_description || frontmatter.description || "",
+    defaultPrompt: interfaceMetadata.default_prompt || "",
+    category: SKILL_CATEGORY[name] || "delivery",
+    skillPath
+  };
+}
+
+function sortSkills(skills) {
+  return [...skills].sort((left, right) => {
+    const leftIndex = SKILL_ORDER.indexOf(left.name);
+    const rightIndex = SKILL_ORDER.indexOf(right.name);
+    if (leftIndex === -1 && rightIndex === -1) {
+      return left.name.localeCompare(right.name);
+    }
+    if (leftIndex === -1) {
+      return 1;
+    }
+    if (rightIndex === -1) {
+      return -1;
+    }
+    return leftIndex - rightIndex;
+  });
+}
+
+export async function listBundledSkills() {
+  const resourcesDir = path.join(getPackageRoot(), "resources");
+  const entries = await fs.readdir(resourcesDir, { withFileTypes: true });
+  const skillDirs = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(resourcesDir, entry.name));
+
+  const skills = [];
+  for (const skillDir of skillDirs) {
+    try {
+      await fs.access(path.join(skillDir, "SKILL.md"));
+    } catch {
+      continue;
+    }
+    skills.push(await readSkillMetadata(skillDir));
+  }
+
+  const ordered = sortSkills(skills);
+  const grouped = Object.entries(CATEGORY_LABELS).map(([category, label]) => ({
+    category,
+    label,
+    skills: ordered.filter((skill) => skill.category === category)
+  }));
+
+  return {
+    kind: "geo-skill-bundle",
+    totalSkills: ordered.length,
+    skills: ordered,
+    groups: grouped.filter((group) => group.skills.length > 0)
+  };
+}
+
+export function renderBundledSkillsMarkdown(bundle) {
+  const lines = [
+    "# GEO Skill Bundle",
+    "",
+    `- 技能数量：\`${bundle.totalSkills}\``,
+    "",
+    "## 推荐理解顺序",
+    "",
+    "- 先看核心 GEO skill。",
+    "- 再看 usage skill，知道什么时候该跑哪个命令。",
+    "- 如果要交给 agent 执行，再进入 handoff / apply / completion 这一条执行链。",
+    "- 如果要产出给团队分发，再进入 share / export / html / publish 这一条交付链。",
+    ""
+  ];
+
+  for (const group of bundle.groups) {
+    lines.push(`## ${group.label}`, "");
+    for (const skill of group.skills) {
+      lines.push(`- ${skill.name}`);
+      lines.push(`  - 显示名：${skill.displayName}`);
+      lines.push(`  - 说明：${skill.shortDescription}`);
+      lines.push(`  - 路径：\`${skill.skillPath}\``);
+    }
+    lines.push("");
+  }
+
+  return `${lines.join("\n")}\n`;
+}