一句话总结

好的 AI Coding Skill = 配置外置 + 工作流闭环 + 占位符解耦。本文以真实 Skill 的 5 次迭代为线索，展示如何把一个”能用”的脚本变成一个”谁拿过去改一行配置就能用”的独立 Skill。

问题背景

我在做什么

在 Hexo 博客项目中维护一个 knowledge_record Skill——它能在我和 AI 对话结束后，自动萃取对话中的技术知识点，生成结构化的博客文章（模板化），预览后一键发布到线上。

遇到了什么问题

第一个版本”能用”但迁不走：

  • 所有路径写死了 d:/Blog/source/_posts，换台机器就崩
  • 跨平台不兼容——Windows 的 del 命令到 Linux 直接报错
  • 发布命令 hexo clean && hexo generate && hexo deploy 散落在 skill.md 的 3 个地方，改一处忘一处
  • 工作流不闭环：能生成能发布，但忘了加预览确认和删除环节

复现

把整个 skills/knowledge_record/ 文件夹拷贝到另一台 Mac 上——技能直接不可用。

AI 分析过程

AI 的定位思路

本对话中，AI 做了 3 轮全局扫描：

  1. 全量收集：用 launch_subagent 并行读取 _config.yml、CNAME、config.json、skill.md、template.md、README.md、examples/、source/ 目录
  2. 交叉对比：发现 config.json 的 posts_dir 和 skill.md 中硬编码的 source/_posts/ 不一致
  3. 逐项消歧：用 grep_search 搜索所有残留的硬编码路径和命令

关键发现

问题 根因 影响
路径硬编码 skill.md 直接写了 d:/Blog/source/_posts/ 换个盘符就崩
跨平台不兼容 del /f /q 是 Windows 专属 Linux/Mac 报错
命令散落 发布命令在 skill.md 里出现 3 次 改一处漏一处
工作流缺失 没有预览→确认环节，没有删除流程 安全感和控制感差

涉及的技术概念

  • {key} 占位符模式：skill.md 中用 {source_dir} {posts_dir} 等占位符引用配置，运行时从 config.json 动态映射
  • Hexo 博客框架：基于 Node.js 的静态博客生成器，核心命令 hexo clean / hexo generate / hexo deploy
  • Skill 独立封装：将 trigger、workflow、template、config 打包为自包含目录，迁移时只改 config.json
  • Frontmatter：Markdown 文件的 YAML 元数据块（--- 包裹），Hexo 用它解析标题、日期、标签等

AI 解决方案

最终方案

不重写，用最小 delta 修改逐轮迭代，总共 5 轮对话完成：

轮次 触发 改动
第1轮 分析项目 修 _config.yml 的 url → 统一到 kukudelin.top
第2轮 “直接同步到博客” skill.md 增加 Step 发布 → 生成完自动 hexo deploy
第3轮 “让我预览+询问” 发布前插入预览→确认环节
第4轮 “要支持删除” 新增 Step D1~D4 删除流程 + 触发词
第5轮 “终检迁移” 全量 {key} 替换 + 交叉校验

核心原则：skill.md 是 immutable 的规则，config.json 是唯一可变配置点。

核心代码片段（如有）

config.json — 配置外置的关键：

1
2
3
4
5
6
7
8
{
  "hexo": {
    "source_dir": "d:/Blog",
    "site_url": "https://kukudelin.top",
    "posts_dir": "source/_posts",
    "deploy_command": "hexo clean && hexo generate && hexo deploy"
  }
}

skill.md — 工作流 Step 0（加载配置）：

1
2
3
4
5
6
Step 0：加载配置
读取 config.json，建立占位符映射表：
  {source_dir}    →  hexo.source_dir
  {posts_dir}     →  hexo.posts_dir
  {deploy_command}→  hexo.deploy_command
本 Skill 所有文件操作均使用占位符，绝不硬编码路径。

为什么这样做能解决问题

{key} 占位符的本质是接口抽象——就像面向对象编程中的 interface。skill.md 定义”我需要什么”，config.json 提供”当前环境下的具体值”。迁移到 Mac 时，只改 config.json 里的 source_dir 从 d:/Blog 到 /Users/xxx/blog，skill.md 一行不动。

跨平台问题上同理：hexo clean && hexo generate && hexo deploy 在所有平台都能跑，替代了 Windows 专属的 del /f /q。

本次知识萃取

显性知识

  • Hexo Skill 架构：trigger → config → workflow → template → output
  • {key} 占位符模式：skill.md 中用占位符引用配置值，config.json 提供映射
  • 跨平台 Shell：优先用框架命令（hexo clean）而非 OS 命令（del）
  • Frontmatter 规范：Hexo 需要 title/date/tags/categories 等字段

隐性知识

  • 最小 delta 原则：每轮迭代只改 1-2 处，改完立即验证，不搞大爆炸重构
  • 终检兜底：在声称”完成”之前，用 grep_search 全局搜索残留硬编码，防止口是心非
  • 预览→确认→发布三步闭环比全自动更能建立用户信任——“慢”即是快
  • 迁移测试是最好的设计审查：假装把 skill 拷贝到另一个环境，立刻暴露所有硬编码问题

关联知识

1
2
3
4
5
6
7
8
9
AI Coding Skill 设计
    ↓
配置驱动的 Agent 行为树
    ↓
LangChain / Semantic Kernel 的 Plugin 模型
    ↓
微服务配置中心 (Consul / Nacos)
    ↓
基础设施即代码 (IaC)

安全思考

本场景的安全考量：

  • 攻击面：Skill 自动执行 hexo deploy，如果 config.json 被篡改，可能推送到恶意仓库——需保护 config.json 的写入权限
  • DoS 风险：hexo generate 在文章量极大时可能 OOM——对于个人博客（< 200 篇）无影响
  • 权限问题：自动写入 source/_posts/ 目录，需确保目录权限正确
  • 数据泄露：对话内容被萃取到博客，需注意是否包含敏感信息（API Key、内部架构细节等）——本 Skill 由用户预览确认后才发布，已提供人工兜底

延伸学习路线

1
2
3
4
5
6
7
8
9
Hexo 博客搭建与基础命令 (hexo new, generate, deploy)
    ↓
AI Coding Skill 设计模式 — 本文
    ↓
Agent 工作流引擎 (LangGraph / Temporal)
    ↓
配置管理 (JSON Schema → 配置校验 → 配置中心)
    ↓
可观测性：给 Skill 加日志、metrics、tracing

面试视角

可能会怎么问

“你设计过一个可以从零迁移的 AI Coding Skill，具体是怎么做到环境无关的？”

你可以怎么答

回答框架（3 层递进）：

  1. 问题定义：说出硬编码的 3 个痛点——路径、平台、命令散落
  2. 设计决策：配置外置（config.json）+ 占位符（{key}）+ 规则不可变（skill.md），类比 interface/impl 分离
  3. 验证手段：迁移测试 + grep_search 终检——设计不是一次性完成的，是迭代修补出来的

核心金句：“skill.md 是 interface，config.json 是 impl，迁移就是换个 impl”。

我的收获

最大的认知 shift：“能用”离”可迁移”差着至少 3 轮迭代。第一版写完觉得好了，一拷到别处立刻暴露问题——路径硬编码、平台不兼容、命令散落、工作流缺失。这些问题在”原地”运行时永远不会暴露，只有当你强迫自己做迁移测试，才会发现。

还有一个意料之外的体验：让用户预览再发布，比全自动更能建立信任。全自动是”你相信我不出错”，半自动是”你随时可以阻止我”——后者反而让用户更放心地把流程交给 AI。