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 的情况下有机发现已经真实发生来源浏览量独立访客Google5,5321,026github.com2,646516t.coTwitter/X570208statics.teams.cdn.office.netMicrosoft Teams17037chatgpt.com10022claude.ai5812com.reddit.frontpage4912bytedance.larkoffice.com字节跳动内部336同一快照中的辅助指标为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 #69Skill 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或?formatmd实现。为什么 Agent 是一等消费者文档站不只是给人类看的。当 Agent 需要理解react-expert能做什么时它应该直接从文档站 URL 获取 markdown而不是抓取 HTML 再做有损的 HTML→Markdown 转换。双格式服务把整个文档站变成一个Agent 可消费的 APIllms.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/?formatmd可在 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 autodocClaude Skills 对应物PackagePhaseintake、discovery、planning、execution、retrospectiveModuleSkill 或 CommandDocstringSKILL.md正文 / 命令描述.md类型注解YAMLinputs/outputs中的类型化字段__init__.py导出workflow-manifest.yaml交叉引用metadata.*关系、external_skills、depends_on模块索引页技能总览 / 工作流 DAG 可视化子模块文档每个技能下的参考文件静态站点生成器直接消费已有的 YAML 定义与 Markdown 文件——这是少量胶水代码而非重写。已存在的内容来源来源生成物skills/*/SKILL.mdfrontmatter技能索引页、每个技能元数据卡片skills/*/SKILL.md正文单技能页面skills/*/references/*.md每个技能下的子页面commands/*/*.yaml带类型化 inputs/outputs 的命令参考页commands/workflow-manifest.yamlDAG 可视化、阶段总览页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 buildsite/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、alternativedomain 标签、兼容性信息等新元数据是否放在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 的解法双格式HTMLMD自定义端点可在/skills/react-expert/index.md提供原始 markdown与/skills/react-expert/的 HTML 并存——受支持的模式而非 hack从 YAML/SKILL.md 自动生成内容集合Content Collections定义与 SKILL.md frontmatter 匹配的 schema指向skills/*/SKILL.md页面带类型化数据自动生成命令 YAML 成为第二个集合开箱即用的 SEOLighthouse 100/100自动 sitemap、meta 标签、OpenGraphStarlight 增加搜索、导航、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 Actionspush 到 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 4Astro 搭建───────────── 在 #69 之后 Phase 5构建部署─────────────── 在 Phase 4 之后 Phase 6维护────────────────── Phase 5 之后持续进行七、提案在仓库中的落地进展从图纸到代码docs/ideas/documentation-site.md是一份想法文档而仓库的site/目录已经把它推进到了可运行状态——这是本文能给出的最有说服力的验证。以下是逐项对照生成器选型已定且已配置。site/astro.config.mjs 实际采用 Astro Starlightsite指向https://jeffallan.github.io、base为/claude-skills通过head数组注入了 Google 站点验证 meta、GA4 统计脚本、指向/claude-skills/llms.txt的relalternate声明恰好落实了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.json67 技能 / 9 工作流 / 371 参考文件与 astro.config.mjs 中link relalternate ... href/claude-skills/llms.txt的声明形成闭环。社交分享能力已预置。仓库根目录的 assets/social-preview.html 与 assets/social-preview.png1280×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 是理解整套机制的最佳起点。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考