日常工作知识库

Appearance

AI Skill 生产级交付与持续维护框架指南 ​

在基于 Agent 架构（如 OpenClaw、Hermes、Claude Code 等）的大模型应用开发中，技能（Skill）是连接自然语言意图与底层物理能力的桥梁。本文档梳理 AI Skill 的上下文加载原理、交付包治理模型，以及生产级上线后的持续维护框架。

一、 AI Agent 技能加载与解析机制 ​

1. SKILL.md vs README.md 的优先级与作用域 ​

维度SKILL.md (面向 Agent/Machine)README.md (面向人类开发者/Human)
解析优先级唯一最高优先级完全不解析
加载时机两阶段加载（路由阶段读 Frontmatter，激活阶段读全量正文）仅在人类通过 Git/IDE 浏览时阅读
功能定位充当技能的 Manifest 配置与 System Prompt 指令约束提供本地安装说明、打包发布指南及 CLI 常用示例
上下文占用全量占用上下文 Window（正文越长，Token 消耗越高）0 占用

关键结论：在设计 AI Skill 时，切勿将针对大模型的控制规则写在 README.md 中。SKILL.md 是大模型理解并执行技能的唯一入口。

2. references/ 模块化文档的按需加载机制 ​

references/ 目录中的静态文档（如 troubleshooting.md、api-design.md）绝对不会被 Agent 默认自动全量装载，而是遵循以下分层加载模式：

  1. 普通/基线 Agent（无本地文件工具）：完全不读取。这类 Agent 仅接收 SKILL.md 的文本，没有读取磁盘文件的工具权限。
  2. 具备 File/RAG 工具的高阶 Agent（如 Claude Code/OpenClaw Agent）：按需（Lazy/On-demand）读取。
    • RAG 向量检索：平台对技能包建立了本地向量索引，遇到特定报错时自动检索相关片段。
    • Tool-Use 指引：SKILL.md 中明确写有 “如遇认证 500/mis_auth 异常，请调用 view_file 工具读取 references/troubleshooting.md” 的显式指令，Agent 才会发起读取。

架构收益：将抓包实证、长篇踩坑与日志分析抽离至 references/，使 SKILL.md 从几十 KB 瘦身至几 KB，为多轮 IM 对话常驻节省 80%+ 的 Context Window，大幅降低计费成本与注意力稀释。

二、 技能包治理与源码 vs 生产交付包隔离 ​

在工程实践中，必须严格区分 开发源码仓 (Source Repository) 与 生产交付包 (Production Distribution Bundle)：

text
源码仓 (test-skills/wuba-invoice-followup/) 
  ├── 包含完整测试用例 test_cases.json
  ├── 包含调试脚本与历史抓包
  └── 包含开发者 README.md
       ↓ 经过构建/剪裁脚本 (pre-publish-check)
生产交付包 (delivery-skills/wuba-invoice-followup-vX.Y.Z/)
  ├── 精简版 SKILL.md (<150 行)
  ├── 物理执行体 invoice_followup_skill.py
  ├── 模块化 references/ 索引
  └── 清理掉 __pycache__ 与冗余测试用例

冗余文件治理矩阵 ​

  • 核心必选：SKILL.md、invoice_followup_skill.py、_meta.json。
  • 按需保留：references/（知识沉淀与按需排障）、skills/（复合编排时的子技能声明）。
  • 生产包必须剔除：test_cases.json（测试用例）、usage.log（本地运行日志残余）、__pycache__（Python 编译缓存文件）。

三、 Skill 上线后的持续维护框架 (Continuous Maintenance) ​

为了确保线上技能在长周期迭代与扩展过程中的稳定性与健壮性，维护模式必须从 “体感维护（改完只要没报错就行）” 走向 “证据闭环维护（对输入、执行、触发和产出进行精准锚定）”。

1. 明确成功标准 (Success Criteria) ​

评估 Skill 质量不能仅看“代码是否 Crash”，需从四个维度综合把控：

  • 结果目标：业务任务是否准确完成（例如：进项税发票是否准确拉取，凭证是否严格满足 R1-R5 四维核对）。
  • 过程目标：执行路径验证（例如：鉴权失败时是否静默走降级指引，是否按规定先吐流式明细再倒查凭证）。
  • 风格与渲染目标：输出规范（例如：必须严格执行 Table-First 约束，全量使用 Markdown 表格结构化呈现）。
  • 效率目标：Token 成本与多余步骤（例如：SKILL.md 保持轻量，避免无谓的推理步骤）。

2. 诊断潜在失控点 (Drift and Failures) ​

实施 双维维护面分离 策略：

text
┌─────────────────────────────────────────────────────────────┐
│                   Skill 持续维护双维分离                     │
├──────────────────────────────┬──────────────────────────────┤
│ 维 1：执行体 (Python 代码)    │ 维 2：触发边界 (Prompt 描述) │
│ - 物理 API 网络交互           │ - 意图识别与选择             │
│ - 字段归一化与精确加减算术     │ - 参数格式强校验与拦截       │
│ - 分页降级与 Token 刷新       │ - 回复格式与 Table 渲染约束  │
└──────────────────────────────┴──────────────────────────────┘

诊断防范三类假想失控：

  • 触发假设失控：用户输入模糊简称（如“天津赶集”）时，Prompt 校验未拦截导致向接口发起了无效请求。
  • 环境假设失控：依赖的环境变量（如 MEISHI_USER_ID）缺失时脚本崩溃，未能给出降级修复引导。
  • 执行假设失控：执行体代码改动后孤立修改，导致触发范围无形漂移。

3. 构建回归测试集 (Regression Suite) ​

在技能包的 test_cases.json 中维护并定期自动化运行 4 类黄金测试用例：

  1. 显式调用样本：提供完整的精确 buyerName + sellerName，卡住业务规则基线。
  2. 隐式调用样本：仅提供口语化自然语言需求，测试 Agent 的意图识别与参数自动补全调度率。
  3. 带上下文调用：在输入中混入业务噪声与历史对话，测试 Agent 的识别韧性。
  4. 负样本（关键边界）：故意传入缺乏主体后缀的简称，验证 Prompt 是否能精准拦截并给出格式引导，而不是错误触发执行。

四、 总结与最佳实践 CheckList ​

  • [ ] 版本号 5 文件一致性：每次发布前确认 SKILL.md、invoice_followup_skill.py、CHANGELOG.md、README.md、_meta.json 版本号全量一致。
  • [ ] CLI 发布必须携带 --name：执行 wubahub publish . --slug <slug> --name "<中文名>" 避免市场展示英文默认名。
  • [ ] 物理与语义分离测试：代码变动跑 --self-test；Prompt 变动跑意图识别与负样本测试。