claude-skills 独立文档站点实战：Astro + Starlight 双格式输出、内部链接图与 llms.txt 可发现性设计-平芜编程栈

claude-skills 独立文档站点实战：Astro + Starlight 双格式输出、内部链接图与 llms.txt 可发现性设计

【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills

本文是 claude-skills 仓库中 docs/ideas/documentation-site.md 技术提案的完整展开：从"全部内容挤在单一 README"的现状出发，论证独立文档站点的必要性，并给出 HTML/Markdown 双格式服务、Skill 内部链接图、llms.txt 与 Astro + Starlight 内容集合的完整落地路径。读完本文，你将掌握如何把一个以 Markdown/YAML 为数据源的多技能仓库，构造成一套同时服务人类读者、搜索引擎与 LLM Agent 的静态文档站。

一、为什么需要独立文档站点：单仓单页的四个瓶颈

claude-skills 的核心资产是skills/目录下的数十个技能（version.json 记录为 67 个技能、9 个工作流命令、371 个参考文件），再加上commands/下的 YAML 命令定义与docs/workflow/下的流程文档。但长期以来，这些内容的唯一出口是 GitHub 仓库页面与一个巨型 README。提案将这种状态的代价归纳为四点：

没有 Google Search Console 访问权——看不到哪些搜索词在带来流量、无法提交 sitemap、无法控制索引行为；
无法控制 meta 标签——页面标题、OpenGraph 结构化数据全部使用 GitHub 的默认值；
一个巨型 README——67 个技能、9 个工作流、356+ 个参考文件被压缩进单一页面；
技能没有独立 URL——单个技能无法被独立链接、分享或索引。

换言之，内容资产已经形成，但缺少"分发层"。独立文档站就是把资产从"仓库内可见"升级为"可检索、可引用、可被搜索引擎与 LLM 结构化消费"。

未做 SEO 已有流量：机会的量化证据

提案给出了 2026 年 1 月的一份两周流量快照，说明在没有投入任何 SEO 的情况下，有机发现已经真实发生：

来源	浏览量	独立访客
Google	5,532	1,026
github.com	2,646	516
t.co（Twitter/X）	570	208
statics.teams.cdn.office.net（Microsoft Teams）	170	37
chatgpt.com	100	22
claude.ai	58	12
com.reddit.frontpage	49	12
bytedance.larkoffice.com（字节跳动内部）	33	6

同一快照中的辅助指标为：197 stars、9.5k 次skills.sh下载、4,560 位独立克隆者、两周 4,008 位独立访客。需要说明的是，以上均为提案撰写时的历史快照数据，Stars 数在站点实现中已被 site/src/components/SocialIcons.astro 改为通过 GitHub API 实时获取。

提案从中提炼出三个关键信号：

企业级采纳——来自 Microsoft Teams 与字节跳动内部 Lark 平台的流量，说明技能在工作场景中被同事间分享；
AI 平台自然发现——ChatGPT 与 Claude.ai 在向用户推荐本仓库，说明 AI 平台已经把仓库当作可检索的知识源；
Google 主导——在零 SEO 优化的情况下 Google 就贡献了 1,026 位独立访客，一旦建立规范页面，增量空间可观。

核心洞察：Skill 链接 = 内部链接图

