他把Agent技能库做成文档站，GitHub Pages访问量3

　　一个产品经理花两周时间，把零散的Agent技能文件变成了能自动切换中英文的文档站。没有服务器，没买域名，全靠GitHub Pages免费托管。上线第三天，仓库Star数从12涨到340，Issues里开始出现日文和德文的翻译请求。

　　这事听起来像技术博客的常规操作，但背后藏着2026年AI工具链的一个关键转向：当所有人都在卷大模型参数时，有人发现"怎么让Agent看懂指令"才是卡住开发者的真痛点。

　　作者叫陈默（化名），前某厂B端产品经理，现在全职做开源工具。他的项目叫agent-skill-hub，定位是"Agent的技能说明书仓库"。每个技能一个文件夹，里面塞着SKILL.md——不是给人看的散文，是给大模型读的执行手册。

　　陈默跟我算过一笔账：用Gemini CLI调GCP服务，新手平均要试7-8次才能跑通第一次部署。不是命令复杂，是每次都要重新解释上下文。"你告诉它'帮我建个VM'，它问你区域、机型、磁盘类型，三轮对话过去，耐心没了。"

　　SKILL.md的解法是把这套对话预演一遍。文件结构固定：技能描述、参数定义、执行示例、错误处理。LLM第一次读取就能建立完整的调用上下文，用户只需要说"执行gcp-helper"，后面的事Agent自己翻文档。

　　陈默最初觉得，GitHub仓库本身够用了。README写清楚，SKILL.md放docs目录，开发者自己翻。

　　但跑了一周社区运营后，数据打脸了：仓库访问量日均40，但SKILL.md的完整阅读率不到15%。有人在Discord问"这个技能怎么用"，答案明明写在文件第三段。

　　他意识到问题：代码仓库是给贡献者用的，文档站是给使用者用的。两类人群，两种场景，不能混为一谈。

　　2026年2月，陈默开始折腾GitHub Pages。需求很明确：零成本、双语言、看着像那么回事。他翻了十几个技术文档站，最终盯上Whisper ASR的页面设计——深色背景配青绿色（Teal）强调色，代码块高对比度，移动端不崩。

　　"开发者每天盯着IDE的暗色主题，你给他来个白底黑字的文档站，眼睛先抗议。"

　　技术实现上，他选了最朴素的方案：纯HTML+CSS，没有React，没有Vue，构建时间为零。目录结构按语言拆分：

　　docs/
├── index.html（浏览器语言检测）
├── en/skills/
└── zh/skills/

　　根目录的index.html塞了段JavaScript，根据navigator.language自动跳转。代码就6行，但覆盖了90%用户的默认需求。剩下的10%？页面角落放手动切换按钮，不强制，不打扰。

　　陈默在文档里写明了部署三步走，但我实测时发现一个细节：他刻意避开了GitHub Actions。

　　"Actions很好，但多一个依赖就多一个故障点。我的目标用户里有一半是后端工程师，他们看得懂YAML，但不想为文档站学一套CI/CD语法。"

　　具体做法是把静态文件塞进仓库的docs/目录，在Settings > Pages里指定main分支的/docs文件夹为源。提交即部署，回滚用git revert，没有构建日志要查，没有缓存要清。

　　这个选择牺牲了"自动化生成文档"的可能性——比如从SKILL.md自动渲染HTML页面。但换来了可预测性：任何时候clone仓库，docs/目录里的内容就是线上看到的内容，没有中间层。

　　陈默的原话是："文档站的寿命往往比项目本身长。三年后我自己都可能忘了怎么维护，越简单越能活。"

　　上线后的数据验证了这个判断。Google Analytics显示，直接流量占62%，搜索引擎占28%，社交媒体只有10%。用户行为也很"老派"：平均停留4分半，跳出率31%，典型的"带着问题来，找到答案走"。

　　文档站是"门面"，SKILL.md才是内核。陈默花了最多时间打磨的文件格式，表面看是Markdown，实际是面向LLM的接口定义。

　　结构强制分层：

　　1. 元数据块：技能ID、版本、作者、依赖技能列表
2. 能力描述：用"该技能可以..."开头，训练LLM的意图识别
3. 参数表：名称、类型、是否必填、默认值、验证规则
4. 执行示例：至少包含一个完整调用和一个边界情况
5. 错误码：分用户错误（参数不对）和系统错误（服务挂了）

　　这个格式的灵感来自OpenAPI，但做了大幅简化。"Agent不需要知道HTTP状态码，它需要知道'磁盘满了'和'权限不足'该怎么区分处理。"

　　一个具体例子：n8n-executor技能负责调用n8n工作流。早期版本只写"触发指定工作流"，LLM经常误解为"获取工作流列表"。改成"该技能用于执行（execute）而非查询（query）n8n工作流，需要workflowId和可选的inputData"后，误调用率从23%降到4%。

　　文档站对此的呈现方式是双栏布局：左边渲染后的说明，右边原始SKILL.md的代码块。陈默的解释是："让使用者看到'说明书'，让贡献者看到'模板'，两拨人在同一个页面各取所需。"

　　上线第七天，陈默收到第一条日文Issue。不是Bug报告，是询问"接受社区翻译吗，我想加ja/目录"。

　　他起初犹豫：日语用户真的需要吗？Agent技能的核心是调用英文API，界面语言本地化有多大价值？

　　但对方给的理由说服了他：日本有大量制造业企业的IT部门，工程师技术过硬，但英语阅读速度慢。SKILL.md的结构化特性，让日语版本可以只做"能力描述"和"错误提示"的翻译，参数名、代码示例保持英文，不影响LLM解析。

　　这个模式后来被复制到德语、韩语版本。陈默建立了简单的贡献规范：翻译文件放在docs/[语言代码]/skills/，元数据块保持英文，正文可本地化。没有翻译平台集成，纯靠Pull Request审核。

　　截至3月中旬，agent-skill-hub收录了27个技能，覆盖云服务商（AWS/GCP/Azure）、自动化工具（n8n/ Zapier）、开发辅助（Git操作、Docker管理）三类场景。文档站日均PV稳定在800左右，来自日本、德国的流量合计占19%。

　　陈默最近在测试一个新功能：让Agent直接读取文档站的HTML，而非仓库里的原始Markdown。原理是利用语义化标签——把技能描述塞进

　　，LLM的网页浏览模式能精准定位内容区块。

　　"SKILL.md是给机器看的纯文本，HTML是给机器看的结构化数据。中间隔了一层渲染，但信息密度更高。"

　　这个实验还没写进文档。但仓库的最近提交记录显示，他正在给所有技能页面添加JSON-LD格式的Schema标记。

　　所以问题来了：当Agent能直接读文档站、甚至能自己提交PR补充技能时，产品经理做的这个"门面"，到底是给人用的，还是给机器用的？