geo-ai-search-optimization 1.2.4 → 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
 
@@ -261,6 +278,24 @@ geo-ai-search-optimization html-pack https://example.com --out-dir ./exports/exa
 - `agent.html`
 - `share.html`
 
+## Publish Pack 命令
+
+如果你希望直接生成一份“最终可交付包”，同时给人和 agent 使用，现在可以用 `publish-pack`：
+
+```bash
+geo-ai-search-optimization publish-pack ./your-site --out-dir ./exports/your-site-publish-pack
+geo-ai-search-optimization publish-pack https://example.com --out-dir ./exports/example-publish-pack
+```
+
+`publish-pack` 会一次生成：
+
+- `site/`: 可浏览的静态 HTML 页面
+- `documents/`: 给 PM、工程、管理层直接转发的 Markdown 文档
+- `data/`: 给 agent 或自动化流程使用的 JSON 工件
+- `START-HERE.md`: 给人的起始说明
+- `AGENT-START.md`: 给 agent 的执行入口
+- `manifest.json`: 机器可读总索引
+
 ## Fix Plan 命令
 
 如果你已经跑过 `audit`、`report` 或 `onboard-url`，下一步就可以直接把结果转成 PM 待办清单：
@@ -400,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
@@ -418,6 +454,7 @@ geo-ai-search-optimization handoff-bundle ./my-site
 geo-ai-search-optimization share-pack ./my-site
 geo-ai-search-optimization export-pack ./my-site --out-dir ./exports/my-site-pack
 geo-ai-search-optimization html-pack ./my-site --out-dir ./exports/my-site-html
+geo-ai-search-optimization publish-pack ./my-site --out-dir ./exports/my-site-publish-pack
 geo-ai-search-optimization exec-summary ./my-site
 geo-ai-search-optimization fix-plan ./my-site
 geo-ai-search-optimization owner-board ./my-site