这是整个提案最有价值的架构判断。skills/*/SKILL.md中已经存在静态的## Related Skills区块（例如 skills/react-expert/SKILL.md 中的related-skills: fullstack-guardian, playwright-expert, test-master）。Issue #69（Skill Metadata Enhancement）计划把这些静态段落形式化为带类型的metadata.*关系（complementary 互补、prerequisite 前置、alternative 替代）。

这套元数据同时服务两类消费者：

Agent 运行时——Claude 通过结构化链接按上下文加载相关技能；
文档站点——同样的关系在技能页之间变成真正的<a href>链接，形成密集的内部链接图。

这正是经典 SEO 与 LLM 检索共同偏好的事物：Google 依赖内部链接结构理解页面关系并传递权重；LLM 做检索时同样会顺着链接结构构建关于项目能力的更丰富上下文。一份 schema，两类消费者——关系数据在 YAML 中写一次，同时生成运行时交叉引用与 HTML 内部链接。Issue #100（交叉引用校验）也因此获得双重用途：既校验 Agent 行为，也校验文档站链接完整性。

二、硬性要求：同一 URL 双格式服务（HTML + Markdown）

提案把"HTML 与 Markdown 双格式"列为必须满足的硬性要求：站点上的每个内容页都必须在同一 URL 下以两种格式提供：

HTML——供人类消费（带样式、可导航、可被搜索引擎索引）；
Markdown——供 Agent 消费（干净、上下文高效、可直接加载）。

格式选择可通过内容协商（Accept: text/markdown）或 URL 约定（如/skills/react-expert.md或?format=md）实现。

为什么 Agent 是一等消费者

文档站不只是给人类看的。当 Agent 需要理解react-expert能做什么时，它应该直接从文档站 URL 获取 markdown，而不是抓取 HTML 再做有损的 HTML→Markdown 转换。双格式服务把整个文档站变成一个Agent 可消费的 API：

llms.txt成为路由文件，为每个技能和命令指向 markdown 端点；
Agent 抓取/skills/react-expert.md，得到与生成 HTML 页完全一致的内容；
技能参考文件在/skills/react-expert/server-components.md提供，Agent 可按需精确加载；
带类型化 inputs/outputs 的工作流命令，以结构化 markdown 出现在/commands/discovery/create.md。

三种实现方案对比

方案	机制	优点	代价
A. 静态 .md 文件协同生成	构建时对每页同时输出`index.html`与`index.md`	简单、无运行时逻辑、适配任何 CDN/静态托管	依赖 URL 约定区分格式
B. 内容协商中间件	服务器检查`Accept`头并返回对应格式	URL 更干净	需要服务器或边缘函数，非纯静态
C. 查询参数	`/skills/react-expert/?format=md`	可在 Cloudflare Pages、Vercel 等静态托管的边缘函数上实现	需要边缘运行时

提案的推荐是Option A（静态协同生成）作为基线：它在任何地方都能工作、零运行时，.md文件本身就是站点构建所依据的源 markdown。如果后续想要更干净的 URL，再在之上叠加方案 B 或 C。

对站点生成器与 llms.txt 的影响

该硬性要求显著收窄了生成器选型范围：生成器（或一个 post-build 脚本）必须能为每个内容页同时写出 HTML 与原始 Markdown，这是构建期关注点，而非运行时关注点。

对llms.txt的影响同样直接——它从静态摘要进化为一个带直接 Markdown URL 的结构化索引：

# Claude Skills > 65 specialized skills for full-stack developers ## Skills - React Expert: React 18+ with Server Components, hooks, state management - NestJS Expert: NestJS modules, controllers, services, TypeORM/Prisma - Python Pro: Python 3.11+ with type safety, async, pytest ... ## Workflows - Discovery Phase: Research, synthesize, and approve requirements - Planning Phase: Analyze codebase and create execution plans ...

每一行都是可 fetch 的 Markdown URL——Agent 读完llms.txt就能在不触碰 HTML 的情况下遍历整个项目。

三、架构设计：Autodoc 类比与内容来源盘点

提案用 Python autodoc 作为类比，证明项目已经具备构建文档站所需的全部"基础设施"——缺的只是消费这些结构的静态站点生成器。

Python autodoc	Claude Skills 对应物
Package	Phase（intake、discovery、planning、execution、retrospective）
Module	Skill 或 Command
Docstring	`SKILL.md`正文 / 命令描述`.md`
类型注解	YAML`inputs`/`outputs`中的类型化字段
`__init__.py`导出	`workflow-manifest.yaml`
交叉引用	`metadata.*`关系、`external_skills`、`depends_on`
模块索引页	技能总览 / 工作流 DAG 可视化
子模块文档	每个技能下的参考文件

静态站点生成器直接消费已有的 YAML 定义与 Markdown 文件——这是少量胶水代码，而非重写。

已存在的内容来源

来源	生成物
`skills/*/SKILL.md`frontmatter	技能索引页、每个技能元数据卡片
`skills/*/SKILL.md`正文	单技能页面
`skills//references/.md`	每个技能下的子页面
`commands//.yaml`	带类型化 inputs/outputs 的命令参考页
`commands/workflow-manifest.yaml`	DAG 可视化、阶段总览页
`docs/workflow/*.md`	阶段与命令描述页
`SKILLS_GUIDE.md`	分类导航、决策树
`README.md`	落地页（简化版）
`CHANGELOG.md`	发布历史页

其中 commands/workflow-manifest.yaml 是值得细看的结构化数据源：它以phases键定义五个阶段（intake → discovery → planning → execution → retrospectives），每个阶段声明depends_on（带strength: required/recommended）、run_once、optional等标记，并列出该阶段下的命令及其 YAML 定义路径；utilities键则登记可按需调用的命令（如common-ground）。这张清单天然就是工作流 DAG 可视化页的数据来源。部分阶段还通过external_skills声明了与技能的关系——例如 discovery 阶段前置依赖feature-forge技能（role: prerequisite），这正是"同一份关系数据供运行时与站点双用"的又一实例。

需要新建的内容

内容	用途
`llms.txt`	面向 LLM 可发现性的结构化项目摘要
落地页	简化的 Hero + 快速上手（而非完整 README）
搜索/筛选 UI	按分类、语言、框架筛选技能
Sitemap	从技能/命令页面自动生成
OpenGraph meta 标签	每个技能独立的社交分享预览

四、站点结构规划

提案给出了一套与仓库目录一一对应的站点路径：

/ ← 落地页（Hero、快速上手、统计） /skills/ ← 技能索引（可按分类筛选） /skills/react-expert/ ← 由 SKILL.md 生成 /skills/react-expert/server-components/ ← 由 references/ 生成 /skills/react-expert/performance/ ← 由 references/ 生成 /commands/ ← 命令索引 /commands/common-ground/ ← 由命令 YAML + 描述 .md 生成 /workflows/ ← 全阶段 DAG 可视化 /workflows/discovery/ ← 阶段总览（来自 docs/workflow/discovery-phase.md） /workflows/discovery/create/ ← 命令详情（来自 YAML + 描述 .md） /guide/ ← 技能指南（来自 SKILLS_GUIDE.md） /guide/decision-trees/ ← 何时用哪个技能 /changelog/ ← 发布历史 /llms.txt ← LLM 可消费的项目摘要

每个技能页应包含：frontmatter 元数据渲染为结构化侧边栏（role、scope、triggers）、技能正文（工作流、约束、输出模板）、来自metadata.*的 Related Skills 内部链接（#69 落地前先用静态段落）、参考文件子导航、"Install this skill" 代码片段。

每个命令页应包含：inputs 表格（来自 YAML 类型定义）、outputs 表格、需求徽章（ticketing、documentation）、阶段上下文（在 DAG 中的位置）、上游/下游命令。读者可在 commands/project/discovery/create.yaml 中看到这种输入输出结构的真实形态。

五、AI 可发现性：llms.txt 与 Markdown 镜像

提案要求在仓库根目录与文档站根目录各放一份llms.txt，内容从以下来源自动生成：

技能名、描述与 triggers（来自 SKILL.md frontmatter）；
工作流阶段与命令摘要（来自 workflow-manifest.yaml）；
项目统计（技能数、参考文件数、框架覆盖）；
安装说明。

这让 Perplexity、ChatGPT 浏览、Claude.ai 网页搜索等 LLM 检索系统无需解析整个站点即可获得结构化索引。

值得强调的是，这部分在当前仓库中已经从提案变成了落地实现。站点预构建脚本 site/scripts/sync-content.mjs 是理解整套机制的核心文件，其职责链条清晰可见：

内容同步（syncCoreDocs/syncGuideDocs/syncWorkflowDocs/syncSkillPages）——将仓库根目录的 README、QUICKSTART.md、SKILLS_GUIDE.md、CHANGELOG.md 等以及docs/workflow/*.md、skills/*/SKILL.md转换为 Starlight 兼容页面写入site/src/content/docs/；
链接重写（rewriteLinks）——通过 linkMap 把文档内部的相对引用统一重写为站点路径（BASE_PATH为/claude-skills），这正是"内部链接图"的构建期实现；
技能元数据渲染（syncSkillPages）——从 frontmatter 抽取domain/role/scope/output-format/triggers/related-skills生成元数据表与 Related Skills 链接块，并把参考表里的references/xxx.md重写为可点击链接；
Markdown 镜像生成（generateMarkdownMirrors）——为每个页面在public/<path>/index.html.md输出一份纯 Markdown，这与提案 Option A"静态 .md 协同生成"完全一致；
llms.txt 生成（generateLlmsTxt）——按 Docs/Guides/技能域分组/Workflows/Optional 顺序输出带index.html.md直链的索引；
llms-full.txt 生成（generateLlmsFullTxt）——把全部页面正文按顺序拼成一个完整文档，供上下文预算充足的场景一次性加载。

