看到 ConardLi 这类开发者维护的 garden-skills 项目很多人第一反应是问这个仓库到底写了什么、能不能直接拿来跑。但我的判断不太一样——像 garden-skills 这种以 skills 命名的仓库价值核心并不是某一个库或某一段代码而是一套把零散经验整理成可复用模块的方法。它解决的问题非常具体踩过坑、写过方案、调过接口之后这些碎片该怎么沉淀才能在下次遇到同类问题时快速找到并直接用。这篇文章适合两类人一类想搭建个人技术知识库但不知道按什么维度分类另一类已经攒了很多笔记每次找某个结论却要翻半天。下面按实际落地顺序拆一遍重点讲仓库结构、技能卡片怎么写、发布链路怎么搭以及仓库为什么会被维护着维护着就废掉。1. 先想清楚“技能花园”这条主线到底解决什么问题在开始建目录之前我建议先想一个问题你需要的是笔记还是一套技能卡片笔记的价值是记录技能卡片的价值是复用。一条技能卡能直接解决某个场景记录却不一定。garden-skills 给我的启发是与其把仓库当成收藏夹不如把每一条内容当成一个可以独立交付的模块它有自己的适用场景、前置条件、操作步骤、验证方式和已知边界。所以第一条判断标准一条内容如果没有场景、没有步骤、没有验证方式它就不该进入技能库应该留在草稿箱。这个标准听起来简单但大部分人的仓库变乱都是因为把“我以后可能会看”的内容也塞了进来。1.1 它和笔记软件、博客有什么区别笔记软件强调捕获速度讲究“想到就记”博客强调表达讲究读者视角而一个 skills 仓库强调复用讲究结构化。同一个内容在笔记里是一段随手记录在博客里是一篇文章在技能库里就应该是一张包含环境、步骤、验证、坑点的卡片。三者的维护成本完全不同。如果只是自己看笔记就够如果要给别人看博客就够如果要让过去的经验在未来省时间技能库才是更合适的形式。选择之前先确定目标否则很容易出现“明明每天都在写却不知道为什么要写”的状态。1.2 判断仓库是否健康的核心指标我一般不看仓库 star 数更关注这几个指标新增一条技能卡的成本是不是足够低一个月内能不能找到自己上个月写过的结论旧内容有没有被更新或删除有没有人在技术方案里引用它。如果这几个答案都是否说明仓库还停在“堆放状态”没有形成技能体系。指标健康状态不健康状态新增成本打开模板10 分钟能写完一条每次要从空文件开始检索成本按目录或标签三步内找到只能靠关键词猜更新频率旧卡片按季度修订写完再也不碰复用情况至少被自己引用过一次只是收藏这个表可以在建库之后每季度过一遍比单纯追求内容数量有用得多。2. 从零搭建一个 skills 仓库的完整流程下面给一套我比较常用的建库顺序不是唯一方案但足够稳定。整个过程分四步设计目录、定义模板、建立输入流程、配置发布。顺序很重要不要反着来。2.1 仓库目录设计先按主题分再按类型分第一层用主题域比如 frontend、backend、engineering、tools、career。不要用时间命名也不要用难度命名。时间会过期难度太主观只有主题域能长期稳定。每个主题下面再按类型分比如 troubleshooting、how-to、cheatsheet。garden-skills/ ├── README.md ├── frontend/ │ ├── troubleshooting/ │ ├── how-to/ │ └── cheatsheet/ ├── backend/ │ └── troubleshooting/ ├── engineering/ │ └── how-to/ ├── tools/ │ └── cheatsheet/ └── inbox.mdinbox.md 是临时落点所有随手记录先放这里每周整理一次。这个文件最容易被忽略但非常重要——它保证了“快速捕获”和“结构化沉淀”不冲突。没有 inbox你会为了保持目录整洁而抗拒记录有了 inbox你可以先记下来再做判断。注意目录不要建太深两层最多三层。超过三层检索成本会快速上升维护意愿会下降。2.2 技能卡片模板把一条经验变成可复用模块每条技能卡片建议包含以下字段标题直接写这个技能解决什么问题适用场景什么条件下用前置条件需要什么环境、依赖、权限操作步骤按顺序列验证方式怎么确认成功已知坑点容易踩的问题替代方案什么时候不选它模板示例# 技能排查 GitHub Actions 工作流失败 - 适用场景push 后 workflow 没有执行或执行失败 - 前置条件仓库有 Actions 权限workflow 文件在 .github/workflows 下 - 操作步骤 1. 打开仓库 Actions 页面找最近一次 run 2. 展开失败 job查看具体 step 日志 3. 确认触发分支和触发事件是否匹配 - 验证方式修复后新 commit 能触发同一 workflow 并通过 - 已知坑点本地能跑的命令不一定能在 Actions 里跑环境变量和依赖源都要单独确认 - 替代方案先在本地用 act 模拟再提交远端写作时有一个原则先写验证方式再写步骤。因为不写清楚“怎么算成功”步骤很容易被人跳过然后继续踩同样的坑。另一个原则每张卡只解决一个问题。一个问题拆成多张卡比一张卡塞进三个问题更容易维护。2.3 从随手记到正式卡片的输入流程我的流程是遇到问题 → 先写入 inbox.md → 当天或本周挑一条转成卡片 → 发布或同步到 README。注意不是所有内容都要转卡片。只有满足两个条件才值得转它花了你至少半小时解决你有把握在未来三个月内还会遇到同类问题。否则留在 inbox 就行等它被再次遇到再说。注意不要把“以后可能会看”的内容直接建卡。技能卡必须服务于一个具体场景否则三个月后你根本不知道它该用在哪个问题上。这里最容易出问题的是“当日热修”。问题解决时最有动力记录但也最容易写得很碎比如只记了一句“改了参数就好了”。我的做法是当时只补三条——现象是什么、改了什么、怎么验证后续如果真的还要碰再补完整步骤。这样热修不会打断工作流也不会留下不可用的废卡。3. 可复用性的关键标签、索引和定期修剪内容一旦多起来最怕的不是没有人看而是找不到、不信任。可复用性主要靠三件事维持目录管归属标签管交叉修订管时效。这一节拆开讲。3.1 标签不是越多越好目录解决的是“这件东西放在哪”标签解决的是“哪些内容互相有关”。标签数量建议控制在 20 个以内并且每个标签必须有明确含义。最忌讳的是同一个意思建多个标签比如“前后端”和“全栈”并存、“部署”和“发布”并列检索时反而更难命中。举个例子如果你有三条卡片分别讲前端资源压缩、图片格式选型、接口缓存策略它们都属于“性能优化”但这个标签会和前端、后端、工具三个目录交叉。这种情况下“性能优化”标签才是合理的而不要建“前端性能”“后端性能”“工具性能”三个标签那样标签就失去了交叉检索的意义。写卡片时我一般会顺手维护一个 tags 索引页把所有标签和对应卡片列出来。这个索引页可以手动维护也可以在提交时用脚本生成。手动维护成本低适合内容少的情况脚本生成适合内容多的仓库。对于单张技能卡建议每张最多 3 个标签。标签越少越容易保证一致性。如果你发现自己给一张卡贴了 6 个标签大概率是这张卡本身混进了多个问题应该拆分。3.2 定期修剪比持续新增更重要知识库和花园一样只种不剪最后会杂草丛生。我建议每季度抽一个下午做三件事把全部卡片扫一遍标记内容已经过期的把超过一年没有被更新的卡片合并或删除检查是否有两条卡片解决同一个问题有则合并。这个动作很难坚持但它是仓库能否长期有用的分水岭。修剪时可以把过期内容移动到 archive 目录而不是直接删除。archive 保留原始记录正式目录保持干净两边都不难受。如果 archived 的内容连续两个季度没人再碰再决定删除。很多人仓库废掉不是因为没有内容而是因为旧内容和新内容互相矛盾最后谁都不敢引用。修剪时如果拿不准我的判断标准是这条记录如果今天消失会不会影响你接下来的工作如果不会就删或合并如果会就更新它。仓库的价值不在于条目数量而在于每一条都被信任。4. 发布链路的搭建从 Markdown 到可访问页面内容写完后下一步是发布。个人仓库最简单的方式是用仓库页面直接浏览 README 和卡片目录。缺点是目录一多阅读体验就下降。进阶一点可以引入一套自动化Markdown 源文件 → 检查 → 生成索引和站点 → 部署到 GitHub Pages 或自己的博客系统。自动化能省时间但要在正确的时候引入。我的建议是先把本地路径跑通再写 CI否则你会同时面对内容和构建两个问题很难判断报错来自哪里。4.1 一套够用的 GitHub Actions 发布流程发布链路不要一开始就搞复杂。下面这个 workflow 是一个很基础的示例推送 main 分支时先检查 Markdown 链接再生成站点到 gh-pages 分支。它只做一件事逻辑很清晰。你可以按自己的站点生成方式替换 build 部分。name: publish on: push: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Run link check run: make check - name: Build site run: make build - name: Deploy uses: peaceiris/actions-gh-pagesv4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist这里用的是常见动作版本号只是示例实际使用时以你确认的版本为准。第一次跑最容易遇到的是路径问题——比如构建产物不在 ./dist或者 make 命令在仓库根目录找不到。先看日志里的工作目录再改路径不要猜。注意第一次跑 Actions先看日志里的 working directory 和文件路径不要直接改构建命令。手动改配置容易把原本能跑的部分也搞坏。至于端口、域名、CDN 这些只有浏览量上来了才需要考虑。前期不需要为性能做任何优化。4.2 如何验证发布链路正常判断发布链路是否正常不只看页面能不能打开。我一般按这个顺序验证push 后 Actions 是否进入 run三分钟内是否变成绿色打开部署后的网址看首页索引是否更新点进其中一条卡片确认链接、代码块、目录都能用再检查旧链接有没有因为重构而失效。如果页面是空白先看构建日志里有没有成功提示再看 dist 目录是否生成了 index.html最后才怀疑部署插件。顺序不要反过来直接改代码往往改不到点上。同步策略也值得提前想。内容源只有一个其他位置都通过构建生成不要手动复制到博客或公众号。手动同步多了数据源就不唯一后面对不齐是必然的。5. 常见坑点与排查顺序这类仓库在搭建和维护过程中总会遇到几个看起来很奇怪的问题。这一节列出我踩过或看别人踩得最多的四类。5.1 写了很多内容但还是搜不到这个问题通常不是搜索引擎的问题而是标题和文件命名的问题。如果每条卡片都叫 01.md、test.md搜索引擎和读者都不知道它讲什么。我一般建议文件名直接使用有意义的小写连字符比如 frontend/troubleshooting/github-actions-path-error.md。这样不用打开文件光看目录就知道这条内容覆盖什么。标题也一样。不要写“关于 Actions 的笔记”这种标题要写“GitHub Actions 路径错误排查”。标题里带上主词内容里在开头重复一次这样无论是读者浏览目录还是搜索引擎收录都能快速命中。5.2 仓库越维护越乱核心原因是什么大部分情况是“数据源不唯一”。笔记里存一份、博客里存一份、仓库里再存一份同一份内容改了三处最后互相矛盾。解决办法是确定单一事实来源以一个目录为唯一内容源其他位置都通过同步或引用生成。同步可以由 CI 完成但前提是源目录稳定、命名规范。如果你发现自己在两个地方手动维护同一份内容就该停下来想想哪个是源哪个是产物。产物只读不能手动改。这个原则比任何自动化工具都重要。5.3 不要在内容还没成型时做自动化我看到最多的失败模式是仓库刚建好先花三天配自动部署、主题、评论系统结果一条卡片都没写。自动化的价值建立在内容稳定、目录稳定的前提下。内容还在频繁变动时做自动化只会让每次改动都要处理构建问题。我的建议是先写内容跑通一条手动发布路径再考虑要不要加 Actions。判断时机很简单——当你连续三次发布都只是复制文件到部署目录、开始觉得机械重复时就是引入自动化的时机。5.4 通用排查顺序如果遇到工作流执行失败、构建报错、页面没更新我一般按这个链路排查先看日志确认失败发生在哪一步再看输入路径和工作目录确认文件真的存在再确认依赖版本和权限比如 Actions 是否允许写入 gh-pages最后才怀疑配置写法。先改参数而不看日志是最浪费时间的做法。这套顺序也适用于很多其他工具。先看现象、再查输入、再查环境、最后查参数基本上能覆盖 90% 的“看起来像是软件坏了”的问题。6. 我的实战建议从最小编成开始别搭完美系统最后给一套可以立刻执行的启动方案。不要模仿别人仓库的全部功能只需要取对自己有用的那部分。6.1 最小启动方案如果你也想做一个 garden-skills 这样的技能库我建议第一周只做四件事新建一个空仓库创建 README.md 和 inbox.md定义一张技能卡片模板写下三条真实经验哪怕每条只有几行。三条经验最好包含一个典型故障、一个常用命令、一个流程步骤。不要在第一周写标签体系不要配评论系统不要迁移旧笔记。旧笔记最晚再迁移先把新经验跑顺。这个方案的目的是让你尽快经历一次“记录→整理→复用”的完整闭环。没有闭环功能加得再多也只是摆设。6.2 后续演进路径当仓库里有了 10 条左右卡片并且你已经遇到过“需要回去找一条旧经验”的场景再考虑加这些功能issue 模板让读者可以直接提“这个技能失效了”标签索引页自动链接检查博客同步或页面发布。每一步都以实际需求为触发条件不要提前堆功能。这时的重点是定期复盘。我一般每个月扫一次 inbox每个季度修剪一次正式卡片。复盘时只问三个问题最近哪些卡片被用到过哪些内容过时了下周最值得新写的是什么回答完这三个问题比打开编辑器硬写更能产出好内容。6.3 什么时候停止优化停止优化的标准很明确当新增一条卡片不超过 10 分钟检索一条旧经验不超过 3 步每次发布或同步不超过 5 分钟时系统已经够用了。继续优化的边际收益很低。这之后更应该把时间花在写内容、修技术债和读别人的技能库上。踩过几次之后我发现garden-skills 这类项目最值得学的不是架构也不是工具链而是“让一条经验保持可复用状态”的能力。仓库只会越写越厚但如果每一条都能被检索、被信任、被复用这个仓库才算真正长出东西来。
从笔记到技能卡片：构建可复用的个人技术知识库
看到 ConardLi 这类开发者维护的 garden-skills 项目很多人第一反应是问这个仓库到底写了什么、能不能直接拿来跑。但我的判断不太一样——像 garden-skills 这种以 skills 命名的仓库价值核心并不是某一个库或某一段代码而是一套把零散经验整理成可复用模块的方法。它解决的问题非常具体踩过坑、写过方案、调过接口之后这些碎片该怎么沉淀才能在下次遇到同类问题时快速找到并直接用。这篇文章适合两类人一类想搭建个人技术知识库但不知道按什么维度分类另一类已经攒了很多笔记每次找某个结论却要翻半天。下面按实际落地顺序拆一遍重点讲仓库结构、技能卡片怎么写、发布链路怎么搭以及仓库为什么会被维护着维护着就废掉。1. 先想清楚“技能花园”这条主线到底解决什么问题在开始建目录之前我建议先想一个问题你需要的是笔记还是一套技能卡片笔记的价值是记录技能卡片的价值是复用。一条技能卡能直接解决某个场景记录却不一定。garden-skills 给我的启发是与其把仓库当成收藏夹不如把每一条内容当成一个可以独立交付的模块它有自己的适用场景、前置条件、操作步骤、验证方式和已知边界。所以第一条判断标准一条内容如果没有场景、没有步骤、没有验证方式它就不该进入技能库应该留在草稿箱。这个标准听起来简单但大部分人的仓库变乱都是因为把“我以后可能会看”的内容也塞了进来。1.1 它和笔记软件、博客有什么区别笔记软件强调捕获速度讲究“想到就记”博客强调表达讲究读者视角而一个 skills 仓库强调复用讲究结构化。同一个内容在笔记里是一段随手记录在博客里是一篇文章在技能库里就应该是一张包含环境、步骤、验证、坑点的卡片。三者的维护成本完全不同。如果只是自己看笔记就够如果要给别人看博客就够如果要让过去的经验在未来省时间技能库才是更合适的形式。选择之前先确定目标否则很容易出现“明明每天都在写却不知道为什么要写”的状态。1.2 判断仓库是否健康的核心指标我一般不看仓库 star 数更关注这几个指标新增一条技能卡的成本是不是足够低一个月内能不能找到自己上个月写过的结论旧内容有没有被更新或删除有没有人在技术方案里引用它。如果这几个答案都是否说明仓库还停在“堆放状态”没有形成技能体系。指标健康状态不健康状态新增成本打开模板10 分钟能写完一条每次要从空文件开始检索成本按目录或标签三步内找到只能靠关键词猜更新频率旧卡片按季度修订写完再也不碰复用情况至少被自己引用过一次只是收藏这个表可以在建库之后每季度过一遍比单纯追求内容数量有用得多。2. 从零搭建一个 skills 仓库的完整流程下面给一套我比较常用的建库顺序不是唯一方案但足够稳定。整个过程分四步设计目录、定义模板、建立输入流程、配置发布。顺序很重要不要反着来。2.1 仓库目录设计先按主题分再按类型分第一层用主题域比如 frontend、backend、engineering、tools、career。不要用时间命名也不要用难度命名。时间会过期难度太主观只有主题域能长期稳定。每个主题下面再按类型分比如 troubleshooting、how-to、cheatsheet。garden-skills/ ├── README.md ├── frontend/ │ ├── troubleshooting/ │ ├── how-to/ │ └── cheatsheet/ ├── backend/ │ └── troubleshooting/ ├── engineering/ │ └── how-to/ ├── tools/ │ └── cheatsheet/ └── inbox.mdinbox.md 是临时落点所有随手记录先放这里每周整理一次。这个文件最容易被忽略但非常重要——它保证了“快速捕获”和“结构化沉淀”不冲突。没有 inbox你会为了保持目录整洁而抗拒记录有了 inbox你可以先记下来再做判断。注意目录不要建太深两层最多三层。超过三层检索成本会快速上升维护意愿会下降。2.2 技能卡片模板把一条经验变成可复用模块每条技能卡片建议包含以下字段标题直接写这个技能解决什么问题适用场景什么条件下用前置条件需要什么环境、依赖、权限操作步骤按顺序列验证方式怎么确认成功已知坑点容易踩的问题替代方案什么时候不选它模板示例# 技能排查 GitHub Actions 工作流失败 - 适用场景push 后 workflow 没有执行或执行失败 - 前置条件仓库有 Actions 权限workflow 文件在 .github/workflows 下 - 操作步骤 1. 打开仓库 Actions 页面找最近一次 run 2. 展开失败 job查看具体 step 日志 3. 确认触发分支和触发事件是否匹配 - 验证方式修复后新 commit 能触发同一 workflow 并通过 - 已知坑点本地能跑的命令不一定能在 Actions 里跑环境变量和依赖源都要单独确认 - 替代方案先在本地用 act 模拟再提交远端写作时有一个原则先写验证方式再写步骤。因为不写清楚“怎么算成功”步骤很容易被人跳过然后继续踩同样的坑。另一个原则每张卡只解决一个问题。一个问题拆成多张卡比一张卡塞进三个问题更容易维护。2.3 从随手记到正式卡片的输入流程我的流程是遇到问题 → 先写入 inbox.md → 当天或本周挑一条转成卡片 → 发布或同步到 README。注意不是所有内容都要转卡片。只有满足两个条件才值得转它花了你至少半小时解决你有把握在未来三个月内还会遇到同类问题。否则留在 inbox 就行等它被再次遇到再说。注意不要把“以后可能会看”的内容直接建卡。技能卡必须服务于一个具体场景否则三个月后你根本不知道它该用在哪个问题上。这里最容易出问题的是“当日热修”。问题解决时最有动力记录但也最容易写得很碎比如只记了一句“改了参数就好了”。我的做法是当时只补三条——现象是什么、改了什么、怎么验证后续如果真的还要碰再补完整步骤。这样热修不会打断工作流也不会留下不可用的废卡。3. 可复用性的关键标签、索引和定期修剪内容一旦多起来最怕的不是没有人看而是找不到、不信任。可复用性主要靠三件事维持目录管归属标签管交叉修订管时效。这一节拆开讲。3.1 标签不是越多越好目录解决的是“这件东西放在哪”标签解决的是“哪些内容互相有关”。标签数量建议控制在 20 个以内并且每个标签必须有明确含义。最忌讳的是同一个意思建多个标签比如“前后端”和“全栈”并存、“部署”和“发布”并列检索时反而更难命中。举个例子如果你有三条卡片分别讲前端资源压缩、图片格式选型、接口缓存策略它们都属于“性能优化”但这个标签会和前端、后端、工具三个目录交叉。这种情况下“性能优化”标签才是合理的而不要建“前端性能”“后端性能”“工具性能”三个标签那样标签就失去了交叉检索的意义。写卡片时我一般会顺手维护一个 tags 索引页把所有标签和对应卡片列出来。这个索引页可以手动维护也可以在提交时用脚本生成。手动维护成本低适合内容少的情况脚本生成适合内容多的仓库。对于单张技能卡建议每张最多 3 个标签。标签越少越容易保证一致性。如果你发现自己给一张卡贴了 6 个标签大概率是这张卡本身混进了多个问题应该拆分。3.2 定期修剪比持续新增更重要知识库和花园一样只种不剪最后会杂草丛生。我建议每季度抽一个下午做三件事把全部卡片扫一遍标记内容已经过期的把超过一年没有被更新的卡片合并或删除检查是否有两条卡片解决同一个问题有则合并。这个动作很难坚持但它是仓库能否长期有用的分水岭。修剪时可以把过期内容移动到 archive 目录而不是直接删除。archive 保留原始记录正式目录保持干净两边都不难受。如果 archived 的内容连续两个季度没人再碰再决定删除。很多人仓库废掉不是因为没有内容而是因为旧内容和新内容互相矛盾最后谁都不敢引用。修剪时如果拿不准我的判断标准是这条记录如果今天消失会不会影响你接下来的工作如果不会就删或合并如果会就更新它。仓库的价值不在于条目数量而在于每一条都被信任。4. 发布链路的搭建从 Markdown 到可访问页面内容写完后下一步是发布。个人仓库最简单的方式是用仓库页面直接浏览 README 和卡片目录。缺点是目录一多阅读体验就下降。进阶一点可以引入一套自动化Markdown 源文件 → 检查 → 生成索引和站点 → 部署到 GitHub Pages 或自己的博客系统。自动化能省时间但要在正确的时候引入。我的建议是先把本地路径跑通再写 CI否则你会同时面对内容和构建两个问题很难判断报错来自哪里。4.1 一套够用的 GitHub Actions 发布流程发布链路不要一开始就搞复杂。下面这个 workflow 是一个很基础的示例推送 main 分支时先检查 Markdown 链接再生成站点到 gh-pages 分支。它只做一件事逻辑很清晰。你可以按自己的站点生成方式替换 build 部分。name: publish on: push: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Run link check run: make check - name: Build site run: make build - name: Deploy uses: peaceiris/actions-gh-pagesv4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist这里用的是常见动作版本号只是示例实际使用时以你确认的版本为准。第一次跑最容易遇到的是路径问题——比如构建产物不在 ./dist或者 make 命令在仓库根目录找不到。先看日志里的工作目录再改路径不要猜。注意第一次跑 Actions先看日志里的 working directory 和文件路径不要直接改构建命令。手动改配置容易把原本能跑的部分也搞坏。至于端口、域名、CDN 这些只有浏览量上来了才需要考虑。前期不需要为性能做任何优化。4.2 如何验证发布链路正常判断发布链路是否正常不只看页面能不能打开。我一般按这个顺序验证push 后 Actions 是否进入 run三分钟内是否变成绿色打开部署后的网址看首页索引是否更新点进其中一条卡片确认链接、代码块、目录都能用再检查旧链接有没有因为重构而失效。如果页面是空白先看构建日志里有没有成功提示再看 dist 目录是否生成了 index.html最后才怀疑部署插件。顺序不要反过来直接改代码往往改不到点上。同步策略也值得提前想。内容源只有一个其他位置都通过构建生成不要手动复制到博客或公众号。手动同步多了数据源就不唯一后面对不齐是必然的。5. 常见坑点与排查顺序这类仓库在搭建和维护过程中总会遇到几个看起来很奇怪的问题。这一节列出我踩过或看别人踩得最多的四类。5.1 写了很多内容但还是搜不到这个问题通常不是搜索引擎的问题而是标题和文件命名的问题。如果每条卡片都叫 01.md、test.md搜索引擎和读者都不知道它讲什么。我一般建议文件名直接使用有意义的小写连字符比如 frontend/troubleshooting/github-actions-path-error.md。这样不用打开文件光看目录就知道这条内容覆盖什么。标题也一样。不要写“关于 Actions 的笔记”这种标题要写“GitHub Actions 路径错误排查”。标题里带上主词内容里在开头重复一次这样无论是读者浏览目录还是搜索引擎收录都能快速命中。5.2 仓库越维护越乱核心原因是什么大部分情况是“数据源不唯一”。笔记里存一份、博客里存一份、仓库里再存一份同一份内容改了三处最后互相矛盾。解决办法是确定单一事实来源以一个目录为唯一内容源其他位置都通过同步或引用生成。同步可以由 CI 完成但前提是源目录稳定、命名规范。如果你发现自己在两个地方手动维护同一份内容就该停下来想想哪个是源哪个是产物。产物只读不能手动改。这个原则比任何自动化工具都重要。5.3 不要在内容还没成型时做自动化我看到最多的失败模式是仓库刚建好先花三天配自动部署、主题、评论系统结果一条卡片都没写。自动化的价值建立在内容稳定、目录稳定的前提下。内容还在频繁变动时做自动化只会让每次改动都要处理构建问题。我的建议是先写内容跑通一条手动发布路径再考虑要不要加 Actions。判断时机很简单——当你连续三次发布都只是复制文件到部署目录、开始觉得机械重复时就是引入自动化的时机。5.4 通用排查顺序如果遇到工作流执行失败、构建报错、页面没更新我一般按这个链路排查先看日志确认失败发生在哪一步再看输入路径和工作目录确认文件真的存在再确认依赖版本和权限比如 Actions 是否允许写入 gh-pages最后才怀疑配置写法。先改参数而不看日志是最浪费时间的做法。这套顺序也适用于很多其他工具。先看现象、再查输入、再查环境、最后查参数基本上能覆盖 90% 的“看起来像是软件坏了”的问题。6. 我的实战建议从最小编成开始别搭完美系统最后给一套可以立刻执行的启动方案。不要模仿别人仓库的全部功能只需要取对自己有用的那部分。6.1 最小启动方案如果你也想做一个 garden-skills 这样的技能库我建议第一周只做四件事新建一个空仓库创建 README.md 和 inbox.md定义一张技能卡片模板写下三条真实经验哪怕每条只有几行。三条经验最好包含一个典型故障、一个常用命令、一个流程步骤。不要在第一周写标签体系不要配评论系统不要迁移旧笔记。旧笔记最晚再迁移先把新经验跑顺。这个方案的目的是让你尽快经历一次“记录→整理→复用”的完整闭环。没有闭环功能加得再多也只是摆设。6.2 后续演进路径当仓库里有了 10 条左右卡片并且你已经遇到过“需要回去找一条旧经验”的场景再考虑加这些功能issue 模板让读者可以直接提“这个技能失效了”标签索引页自动链接检查博客同步或页面发布。每一步都以实际需求为触发条件不要提前堆功能。这时的重点是定期复盘。我一般每个月扫一次 inbox每个季度修剪一次正式卡片。复盘时只问三个问题最近哪些卡片被用到过哪些内容过时了下周最值得新写的是什么回答完这三个问题比打开编辑器硬写更能产出好内容。6.3 什么时候停止优化停止优化的标准很明确当新增一条卡片不超过 10 分钟检索一条旧经验不超过 3 步每次发布或同步不超过 5 分钟时系统已经够用了。继续优化的边际收益很低。这之后更应该把时间花在写内容、修技术债和读别人的技能库上。踩过几次之后我发现garden-skills 这类项目最值得学的不是架构也不是工具链而是“让一条经验保持可复用状态”的能力。仓库只会越写越厚但如果每一条都能被检索、被信任、被复用这个仓库才算真正长出东西来。