@@ -433,6 +470,20 @@ 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`
+- 一次生成最终可交付目录，而不是手动拼 HTML、Markdown、JSON
+- 增加 `START-HERE.md`、`AGENT-START.md`、`manifest.json`
+- 新增 `geo-ai-search-optimization-publish-pack` skill，帮助 agent 直接接手最终交付包
+
 ## New in 1.2.4
 
 - 新增 `html-pack`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.2.4",
+  "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-publish-pack/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: geo-ai-search-optimization-publish-pack
+description: Generate a final GEO delivery package that combines HTML pages, markdown documents, JSON artifacts, and agent start files. Use when a PM or agent wants one folder that can be shared directly with humans and handed off directly to another agent.
+---
+
+# GEO Publish Pack
+
+Use this skill when the user wants a single final package instead of separate GEO artifacts.
+
+`GEO = Generative Engine Optimization`
+
+## What it generates
+
+- `site/` for browsable HTML pages
+- `documents/` for markdown files that can be sent to PM, engineering, or management
+- `data/` for machine-readable JSON artifacts
+- `START-HERE.md` for people
+- `AGENT-START.md` for the next agent
+- `manifest.json` for automation and indexing
+
+## Best use
+
+- generate one delivery folder at the end of an analysis round
+- share `site/index.html` for quick browsing
+- point the next agent to `AGENT-START.md`
+- use `manifest.json` when another tool needs to ingest the package

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Publish Pack"
+  short_description: "Build a final delivery folder for humans and agents"
+  default_prompt: "Use $geo-ai-search-optimization-publish-pack to generate a final GEO delivery package with HTML, markdown, JSON, and an agent handoff entrypoint."

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

@@ -22,6 +22,7 @@ import { renderHtmlPackMarkdown, writeHtmlPack } from "./html-pack.js";
 import { createOwnerBoard, renderOwnerBoardMarkdown, writeOwnerBoardOutput } from "./owner-board.js";
 import { createMeetingPack, renderMeetingPackMarkdown, writeMeetingPackOutput } from "./meeting-pack.js";
 import { createPmBrief, renderPmBriefMarkdown, writePmBriefOutput } from "./pm-brief.js";
+import { renderPublishPackMarkdown, writePublishPack } from "./publish-pack.js";
 import { generateReport, writeReportOutput } from "./report.js";
 import { createRoadmap, renderRoadmapMarkdown, writeRoadmapOutput } from "./roadmap.js";
 import {
@@ -32,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;
@@ -55,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>]",
@@ -70,6 +73,7 @@ function printHelp() {
       "  geo-ai-search-optimization share-pack <input> [--task <id>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization export-pack <input> [--task <id>] [--format <markdown|json>] [--out-dir <dir>]",
       "  geo-ai-search-optimization html-pack <input> [--task <id>] [--out-dir <dir>]",
+      "  geo-ai-search-optimization publish-pack <input> [--task <id>] [--out-dir <dir>]",
       "  geo-ai-search-optimization exec-summary <input> [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization fix-plan <input> [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization owner-board <input> [--format <markdown|json>] [--out <file>]",
@@ -134,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")) {
@@ -506,6 +520,20 @@ async function handleHtmlPack(args) {
   process.stdout.write(renderHtmlPackMarkdown(pack));
 }
 
+async function handlePublishPack(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("publish-pack 需要一个输入值，可以是项目路径、网站网址或已导出的 JSON 工件");
+  }
+
+  const pack = await writePublishPack(input, {
+    taskId: getFlagValue(args, "--task"),
+    outputDir: getFlagValue(args, "--out-dir")
+  });
+
+  process.stdout.write(renderPublishPackMarkdown(pack));
+}
+
 async function handleExecSummary(args) {
   const input = args.find((value) => !value.startsWith("-"));
   if (!input) {
@@ -639,6 +667,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "skills") {
+    await handleSkills(rest);
+    return;
+  }
+
   if (command === "where") {
     handleWhere();
     return;
@@ -714,6 +747,11 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "publish-pack") {
+    await handlePublishPack(rest);
+    return;
+  }
+
   if (command === "exec-summary") {
     await handleExecSummary(rest);
     return;

package/src/index.js

@@ -20,10 +20,12 @@ export { createExportPack, renderExportPackMarkdown, writeExportPack } from "./e
 export { createMeetingPack, renderMeetingPackMarkdown, writeMeetingPackOutput } from "./meeting-pack.js";
 export { createOwnerBoard, renderOwnerBoardMarkdown, writeOwnerBoardOutput } from "./owner-board.js";
 export { createPmBrief, renderPmBriefMarkdown, writePmBriefOutput } from "./pm-brief.js";
+export { renderPublishPackMarkdown, writePublishPack } from "./publish-pack.js";
 export { createQuickStartPlan, renderQuickStartMarkdown, writeQuickStartOutput } from "./quick-start.js";
 export { generateReport, writeReportOutput } from "./report.js";
 export { createRoadmap, renderRoadmapMarkdown, writeRoadmapOutput } from "./roadmap.js";
 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/publish-pack.js

@@ -0,0 +1,420 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createExecSummary, renderExecSummaryMarkdown } from "./exec-summary.js";
+import { createHandoffBundle, renderHandoffBundleMarkdown } from "./handoff-bundle.js";
+import { createOwnerBoard, renderOwnerBoardMarkdown } from "./owner-board.js";
+import { createPmBrief, renderPmBriefMarkdown } from "./pm-brief.js";
+import { createSharePack, renderSharePackMarkdown } from "./share-pack.js";
+
+function sanitizeSegment(value) {
+  return String(value)
+    .replace(/[^a-z0-9-_]+/gi, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+function buildBaseName(sourceType, source) {
+  if (sourceType === "url") {
+    try {
+      const hostname = new URL(source).hostname || "website";
+      return sanitizeSegment(hostname) || "website";
+    } catch {
+      return "website";
+    }
+  }
+
+  return sanitizeSegment(path.basename(source)) || "site";
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function wrapHtml(title, body) {
+  return [
+    "<!doctype html>",
+    '<html lang="zh-Hant">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<title>${escapeHtml(title)}</title>`,
+    "<style>",
+    "body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;margin:0;background:#f5f7fb;color:#16324f;}",
+    ".shell{max-width:1100px;margin:0 auto;padding:32px 20px 64px;}",
+    ".hero,.card{background:#fff;border:1px solid #d9e2ec;border-radius:16px;box-shadow:0 8px 24px rgba(15,23,42,.06);}",
+    ".hero{padding:28px;margin-bottom:24px;}",
+    ".grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:16px;}",
+    ".card{padding:20px;}",
+    "h1,h2,h3{margin-top:0;color:#102a43;}",
+    "ul{padding-left:20px;line-height:1.7;}",
+    "a{color:#0b7285;text-decoration:none;}",
+    "code,pre{background:#f4f7fb;border-radius:10px;}",
+    "pre{padding:16px;white-space:pre-wrap;overflow:auto;}",
+    ".meta{display:flex;gap:12px;flex-wrap:wrap;color:#486581;}",
+    "</style>",
+    "</head>",
+    "<body>",
+    body,
+    "</body>",
+    "</html>"
+  ].join("");
+}
+
+function buildDocumentHtml(title, content) {
+  return wrapHtml(
+    title,
+    `
+    <main class="shell">
+      <section class="hero">
+        <h1>${escapeHtml(title)}</h1>
+      </section>
+      <section class="card">
+        <pre>${escapeHtml(content)}</pre>
+      </section>
+    </main>
+    `
+  );
+}
+
+function buildIndexHtml(pack) {
+  const cards = pack.htmlFiles
+    .map(
+      (file) => `
+      <article class="card">
+        <h3>${escapeHtml(file.label)}</h3>
+        <p>${escapeHtml(file.description)}</p>
+        <a href="./${escapeHtml(file.filename)}">打开 ${escapeHtml(file.filename)}</a>
+      </article>
+    `
+    )
+    .join("");
+
+  return wrapHtml(
+    "GEO Publish Pack",
+    `
+    <main class="shell">
+      <section class="hero">
+        <h1>GEO Publish Pack</h1>
+        <div class="meta">
+          <span>来源：${escapeHtml(pack.source)}</span>
+          <span>类型：${escapeHtml(pack.sourceType)}</span>
+          <span>目录：${escapeHtml(pack.outputDir)}</span>
+        </div>
+        <p>这是一个适合直接交付、分发与交接的 GEO 最终发布包，覆盖 PM、工程、管理层与下一位 agent。</p>
+      </section>
+      <section class="grid">
+        ${cards}
+      </section>
+    </main>
+    `
+  );
+}
+
+function buildStartHereContent(pack) {
+  return [
+    "# GEO Publish Pack",
+    "",
+    `- 输入来源：\`${pack.source}\``,
+    `- 来源类型：\`${pack.sourceType}\``,
+    `- 生成时间：${pack.generatedAt}`,
+    "",
+    "## 这份包怎么用",
+    "",
+    "1. 人先打开 `site/index.html` 看总览。",
+    "2. PM 看 `documents/pm-brief.md` 或 `site/pm.html`。",
+    "3. 工程 / 执行团队看 `documents/owner-board.md` 或 `site/engineering.html`。",
+    "4. 管理层看 `documents/exec-summary.md` 或 `site/exec.html`。",
+    "5. 下一位 agent 从 `AGENT-START.md` 和 `data/agent-handoff-bundle.json` 开始。",
+    "",
+    "## 目录结构",
+    "",
+    "- `site/`: 可浏览的静态 HTML 页面。",
+    "- `documents/`: 可直接分享的 Markdown 文档。",
+    "- `data/`: 给 agent 或自动化流程使用的 JSON 工件。",
+    "- `START-HERE.md`: 给人看的起始说明。",
+    "- `AGENT-START.md`: 给 agent 的执行入口。",
+    "- `manifest.json`: 机器可读的总索引。",
+    "",
+    "## 快速入口",
+    "",
+    `- 总览页：\`${pack.quickLinks.indexHtml}\``,
+    `- PM：\`${pack.quickLinks.pmDocument}\``,
+    `- 工程：\`${pack.quickLinks.engineeringDocument}\``,
+    `- 管理层：\`${pack.quickLinks.execDocument}\``,
+    `- Agent：\`${pack.quickLinks.agentData}\``,
+    "",
+    "## 推荐分发顺序",
+    ""
+  ].concat(pack.sharePack.audienceOrder.map((item) => `- ${item}`)).join("\n") + "\n";
+}
+
+function buildAgentStartContent(pack) {
+  const firstPacket = pack.handoffBundle.applyPlan.packets[0];
+  const firstValidation = firstPacket?.validationCommands ?? [];
+  const nextRoundTasks = pack.handoffBundle.completionReport.nextRoundTasks.slice(0, 3);
+
+  const lines = [
+    "# AGENT START",
+    "",
+    "你现在接手这份 GEO 发布包。",
+    "",
+    `- 输入来源：\`${pack.source}\``,
+    `- 来源类型：\`${pack.sourceType}\``,
+    `- 执行模式：\`${pack.handoffBundle.summary.executionMode}\``,
+    `- 执行类型：\`${pack.handoffBundle.summary.executionType}\``,
+    "",
+    "## 先读什么",
+    "",
+    "1. `data/agent-handoff-bundle.json`",
+    "2. `documents/share-pack.md`",
+    "3. `documents/owner-board.md`",
+    "4. `documents/pm-brief.md`",
+    "",
+    "## 你现在该做什么",
+    ""
+  ];
+
+  if (firstPacket) {
+    lines.push(`- 先从任务包 \`${firstPacket.id}\` 开始：${firstPacket.title}`);
+    lines.push(`- 负责人建议：${firstPacket.owner}`);
+  } else {
+    lines.push("- 当前没有具体任务包，请先根据 share-pack 和 owner-board 重新确认优先级。");
+  }
+
+  if (pack.handoffBundle.summary.executionMode === "implementation-ready") {
+    lines.push("- 当前已有本地项目上下文，可以直接检查模板、metadata、schema 或内容文件并实施修复。");
+  } else if (pack.handoffBundle.summary.executionMode === "advice-only") {
+    lines.push("- 当前更适合先给结构化建议，不要假设你已经拥有代码仓库写入权限。");
+    lines.push("- 如果用户能提供仓库或 CMS 上下文，请在拿到后重新生成 publish-pack，再进入直接执行。");
+  } else {
+    lines.push("- 当前输入主要来自已有工件，先根据工件整理修复顺序，再等待更多上下文。");
+  }
+
+  lines.push("", "## 建议先跑的验证命令", "");
+
+  for (const command of firstValidation) {
+    lines.push(`- \`${command}\``);
+  }
+
+  if (firstValidation.length === 0) {
+    lines.push("- 当前没有额外验证命令，先检查 handoff bundle 中的任务描述。");
+  }
+
+  lines.push("", "## 下一轮任务", "");
+
+  for (const task of nextRoundTasks) {
+    lines.push(`- ${task.id}｜${task.title}｜${task.nextAction}`);
+  }
+
+  if (nextRoundTasks.length === 0) {
+    lines.push("- 暂无下一轮任务，先根据当前工件确认缺口。");
+  }
+
+  lines.push(
+    "",
+    "## 完成后怎么回报",
+    "",
+    "- 完成后更新 completion-report 风格的总结。",
+    "- 说明你检查了哪些文件、修改了什么、如何验证、还剩什么风险。",
+    "- 如果无法直接修复，要明确说明缺少哪些上下文或权限。"
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
+function buildManifest(pack) {
+  return {
+    kind: "geo-publish-pack",
+    generatedAt: pack.generatedAt,
+    source: pack.source,
+    sourceType: pack.sourceType,
+    outputDir: pack.outputDir,
+    directories: {
+      site: pack.siteDir,
+      documents: pack.documentsDir,
+      data: pack.dataDir
+    },
+    quickLinks: pack.quickLinks,
+    shareAudienceOrder: pack.sharePack.audienceOrder,
+    executionMode: pack.handoffBundle.summary.executionMode,
+    executionType: pack.handoffBundle.summary.executionType
+  };
+}
+
+export async function writePublishPack(input, options = {}) {
+  const [sharePack, pmBrief, ownerBoard, execSummary, handoffBundle] = await Promise.all([
+    createSharePack(input, { format: "json", taskId: options.taskId }),
+    createPmBrief(input, { format: "json" }),
+    createOwnerBoard(input, { format: "json" }),
+    createExecSummary(input, { format: "json" }),
+    createHandoffBundle(input, { format: "json", taskId: options.taskId })
+  ]);
+
+  const baseName = buildBaseName(sharePack.sourceType, sharePack.source);
+  const outputDir = path.resolve(options.outputDir || `./exports/${baseName}-geo-publish-pack`);
+  const documentsDir = path.join(outputDir, "documents");
+  const dataDir = path.join(outputDir, "data");
+  const siteDir = path.join(outputDir, "site");
+
+  await fs.mkdir(documentsDir, { recursive: true });
+  await fs.mkdir(dataDir, { recursive: true });
+  await fs.mkdir(siteDir, { recursive: true });
+
+  const documentFiles = [
+    { key: "share_pack", filename: "share-pack.md", content: renderSharePackMarkdown(sharePack) },
+    { key: "pm", filename: "pm-brief.md", content: renderPmBriefMarkdown(pmBrief) },
+    { key: "engineering", filename: "owner-board.md", content: renderOwnerBoardMarkdown(ownerBoard) },
+    { key: "exec", filename: "exec-summary.md", content: renderExecSummaryMarkdown(execSummary) },
+    { key: "agent", filename: "agent-handoff-bundle.md", content: renderHandoffBundleMarkdown(handoffBundle) }
+  ];
+
+  const dataFiles = [
+    { key: "share_pack", filename: "share-pack.json", content: `${JSON.stringify(sharePack, null, 2)}\n` },
+    { key: "pm", filename: "pm-brief.json", content: `${JSON.stringify(pmBrief, null, 2)}\n` },
+    { key: "engineering", filename: "owner-board.json", content: `${JSON.stringify(ownerBoard, null, 2)}\n` },
+    { key: "exec", filename: "exec-summary.json", content: `${JSON.stringify(execSummary, null, 2)}\n` },
+    { key: "agent", filename: "agent-handoff-bundle.json", content: `${JSON.stringify(handoffBundle, null, 2)}\n` }
+  ];
+
+  const htmlFiles = [
+    {
+      key: "index",
+      label: "总览页",
+      description: "适合直接打开给团队看的入口。",
+      filename: "index.html",
+      content: ""
+    },
+    {
+      key: "pm",
+      label: "PM Brief",
+      description: "给 PM 的优先级和推进摘要。",
+      filename: "pm.html",
+      content: documentFiles.find((file) => file.key === "pm")?.content || ""
+    },
+    {
+      key: "engineering",
+      label: "Owner Board",
+      description: "给工程与执行团队的任务视图。",
+      filename: "engineering.html",
+      content: documentFiles.find((file) => file.key === "engineering")?.content || ""
+    },
+    {
+      key: "exec",
+      label: "Exec Summary",
+      description: "给管理层的高层摘要。",
+      filename: "exec.html",
+      content: documentFiles.find((file) => file.key === "exec")?.content || ""
+    },
+    {
+      key: "agent",
+      label: "Agent Bundle",
+      description: "给下一位 agent 的交接入口。",
+      filename: "agent.html",
+      content: documentFiles.find((file) => file.key === "agent")?.content || ""
+    },
+    {
+      key: "share",
+      label: "Share Pack",
+      description: "给协调者的总览文档。",
+      filename: "share.html",
+      content: documentFiles.find((file) => file.key === "share_pack")?.content || ""
+    }
+  ];
+
+  const generatedAt = new Date().toISOString();
+  const quickLinks = {
+    startHere: "START-HERE.md",
+    agentStart: "AGENT-START.md",
+    manifest: "manifest.json",
+    indexHtml: "site/index.html",
+    pmDocument: "documents/pm-brief.md",
+    engineeringDocument: "documents/owner-board.md",
+    execDocument: "documents/exec-summary.md",
+    agentData: "data/agent-handoff-bundle.json"
+  };
+
+  const pack = {
+    kind: "geo-publish-pack",
+    generatedAt,
+    source: sharePack.source,
+    sourceType: sharePack.sourceType,
+    outputDir,
+    documentsDir,
+    dataDir,
+    siteDir,
+    quickLinks,
+    sharePack,
+    handoffBundle,
+    htmlFiles
+  };
+
+  await Promise.all(
+    documentFiles.map((file) => fs.writeFile(path.join(documentsDir, file.filename), file.content, "utf8"))
+  );
+  await Promise.all(dataFiles.map((file) => fs.writeFile(path.join(dataDir, file.filename), file.content, "utf8")));
+
+  const indexHtml = buildIndexHtml(pack);
+  await fs.writeFile(path.join(siteDir, "index.html"), indexHtml, "utf8");
+
+  for (const file of htmlFiles.filter((file) => file.key !== "index")) {
+    await fs.writeFile(path.join(siteDir, file.filename), buildDocumentHtml(file.label, file.content), "utf8");
+  }
+
+  await fs.writeFile(path.join(outputDir, "START-HERE.md"), buildStartHereContent(pack), "utf8");
+  await fs.writeFile(path.join(outputDir, "AGENT-START.md"), buildAgentStartContent(pack), "utf8");
+
+  const manifest = buildManifest(pack);
+  await fs.writeFile(path.join(outputDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+  return {
+    ...manifest,
+    files: {
+      root: [
+        path.join(outputDir, "START-HERE.md"),
+        path.join(outputDir, "AGENT-START.md"),
+        path.join(outputDir, "manifest.json")
+      ],
+      documents: documentFiles.map((file) => path.join(documentsDir, file.filename)),
+      data: dataFiles.map((file) => path.join(dataDir, file.filename)),
+      site: htmlFiles.map((file) => path.join(siteDir, file.filename))
+    }
+  };
+}
+
+export function renderPublishPackMarkdown(pack) {
+  const lines = [
+    "# GEO Publish Pack",
+    "",
+    `- 输入来源：\`${pack.source}\``,
+    `- 来源类型：\`${pack.sourceType}\``,
+    `- 输出目录：\`${pack.outputDir}\``,
+    `- 生成时间：${pack.generatedAt}`,
+    "",
+    "## 快速入口",
+    "",
+    `- 人类入口：\`${path.join(pack.outputDir, pack.quickLinks.startHere)}\``,
+    `- Agent 入口：\`${path.join(pack.outputDir, pack.quickLinks.agentStart)}\``,
+    `- 静态页面：\`${path.join(pack.outputDir, pack.quickLinks.indexHtml)}\``,
+    `- 机器索引：\`${path.join(pack.outputDir, pack.quickLinks.manifest)}\``,
+    "",
+    "## 目录",
+    "",
+    `- 文档：\`${pack.directories.documents}\``,
+    `- 数据：\`${pack.directories.data}\``,
+    `- 页面：\`${pack.directories.site}\``,
+    "",
+    "## 适合怎么用",
+    ""
+  ];
+
+  lines.push("- 先把 `site/index.html` 发给需要快速了解现状的人。");
+  lines.push("- 把 `documents/pm-brief.md`、`documents/owner-board.md`、`documents/exec-summary.md` 分别发给不同角色。");
+  lines.push("- 让下一位 agent 从 `AGENT-START.md` 和 `data/agent-handoff-bundle.json` 继续接手。");
+
+  return `${lines.join("\n")}\n`;
+}

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`;
+}