同步脚本同时负责清理public/下旧的镜像产物（cleanGeneratedPublicContent），保证每次构建输出确定且自洽。整个过程通过npm run build（site/package.json）触发：先sync再astro build。

六、分阶段实施路线

提案把整体工作拆成六个阶段，并明确标注了阻塞关系。

Phase 1：文档审计

使用技术写作 Agent 完成：盘点全部现有文档（README、SKILLS_GUIDE、CONTRIBUTING、docs/*.md、工作流文档、各技能 SKILL.md）；识别跨 README/SKILLS_GUIDE/单篇文档的冗余；识别缺口（缺失文档、过期段落、断裂交叉引用）；评估语态一致性（是否遵循同一语气、结构、术语）；把内容映射到站点结构（哪篇现有文档对应哪个站点页面）。

Phase 2：内容重构

分离关注点（README 变为指向文档站的短落地页，详细内容移入 docs）；去重（每个主题保持单一事实来源，其余位置仅链接）；标准化结构（每个技能页、命令页遵循同一模板）；补写缺失内容（落地页文案、分类描述、入门指南）；刷新过期内容。

Phase 3：完成 Issue #69——技能元数据增强（阻塞项）

此阶段必须在站点生成器搭建之前完成。原因是 Astro 内容集合的 schema 依赖最终定型的元数据结构——在 #69 落地前建站，等于把 schema 定义两遍（先临时定义，元数据规范落地后再定义一次）。

#69 决定的是数据模型：SKILL.md frontmatter 与metadata.*键各自承载哪些字段；关系类型如何结构化（complementary、prerequisite、alternative）；domain 标签、兼容性信息等新元数据是否放在metadata.*下；Agent 运行时与文档站共同消费的最终 schema。内容集合 schema、内部链接图、每页 meta 标签、llms.txt索引全部从 #69 的输出派生——先把数据模型做对。

可以与 #69 并行推进的事项：Phase 1（审计）与 Phase 2（内容重构）——它们处理文档内容而非 schema；用当前 frontmatter 字段做 Astro + Starlight 概念验证；搭建文档站的仓库结构（Astro 项目脚手架）。

Phase 4：站点生成器选型——Astro + Starlight

在评估 Docusaurus、Hugo、MkDocs Material、VitePress 之后，提案推荐Astro + Starlight：

需求	Astro 的解法
双格式（HTML+MD）	自定义端点可在`/skills/react-expert/index.md`提供原始 markdown，与`/skills/react-expert/`的 HTML 并存——受支持的模式而非 hack
从 YAML/SKILL.md 自动生成	内容集合（Content Collections）：定义与 SKILL.md frontmatter 匹配的 schema，指向`skills/*/SKILL.md`，页面带类型化数据自动生成；命令 YAML 成为第二个集合
开箱即用的 SEO	Lighthouse 100/100；自动 sitemap、meta 标签、OpenGraph；Starlight 增加搜索、导航、TOC
零 JS 交付	默认纯静态 HTML，无 SPA 水合开销，面向从 Google 或 LLM 推荐进入文档的开发者即时加载
社交卡片	现有 scripts/capture-screenshot.js 可适配为每页 OG 图

为何排除其他方案：Docusaurus SEO 默认值最佳，但交付 React SPA（无谓的 JS 负担）且没有原生内容集合概念，双格式需自定义插件；Hugo 是唯一把双格式输出（自定义输出格式）做成一等公民的 SSG，但用 Go 模板从结构化 YAML 自动生成比 Astro 内容集合更依赖手工接线，可作后备；MkDocs Material 有独特的自动社交卡片生成，但双格式与程序化页面生成最弱，且对目录结构过于固执；VitePress 快速干净，但插件生态不如 Astro 成熟且没有内容集合。

生态契合度：项目面向 TypeScript/JavaScript 开发者，Astro 原生使用 TypeScript。现有的 scripts/validate-skills.py 与 scripts/update-docs.py 继续作为 CI 校验存在——站点生成器不替代它们。

内容集合映射（概念版）

// Astro content collection schema（概念示例） // 注意：最终 schema 取决于 #69 元数据增强 skills collection: source: skills/*/SKILL.md schema: name: string ← 来自 frontmatter description: string ← 来自 frontmatter（最长 1024 字符） triggers: string[] ← 来自 frontmatter role: enum ← specialist | expert | architect scope: enum ← implementation | review | design | ... output-format: enum ← code | document | report | ... metadata: ← 来自 #69，结构待定 related: object[] ← 类型化关系（complementary、prerequisite 等） domain: string[] ← 领域标签 ... commands collection: source: commands/**/*.yaml schema: command: string ← phase:action 标识符 phase: string ← intake | discovery | planning | ... inputs: object[] ← 类型化输入定义 outputs: object[] ← 类型化输出定义 requires: string[] ← ticketing | documentation status: enum ← existing | planned | deprecated workflows collection: source: commands/workflow-manifest.yaml schema: phases: object ← 带 depends_on 边的 DAG 定义 utilities: object[] ← 按需命令

你可以拿 skills/react-expert/SKILL.md 的 frontmatter 逐字段对照：name、description、metadata.domain、metadata.triggers、metadata.role、metadata.scope、metadata.output-format、metadata.related-skills全部在概念 schema 中有所对应。

Phase 5：构建与部署

从定稿的 #69 元数据规范定义 Astro 内容集合 schema；
构建技能、命令、工作流的页面模板；
实现双格式端点（每页 HTML + markdown）；
构建时从内容集合生成llms.txt；
部署到 GitHub Pages 并使用自定义域名；
向 Google Search Console 提交 sitemap；
在站点与仓库 README 中添加赞助徽章；
配置 GitHub Actions，push 到 main 时自动部署。

Phase 6：持续维护

CI 校验：每个技能/命令都有对应文档页；
CI 校验：内部链接有效性（延伸 #100 交叉引用校验）；
发布时自动重新生成llms.txt；
内容变更时自动重新生成 sitemap；
内容集合 schema 校验在构建期拦截损坏的 frontmatter。

依赖链

#69 Skill Metadata Enhancement ├── 文档站内容集合 schema（没有 #69 无法定稿） ├── #65 跨领域推荐（内容工作，依赖 #69） ├── #66 增强路由逻辑（更好的描述 = 更好的页面标题） └── 内部链接图（关系元数据 → <a href> 链接） #100 交叉引用校验 └── 文档站链接校验（同一检查，双重用途） #68 技能依赖映射 └── 文档站 DAG 可视化页 Phase 1（审计）──────────────────── 现在即可开始 Phase 2（内容重构）──────────────── 现在即可开始 Phase 3（#69 元数据）───────────── 阻塞站点 schema Phase 4（Astro 搭建）───────────── 在 #69 之后 Phase 5（构建部署）─────────────── 在 Phase 4 之后 Phase 6（维护）────────────────── Phase 5 之后持续进行

七、提案在仓库中的落地进展：从图纸到代码

docs/ideas/documentation-site.md是一份"想法文档"，而仓库的site/目录已经把它推进到了可运行状态——这是本文能给出的最有说服力的验证。以下是逐项对照：

生成器选型已定且已配置。site/astro.config.mjs 实际采用 Astro + Starlight：site指向https://jeffallan.github.io、base为/claude-skills；通过head数组注入了 Google 站点验证 meta、GA4 统计脚本、指向/claude-skills/llms.txt的rel="alternate"声明（恰好落实了"Agent 是一等消费者"的硬性要求），并通过内联脚本集成 mermaid 用于 DAG 渲染。侧边栏按语言、后端框架、前端与移动端、基础设施与云、API 与架构、质量与测试、DevOps、安全、数据与 ML 等 12 个分类自动生成技能条目，与提案中的"按分类筛选"目标一致。

内容集合已建立。site/src/content.config.ts 使用 Starlight 的docsLoader与docsSchema注册 docs 集合——虽然当前还依赖 Starlight 默认 schema（而非 #69 定稿的自定义 schema），但集合机制本身已就位，印证了提案 Phase 4 的技术路径可行。

双格式服务已实现。前面分析的 generateMarkdownMirrors 正是提案 Option A（静态 .md 协同生成）的工程实现：每个页面对应一份index.html.md。同时 Header.astro 在导航栏渲染了一个"View as Markdown"入口，动态拼出当前页的镜像 URL——人类读者与 Agent 读者都能一键拿到源 Markdown。

llms.txt 已落地。同步脚本每次构建都会从页面清单重新生成 site 的llms.txt与llms-full.txt（全量拼接版），并把统计数字取自 version.json（67 技能 / 9 工作流 / 371 参考文件），与 astro.config.mjs 中<link rel="alternate" ... href="/claude-skills/llms.txt">的声明形成闭环。

社交分享能力已预置。仓库根目录的 assets/social-preview.html 与 assets/social-preview.png（1280×640 的标准 OG 尺寸）是社交卡片的现成素材，配合 scripts/capture-screenshot.js 即可把提案中"Per-skill social previews"的目标从单张推广图扩展到每技能独立卡片。

搜索与主题能力。Starlight 自带的搜索与 TOC 由 astro.config.mjs 引入，customCss指向 site/src/styles/custom.css；首页 site/src/content/docs/index.mdx 使用 splash 模板呈现 67 Skills / 9 Workflows / 371 References / Progressive Disclosure 四张卡片——它承担的就是提案中"简化版落地页"的角色，而不是完整 README。

CI 校验方面，仓库根目录已有 Makefile 与 scripts/validate-skills.py、scripts/validate-markdown.py 等校验脚本，可为 Phase 6 的"构建期 schema 校验 + 链接校验"提供基础。

八、开放问题与后续决策点

提案在末尾保留了四个开放问题，作为方案落地前需要拍板的决策项：

自定义域名？——docs.claudeskills.dev、skills.jeffallan.dev，还是既有站点的子目录；
版本化文档？——需要维护多个版本的文档，还是只保留最新版；
搜索方案——Starlight 内置搜索，还是 Algolia DocSearch（开源项目免费）；
文档站仓库形态——与主仓库同仓（monorepo，使用/site目录），还是独立仓库。

从前述源码看，当前仓库实际上已经选择了 monorepo 形态（/site目录即为文档站），搜索使用 Starlight 内置能力（config.pagefind），域名/版本化仍待定。这些决策会直接决定部署拓扑与内容治理流程，值得在推进 Phase 4 前明确。

小结

claude-skills 的文档站提案给出了一条"数据资产 → 结构化文档站"的完整链路：以 SKILL.md frontmatter 与命令 YAML 为单一数据源，用 Astro 内容集合消费它们生成技能页、命令页与工作流 DAG 页；用 Option A 静态协同生成实现同一 URL 的 HTML/Markdown 双格式输出；用 #69 关系元数据驱动内部链接图；用llms.txt与 Markdown 镜像把整站变成 Agent 可消费的 API。仓库的site/目录已经证明了这条路线的可行性，其预构建脚本 sync-content.mjs 是理解整套机制的最佳起点。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考