事情得从办公室那声“老登”说起。我组里几个年轻人平时管我这个工作十二年、现在主攻 AI 应用落地的人叫“老登程序员”。上个月我花半天时间把 agentskill.work 从空白仓库做到全量上线回来之后他们再喊这个称呼我答应得比谁都快。这个项目是一个给 AI Agent 使用的技能包分享站把大模型干活时需要的那套标准化流程、工具参数、提示词模板打包成一个个 SKILL.md 文件让人可以浏览、筛选、复制、提交并查看说明。如果你也想尽快上线一个内容型小产品又想在第一版就把部署、SEO、自动化审核全部安排明白那这篇记录应该能给你省下不少时间。1. 为什么偏偏是 agentskill.work1.1 一次群聊引发的立项起因很简单。上周一个技术群里有人晒了个三天完成的 Agent 工作流平台界面很花哨接了模型、接了很多工具但点进去发现核心技能定义散落在数据库和代码里别人根本没法复用。我当时就一个想法这东西要能“标准化、可分享”才算真正有点价值。所谓 Agent 技能说人话就是给大模型搭配的一套可复用的操作说明书。核心是文本协定一个 SKILL.md 文件说明“什么时候调用、调用时需要哪些参数、按什么流程处理”再配上一组脚本或资料文件让 Agent 遇到对应任务时能按部就班地用起来。很多场景里的可靠性就是这么来的因为提示词是软的但流程定义是硬的。我随手起了个名字 agentskill.work拆开就是 agent、skill、work。思路很清楚做一个公开的技能包仓库站点让每个人都能提交自己的 SKILL.md其他人能看到它适合什么场景、依赖哪些工具、怎么安装一键复制到本地或者自己的 Agent 项目里。群里那个人做的是“平台”我做的是“基础设施”两者不冲突而且后者内容涨起来之后价值会越来越厚。立项通常用不着一整张 PPT能说得清三个问题就够了给谁用、解决什么麻烦、跟已有方案有什么差异。这个项目的用户就是 Agent 开发者和使用者麻烦在于技能不透明、不互通、到处复制粘贴又没人维护版本。1.2 老登的技术选型哲学年轻人听说我要半天上线第一反应是用一套前端重型框架加实时数据库再配一堆模型网关、向量库听起来很稳妥但半天根本做不完。老登的哲学不一样能用静态生成器就不上服务端渲染能用纯文本存数据就不建数据库能交给托管平台执行构建就不自己买服务器。我的最终选型是Next.js 做静态导出内容全部以 Markdown 文件存在 GitHub 仓库里部署走 VercelDNS 用 Cloudflare 管理。有人可能觉得这组合不够“新”但每一项都是为内容型站点量身定制的。Next.js 的静态导出能力可以把每个技能详情页提前生成成 HTML访客访问时不需要任何 Node 进程加载极快天然抗爬。Markdown 文件自带可读性人类能直接 review 内容机器也能通过固定路径快速解析。GitHub 是天然的存储引擎和协作后台大家提交技能包不是往数据库里灌数据而是提 Pull Request。Vercel 在我 push 到 main 分支后自动触发构建和部署省掉所有运维心智负担。为什么强调“自动化能交出去就不手写”因为上线的敌人不是功能少而是变更链路长。当构建、预览、发布、回滚全部复用原生的托管平台能力你就可以把精力集中在内容规则和审核逻辑上而不是半夜爬起来重启服务。1.3 把边界画出来再动手半天项目有个残酷规律你想得越宽死得越快。我给自己立了三条不可违背的边界。第一首版不做账号系统。用户提交技能走 GitHub PR站长在仓库里做人工审核不需要注册、邮箱验证、权限分级。这意味着身份认证的复杂度直接被移除同时审核流程天然留痕。第二首版不做在线 Agent 执行沙箱。让用户在网页里直接调模型、跑一遍技能确实很酷但会引入 API Key 管理、模型计费、超时任务清理这些深坑。首版老老实实做“预览 复制 下载”在线执行后面用独立服务补齐。这样演示时也能说清楚 Value 在哪里而不是用一个不停转圈的控制台糊弄人。第三首版全域只读。除了 GitHub 那边的 PR 提交站内没有写操作后端零接口连表单都不用埋。边界画完之后整个项目就退化成一件极其舒服的事情一个读取仓库文件并渲染成页面的静态站。剩下的时间全部砸在信息架构和内容规范上因为那才是这个站点区别于普通作品集的地方。2. 从零到上线的真实操作记录2.1 半小时搭出站点骨架老登做事第一板斧是把脚手架跑起来。系统里只要有 Node 和包管理器一行命令就能得到带 TypeScript、Tailwind、App Router 的初始工程。这类项目 I/O 少、刷新频率低我直接关掉了所有运行时特性在 next.config.mjs 里显式声明静态导出。const nextConfig { output: export, images: { unoptimized: true }, trailingSlash: false, }; export default nextConfig;这里有个新手容易吃亏的点用了 next/image 但忘了关图片优化静态导出时构建会直接报错。大部分站点的技能封面都是普通图片直接禁用优化就完事反正部署在 CDN 前面图也快。接下来搭三个顶层路由首页、技能详情、提交页。提交页不接表单只放一个按钮链到 GitHub 仓库的 Pull Request 页面加清楚的操作指引。首页拆成 Hero 区域、标签筛选区和技能卡片列表详情页按“概述、使用方式、配置参数、依赖、示例对话、版本记录”的顺序组织内容。半小时搭出来的骨架主要是布局和视觉约束不需要华丽但要保证路子对颜色用两三个中性色字体默认多语言适配卡片间距统一。丑一点没关系内容没上来之前美化和返工纯属浪费。2.2 Markdown 数据流与静态渲染设计数据流之前我先把仓库内容组织方式定了。每个技能包占用一个目录里面有一个 SKILL.md 作为主文件可能还带 assets 目录放参考文档和脚本。SKILL.md 的头部用 YAML frontmatter 承载元数据正文用标准 Markdown 写操作流程。--- name: web-search-assist title: 内部文档检索助手 description: 帮助 Agent 在企业文档站里快速定位并总结相关信息 version: 0.3.0 tags: [搜索, 文档, 总结] tools: [web_search, extract_url, summarize] author: laodeng ---为什么选 Markdown 而不是 JSONAgent 本身靠上下文文本工作把技能写成文本文件模型可以直接读取人类也可以直接阅读和修改版本管理又天然基于 git diff。JSON 虽然结构化但对于非程序员来说门槛明显更高也不利于写长流程。页面侧的逻辑不复杂。构建时用一个脚本扫描 /skills 目录下的所有目录读取每个 SKILL.md 的前置元数据生成一份全局 index.json同时给每个技能生成一个详情页面对象。用 Next.js 的 generateStaticParams可以预先得到每个技能页的路径参数然后逐页渲染。export async function generateStaticParams() { const skills await getAllSkills(); return skills.map((skill) ({ slug: skill.slug })); }这一步是老登最看重的地方数据是“静态”的但绝不死板。访问者的筛选、搜索行为全部在前端完成——打开页面第一时间去 fetch 全局索引 JSON然后根据标签和关键词做客户端过滤。为什么不上服务端搜索因为内容总量少索引文件小客户端搜索响应毫秒级还能减少一个故障源。等技能包超过几百个再考虑接入云搜索这个演进路径是平滑的。2.3 一键部署和域名解析React 项目本地跑起来只算完成了一半老登和“搬代码的”最大区别就在后面这两步部署、上线、验证。我先把项目推到 GitHub 私有仓库然后在 Vercel 上选择仓库并配置生产分支。Vercel 检测到 push 后自动执行 npm ci、npm run build成功后生成一个可直接访问的预览地址域名点击绑定即可。域名这块agentskill.work 的 DNS 由 Cloudflare 托管操作顺序要谨慎。先在 Cloudflare 的 DNS 面板添加一条 CNAME 记录指向 Vercel 提供的目标地址再回 Vercel 的域名设置里填上 agentskill.work。我说实话顺序反过来的话很容易出现域名可用但 HTTPS 证书迟迟签不下来的情况。CNAME 记录内容大概是agentskill.work - cname.vercel-dns.com这里要提一个 DNS 生效的常识修改解析后全球生效时间通常在几分钟到二十四小时之间和本地缓存强相关。验证时别用浏览器硬等直接在终端敲一个查询命令看看结果更稳妥。dig agentskill.work CNAME看到记录正确返回后再访问域名看证书是否自动发好。整个部署过程我没写一行服务器配置脚本也没有 ssh 登录任何机器。这套玩法最大的优势不是省一台虚拟机而是让“上线”变成每天可以发生二十次的高频动作而不是一个需要挑日子执行的仪式。2.4 发布当天的 SEO 动作半天上线的项目流量不会因为域名好听就自己涌过来。我的思路很朴素标题和描述里把核心词讲清楚每个页面都给搜索引擎足够的结构化信息。首页的 title 直接写成 “Agent Skills - 可复用的 AI Agent 技能包”description 解释这个站是干什么的、适合哪些人。每个技能详情页的 title 就是“技能名 场景说明”比如“内部文档检索助手 - Agent Skill”保证搜索意图能精准匹配。另外在每个详情页加入 JSON-LD 结构化数据。这里用同样来自 Markdown frontmatter 的字段包括技能名称、简介、发布者、版本、标签。搜索引擎看到这些语义信息更容易把页面当作一个标准物件来索引而不是一堆无分类的 HTML。我还会刻意保留一个 robots.txt 和站点地图。静态导出框架一般都能自动生成 sitemap.xml但 robots.txt 我建议手写明确允许全量爬取并且把技能目录标记为优先。至于社交平台的分享卡片我用一张动态生成的小图放在 /api/og 上但首版没做复杂套壳就用固定品牌图。这些 SEO 工作看似琐碎其实占不了半个小时。但对一个工具类内容站来说它决定了你在前两周有没有自然搜索流量入口。标题里那个 agentskill 本身就是搜索热词的一部分页面结构越清晰越容易吃住这波精准需求。3. 坑与排查实战实录3.1 差点翻车的三个瞬间第一个坑是代码高亮。SKILL.md 正文里全是代码块、参数表格、shell 命令如果渲染器选择不当生成的页面会无比臃肿首屏要加载几百 KB 的脚本。我用的是 react-markdown 配合一个轻量级代码高亮方案只高亮不搞复杂交互首版脚本体量控制在可以接受的范围。第二个坑跟版本相关。某个技能包在 SKILL.md 里写了一个相对路径图但站点目录结构和仓库里的目录结构不一样导致页面 404。后来我统一了路径规则标题里只允许用仓库根目录作为规范基准渲染时再做一次路径 remap。这个设计很土但在内容型项目里非常好用直接消灭一类“本地正常、线上白屏”的问题。第三个坑是中文内容的分页截断。有些技能说明特别长我希望在列表卡片里显示摘要而不是把全文切出来。为卡片做摘要时如果按字数盲切很容易把中文标点切坏。最终的方案是在 frontmatter 里加一个 summary 字段列表卡片只读这个字段详情页才读全文。这样两个页面职责分离内容作者也能完全控制展示效果。3.2 搜索功能为什么没上服务端项目上线前年轻人问我搜索是不是该用 Elasticsearch 或 Algolia我的回答是不用浏览器自带能力。站点内容只有几十个技能包全局索引 JSON 也就几百 KB浏览器控件读一次就能完成全量检索速度根本不在一个纠结层级。服务端搜索的方案不是不能用但它会引入同步任务、索引构建、权限控制、费率消耗等一堆新问题。对一个首版只读、内容量可控的站点这些都是过度设计。老登的判断标准其实很简单当前规模下不值得做的事就不做等规模大了再做也不算推翻重来。如果你后续真的要做服务端搜索我建议也不是一步跳到 Elasticsearch。可以用同一个 index.json 接到 Cloudflare Workers 或云函数里做一个带关键词参数的小接口缓存友好成本可控。也就是说演进路径应该是从“纯静态索引”到“一个轻量接口”再到“专业搜索服务”而不是一上来就摆重型武器。3.3 常见问题速查表上线到今天朋友和同事踩过的问题集中在下面这几类我整理成一个速查表格方便你直接抄作业。症状可能原因处理方式页面 404 或白屏详情页路径与仓库目录结构不一致统一使用仓库根目录作为路径基准检查 generateStaticParams 的返回值构建失败且报图片相关错误next/image 在静态导出时无法处理优化在 next.config 中把 images 设为 unoptimized或改用普通 img 标签DNS 改了解析但访问没变化本地 DNS 缓存未过期用 dig 命令确认记录再尝试刷新本机缓存或切换网络验证部署失败但本地构建正常分支名不匹配或环境变量缺失检查 Vercel 的 Production Branch 设置确认提交的默认分支为 main中文摘要显示乱码或截断前端按字节裁剪字符串改用 frontmatter 中的 summary 字段由内容作者控制长度搜索无结果全局索引 JSON 未更新重新触发构建确保脚本扫描技能目录后重新生成 index.json这些坑都算不上高级错误但因为项目工期短每一个都可能直接把半天压缩成一天。我会说多踩一次就对“为什么要自动化”多一分敬畏。4. “老登程序员”的效率来源4.1 不追求完美架构追求可演进架构年轻人做项目容易把架构设计当成交付物本身。我干了十几年见过很多团队在首版就设计了七层抽象结果产品没人用代码先把自己累死了。老登做事的逻辑是先找到能跑通的最小闭环再考虑如何沿着同一套数据模型持续叠加功能。agentskill.work 的整个架构核心只有一条数据路径仓库里的 Markdown 文件 - 构建时索引 - 静态页面。后续所有功能演进都遵循一个原则不断开这条链路只往两端插东西。比如加入多语言支持就是给文件加一个新的语言目录加入版本对比就是在 frontmatter 里加版本号并保留历史文件加入在线执行就是在详情页加一个请求代理复用已经定义好的技能参数。这种架构的好处是“退路特别多”。哪天觉得 Next.js 太重换一个静态站点生成器只要数据格式不变迁移成本就很低哪天觉得 GitHub 不够用换一个对象存储加 CMS页面渲染逻辑也不用动。架构的价值不在于它当时多先进而在于它不绑架下一步的方向。我经常跟人讲不要把时间花在“未来可能很麻烦”的担忧上而要把时间花在“现在很差劲”的痛点上。首版架构只需要做到改内容方便、上线方便、查问题方便。剩下的事情等你真的遇到第二十个版本再说。4.2 能自动化的事就不手工盯上线第一周我花在维护上的时间基本为零因为把重复劳动全部压到了脚本和托管平台上。技能包数量增加、内容更新频率提高之后手工人肉同步是不可接受的。仓库里放了一个 GitHub Actions 工作流功能有两块一是跑格式校验二是触发站点构建。校验脚本会检查每个 SKILL.md 的 frontmatter 是否包含必填字段描述长度是否合规标签是否在预设白名单里。校验通过后Vercel 自动部署出新版本。name: validate-skills on: pull_request: paths: [skills/**] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: npm ci - run: npm run validate这里有个细节值得说校验放在 Pull Request 阶段而不是合并到 main 之后。因为此时发现问题提交者能直接修改并重新推送不会污染主分支。这个判断来自一个老登习惯把错误拦截在离源头最近的地方越往后排查成本越是成倍增长。再说一个自动化反哺内容的例子。所有技能包都有一份对应的 README 模板提交者只要填好模板校验脚本会自动生成站内详情页所需的半结构化数据。这让贡献者的心智负担降到很低也让站点的内容质量标准不依赖于某一个人的责任心。4.3 经验的本质是预判坑位半天上线一个项目真正值钱的不是敲键盘的速度而是提前把坑位圈出来的能力。年轻人第一次做部署可能会在“为什么同样的代码我本地能跑、线上不能”上耗掉两小时老登看了一眼分支和构建日志就能定位到问题因为他掉进过同一个坑而且记得比谁都清楚。我这次的预判有三个第一静态导出绝不能碰动态服务端功能第二内容型站点的 SEO 优先级高于动画和交互特效第三没有后台的前提下表单提交不如 GitHub PR 靠谱。这三条每一条都是在别处踩过坑换来的经验今天用起来就像条件反射一样快。经验的另一个来源是读过大量别人的生产事故复盘特别是那些“上线很顺利一个月之后发现数据模型扛不住”的案例。老登的优势不是不会犯错而是能在一个错误成为事故之前就感知到它。这种对危险的嗅觉没法靠文档传给新人只能靠持续地在项目里翻滚、碰到问题、记录、再碰下一个问题。5. 上线之后从玩具到工具5.1 技能包如何形成社区闭环站点上线后我最大的愿望不是流量暴涨而是让技能包形成正向循环。所谓闭环就是读的人越多提交的包越丰富提交的人越多浏览价值越高浏览价值越高回访和引用越频繁。为了让这个闭环转起来我在每张技能卡片上都加了“复制安装命令”和“查看完整说明”两个操作配合详情页的版本记录与依赖列表让使用者不离开页面就能判断是否值得引入。这个判断成本如果足够低拿走使用的概率就会明显升高。我还把提交门槛降到最低不需要注册账号不需要理解 git 理论只要会写 Markdown 就能给仓库提 Pull Request。校验脚本会在 PR 阶段把字段完整性、描述格式等问题直接反馈给提交者。相当于把审核能力前置到了开发者身边而站长只需要在合并前扫一眼是否合规。要说还有什么遗憾就是站点目前还没有生成足够多的“成功案例”也就是用户在真实工作流里用某个技能包解决了什么具体问题的叙事。这种东西比一百个点赞都有说服力。后续我打算在详情页增加一个“使用反馈”入口让使用者留下一句话慢慢沉淀成对提交者最好的激励。5.2 商业化之前先想清楚的四件事不少人看到流量起来就问怎么赚钱我的习惯是先把赚钱放一放认真想清楚四件事再做决定。第一技能包的版权和授权规则。哪个许可证允许商用、哪个只允许个人使用、贡献者提交后算不算授权给站点分发这些都是法律级细节马虎不得。过早收费如果贡献者失去动力社区生态会比赚那点钱更亏。第二能不能保持中立。如果哪天我自己出了很多技能包并把它排在搜索结果前面社区信任就会崩盘。中立性和公信力是这类基础设施的唯一资产维护它比优化收入重要一百倍。第三躺着赚钱的路径是否合理。更合理的可能是提供企业服务比如私有部署、定制技能包、团队内部技能管理平台而不是向个人属性强的用户收费。企业愿意为可靠性和可维护性付钱个人的可挥发性太强。第四自动化维护能撑到多大。技能包数量涨到一万个时人工 review 就不可行了需要引入更智能的重复检测和内容安全机制。这笔投入不是一次性功课而是伴随整个业务生命周期的持续成本。我的观点很明确工具站最容易犯的错就是过早植入商业化把用户当韭菜。产品先成为大家真正离不开的公共设施再谈商业模型腰杆才硬。这个项目做到这里我自己最大的体会倒不是技术多炫而是“老登”这两个字如今确实带着点含金量。它的来源不是会多少框架而是清楚了什么不该做、什么是首版不必解决的、哪些操作无论如何都要留着退路。agentskill.work 用半天上线并不代表我比谁快多少只代表我在过去的十几年里已经把那些会浪费半天的大坑提前踩完了。如果你也想做类似的内容型项目建议把第一版的目标定为“能安全上线、能被人看懂、能为后续留出改动空间”而不是“在开屏动画里塞进一个 Agent”。经验这种东西不见得非得自己撞到满头是包才长记性读一读别人踩过的路也算一种抄近道。