AI Coding 正在从“问答工具”演变成“执行工具”。早期我们用 AI 代码助手补全函数、解释报错、生成单元测试本质上还是一次性信息交换而现在AI Coding Agent 引入了 Skill 机制让工程师把自己沉淀的开发流程封装成可复用技能模型可以按固定步骤思考、调用脚本、生成文件、执行构建并汇总结果。对于真实工程师来说构建 Do Work Skill 解决方案就是把 AI 编程能力从“演示”变成“生产力”的关键一步。这篇文章从概念入手逐步搭建一个最小可运行的 Skill用一个开发任务验证闭环再讲清楚生产环境落地的排查方式与最佳实践。1. 先理解 Do Work SkillAI 编程从生成代码走向完成工作1.1 什么是 Do Work Skill“Do Work Skill”可以理解为一种按“完成任务”而不是“回答问题”来设计的 AI 技能单元。普通对话式 AI 编程是工程师给模型一个需求模型返回一段代码或一段解释再由人去复制、调整、集成。这个过程中人承担了大部分执行工作AI 更像一个文档和代码生成器。Do Work Skill 则不同。它把一套完整的工作流程封装成可加载的技能包括四个部分元信息描述这个 Skill 是干什么的、需要什么输入、会产出什么结果。执行步骤把任务拆成计划、生成、验证等阶段并规定每一步的输入输出。执行载体调用本地脚本、模板文件或工具命令来完成实际文件操作。验收规则执行结束后用构建命令、测试脚本或静态检查来判断结果是否合格。当 AI Coding Agent 加载了这个 Skill遇到匹配的任务时就不再是“给一段代码就结束”而是会进入一个可跟踪、可验证的执行流程。这是“Do Work”和“Chat”最本质的区别。1.2 Skill 机制解决的核心问题在不使用 Skill 的情况下让 AI 去完成一项稍微复杂的工程任务往往面临四个问题不一致同一个需求换一个模型或换一次会话产出的代码风格、目录结构、命名规范可能完全不同。不可验证模型给完代码就结束代码能否编译、测试能否通过没有闭环。不可复用每次都要重新把需求、规范、约束写一遍换个人协作又要重新解释。不可维护规范散落在若干次对话里团队无法统一更新。Skill 机制把“人怎么干活”翻译成“机器能执行的流程协议”。它解决的不仅是生成效率更重要的是执行的一致性和可审计性。团队可以把代码规范、模块生成方式、代码审查清单都沉淀到 Skill 里AI 每次执行时都遵循同一套规则。1.3 Skill 与普通 Prompt、代码模板的区别很多工程师会问我不用 Skill写一个长 Prompt 或者维护一套代码模板不也能达到类似效果吗答案是可以达到一部分但边界不同。对比维度普通 Prompt代码模板Do Work Skill触发方式每次手动输入工程师手动套用Agent 根据任务描述自动匹配执行过程模型自由发挥固定填充占位符步骤化执行可调用脚本和工具验证机制无无构建、测试、静态检查等硬校验复用粒度一次会话代码文件级完整流程级维护方式无版本概念模板文件版本控制独立目录可版本化、可评测普通 Prompt 适合解决一次性的问题代码模板适合解决固定结构的代码输出而 Do Work Skill 适合解决“从需求到可运行产物”的完整流程。实际项目中这三者并不冲突Skill 内部可以引用模板也可以包含 Prompt 片段但 Skill 多了一层“执行协议”这是关键差异。2. 搭建 Skill 运行环境工具链、目录和第一份配置2.1 准备最小学习环境构建和验证 Skill 不需要重型基础设施先准备一个最小环境即可。需要准备的内容包括一台安装了 Python 3 或 Node.js 的开发机用于运行 Skill 内的辅助脚本。一个支持本地目录读取、工具调用和自定义 Skill 机制的 AI Coding Agent。不同工具叫法不同有的叫 Skill有的叫 Rule本质上都是“给 Agent 一段结构化的运行指令”。一个 Git 仓库用于管理 Skill 的版本变更。一个用于测试的最小示例项目避免直接在真实项目上做实验。初始化目录mkdir -p do-work-skill/{scripts,templates,examples} cd do-work-skill git init python --version node --version这里有一个很容易忽略的点Skill 里的脚本最终要交给 Agent 在本地执行所以开发机上的 Python、Node 版本、可执行文件路径都要提前确认。如果 Agent 运行在容器或远程环境里脚本运行环境还需要与 Skill 的声明保持一致。2.2 选择支持 Skill 的 AI Coding Agent不同 AI Coding Agent 对 Skill 的支持程度不一样。选择时需要重点确认几个能力是否支持从本地目录加载自定义技能或规则。是否能执行本地命令比如运行 Python 脚本、执行构建命令。是否能读取工作目录下的文件并写入新文件。是否允许通过配置文件声明技能目录。是否有日志或回放机制便于定位执行问题。可以用下面的问题清单做快速评估评估维度需要确认的点不满足时的折中方案技能加载是否支持指定技能目录退化为通过系统 Prompt 注入流程命令执行是否允许运行白名单命令用脚本生成结果人手工执行文件权限能否读写指定工作区限制在独立沙箱目录内操作日志回放是否记录工具调用过程手动记录脚本输出和退出码需要提醒的是不要只看模型本身的能力还要看 Agent 壳层的工程能力。同一个模型在不同 Agent 工具里的执行力差异很大。判断标准是它能不能稳定地按步骤调用工具而不是偶尔成功一次。2.3 设计 Skill 目录与命名规则一个技能对应一个目录目录内部有固定的组织方式。推荐下面这种结构do-work-skill/ ├── SKILL.md ├── scripts/ │ ├── plan.py │ ├── scaffold.py │ └── verify.py ├── templates/ │ └── module.tpl └── examples/ └── demo-task.json命名规则建议统一使用 kebab-case目录名与 Skill 名称保持一致。SKILL.md是整个技能的唯一入口Agent 会优先读取它。scripts存放可执行脚本templates存放文件模板examples存放示例输入和期望输出。目录结构设计的目的是让“人维护技能”和“Agent 执行技能”都变得可预期。后续做评测、版本对比、团队共享时这个结构也能直接复用。3. 构建一个最小可运行 Skill模块生成器3.1 SKILL.md先让 Agent 知道这个 Skill 怎么用SKILL.md是技能的大脑。它告诉 Agent 三个核心信息什么时候用这个技能、需要什么输入、按什么步骤执行。下面是一个模块生成器的元信息示例name: module-generator description: 根据需求描述生成后端模块骨架并运行构建与测试验证。当用户要求生成新功能模块或新服务时使用。 version: 1.0.0 author: engineering-team inputs: - name: module_name description: 模块名称使用 kebab-case required: true - name: requirement description: 功能需求描述 required: true - name: out_dir description: 输出目录 default: ./work steps: - name: plan script: python scripts/plan.py task.json plan.json description: 解析需求生成实现计划 - name: scaffold script: python scripts/scaffold.py plan.json description: 根据计划生成模块代码 - name: verify script: python scripts/verify.py plan.json description: 执行构建和测试输出验证报告 verification: - 构建命令必须成功 - 至少包含一个可运行的测试用例 - 生成的入口文件必须存在 safety: - 禁止删除工作区外的文件 - 禁止执行未在 steps 中声明的命令写SKILL.md时有三个关键点。第一description要写清楚“什么时候用”。Agent 的任务匹配主要靠描述与用户意图的相似度。描述太泛无关任务也会触发描述太窄真实需求又匹配不上。第二steps要写清楚“每一步干什么”。每一步的脚本都要接受明确输入、产生明确输出这样才能被下一步消费。第三verification是 Skill 有没有完成工作的硬标准。没有验收规则Skill 就是一个高级 Prompt。3.2 执行脚本把工作拆成可独立验证的步骤模块生成器包含三个脚本分别对应计划、生成、验证三个阶段。先看计划脚本scripts/plan.py。它的职责是读取任务输入检查必要字段生成一份实现计划# scripts/plan.py import json import pathlib import sys def load_json(path): with open(path, r, encodingutf-8) as f: return json.load(f) def save_json(path, data): with open(path, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2) def main(): if len(sys.argv) 3: print(usage: python plan.py task.json plan.json, filesys.stderr) sys.exit(1) task_path, plan_path sys.argv[1], sys.argv[2] task load_json(task_path) module_name task.get(module_name, ).strip() requirement task.get(requirement, ).strip() if not module_name or not requirement: print(error: module_name and requirement are required, filesys.stderr) sys.exit(1) plan { module_name: module_name, requirement: requirement, out_dir: task.get(out_dir, ./work), steps: [create_module_dirs, write_entry_files, write_tests], } save_json(plan_path, plan) print(json.dumps({status: ok, plan: plan_path}, ensure_asciiFalse)) if __name__ __main__: main()这个脚本做了三件事校验输入是否完整、把需求整理成结构化计划、把计划落盘。它的核心价值不是生成代码而是把“模糊需求”变成“可执行的结构化任务”。再看生成脚本scripts/scaffold.py它读取计划文件按照计划创建模块目录和入口文件# scripts/scaffold.py import json import pathlib import sys def load_json(path): with open(path, r, encodingutf-8) as f: return json.load(f) def main(): if len(sys.argv) 2: print(usage: python scaffold.py plan.json, filesys.stderr) sys.exit(1) plan load_json(sys.argv[1]) module_name plan[module_name] out_dir pathlib.Path(plan[out_dir]) / module_name (out_dir / src).mkdir(parentsTrue, exist_okTrue) (out_dir / tests).mkdir(parentsTrue, exist_okTrue) entry out_dir / README.md entry.write_text( f# {module_name}\n\n需求: {plan[requirement]}\n, encodingutf-8, ) print(json.dumps({status: ok, module_path: str(out_dir)}, ensure_asciiFalse)) if __name__ __main__: main()最后是验证脚本scripts/verify.py。它可以检查生成的目录和文件是否满足验收规则# scripts/verify.py import json import pathlib import sys def load_json(path): with open(path, r, encodingutf-8) as f: return json.load(f) def main(): if len(sys.argv) 2: print(usage: python verify.py plan.json, filesys.stderr) sys.exit(1) plan load_json(sys.argv[1]) module_path pathlib.Path(plan[out_dir]) / plan[module_name] checks { entry_exists: (module_path / README.md).exists(), src_dir_exists: (module_path / src).is_dir(), tests_dir_exists: (module_path / tests).is_dir(), } failed [name for name, ok in checks.items() if not ok] if failed: print(json.dumps({status: failed, failed_checks: failed}, ensure_asciiFalse)) sys.exit(1) print(json.dumps({status: passed, checks: checks}, ensure_asciiFalse)) if __name__ __main__: main()这里的设计意图是生成脚本只负责产出验证脚本只负责判活。两步分离之后无论生成逻辑怎么变验收标准都是稳定的。真实项目里verify.py可以替换为mvn test、pytest、go test等真实构建命令也可以同时跑静态检查和单元测试。3.3 模板文件与示例任务模板文件templates/module.tpl用于定义生成文件的固定结构。这里的写法是简单占位符风格真实项目可以换成 Jinja2、Go Template 等更强模板引擎# {{ module_name }} ## 功能说明 {{ requirement }} ## 目录结构 src/ main code tests/ unit tests ## 验证命令 python -m pytest tests/对应的示例任务examples/demo-task.json{ module_name: order-service, requirement: 提供订单查询接口支持按订单号查询订单基本信息, out_dir: ./work }模板的价值是约束格式示例任务的价值是提供最小回归用例。每次修改 Skill都应该先跑一遍示例任务确认流程没有被破坏。3.4 注册和加载 Skill加载方式取决于你使用的 AI Coding Agent。常见的方式是在 Agent 的配置文件中声明技能目录skills: - path: ./do-work-skill enabled: true不同工具的配置字段和加载机制可能不同。落地前必须先查看对应工具的支持文档确认字段名。如果工具不支持从本地目录加载技能可以退而求其次把SKILL.md的内容通过系统提示词注入但这种方式会丢失脚本调用能力只能作为临时方案。加载完成后可以做一个最简单的连通性测试直接向 Agent 提问“你有哪些可用技能”看它能否正确列出module-generator及其描述。能列出来说明元信息加载成功。4. 用真实任务跑一遍验证 Skill 确实“能干活”4.1 输入一个带验收标准的任务运行 Skill 之前先明确任务和验收标准。这里使用示例任务{ module_name: order-service, requirement: 提供订单查询接口支持按订单号查询订单基本信息, out_dir: ./work }验收标准可以拆成三条模块目录./work/order-service被创建。模块内包含src、tests目录。模块内包含入口文件README.md内容包含需求和模块名。把任务交给 Agent 时建议直接引用技能名称例如“使用 module-generator 技能处理这个任务”。这样可以减少匹配抖动先把链路跑通。等确认稳定后再测试不指定技能名、由 Agent 自动匹配的方式。4.2 执行过程的关键检查点一个健康的执行过程会经历以下阶段Agent 读取SKILL.md确认使用module-generator。Agent 解析任务输入调用plan.py生成plan.json。Agent 调用scaffold.py创建目录和文件。Agent 调用verify.py检查产物是否符合验证规则。Agent 汇总输出报告执行结果。每个阶段都要有检查点检查点预期结果失败信号技能加载Agent 识别出 module-generator未触发技能直接生成未经确认的代码计划生成plan.json 存在且字段完整脚本报错缺少 module_name文件生成目录和入口文件存在文件写到错误路径验证通过verify.py 返回 status passed返回 failed 或非零退出码结果汇总Agent 明确报告成功与产物路径只贴了输出没有确认验收结果4.3 结果解读与失败回放正常运行后你应该能在./work/order-service下看到完整产物work/ └── order-service/ ├── README.md ├── src/ └── tests/验证脚本的输出类似{ status: passed, checks: { entry_exists: true, src_dir_exists: true, tests_dir_exists: true } }如果失败不要只看最后一句错误。应该按顺序做回放检查任务输入是否完整检查plan.json内容是否符合预期手动单独运行出错的脚本确认脚本本身是否有问题。脚本工具链的排查和普通 CI 流水线的排查思路完全一致定位到具体一个步骤再定位到具体一条命令。5. 设计决策和参数取舍为什么这样构建 Skill5.1 步骤化而非一次生成构建 Skill 时最容易犯的错误是让 Agent 一次生成所有目标文件。这样做的问题有两个上下文长度压力大生成代码越多越容易出现细节裁切和前后不一致。一旦后续验收失败无法定位是哪一步产生了问题。所以推荐把流程拆成“计划、生成、验证”三个独立步骤。每个步骤都有独立的输入文件和输出文件。这样既便于 Agent 理解也便于工程排查。真实项目中步骤还可以进一步拆分比如增加“代码审查”“数据库迁移检查”“接口文档生成”等阶段。5.2 输出到目录而不是输出到聊天窗口Do Work Skill 的一个重要设计原则是让 Agent 通过脚本把产物写入工作区而不是在对话里返回代码块。原因很简单写入文件后人可以查看、修改、对比、回滚代码块粘贴进编辑器后这些工程能力全部丢失。而且脚本执行会留下明确的文件路径和时间信息审计时有据可查。建议所有 Skill 都强制使用独立输出目录比如./work/或.ai-skill-output/。这样不仅避免了污染现有代码库也让“清理本次生成结果”变成一个简单的目录删除操作。5.3 验证前置没有验收标准就不算完成Skill 的执行结果必须对应到可检查的验收条件。这里有一条建议先写验收标准再写生成逻辑。如果验证规则是“构建命令必须成功”那么每个被 Skill 生成的模块都要能通过该命令。如果验证规则是“至少存在一个测试用例”那么生成逻辑里就要包含测试文件。验证规则反过来约束生成逻辑才能形成闭环。5.4 权限、安全边界和上下文约束Skill 拥有工作区文件读写的权限时必须明确安全边界。下面这些参数建议在SKILL.md或 Agent 配置里显式声明参数推荐默认值调小的影响调大的影响工作区范围当前项目目录无法访问依赖全局配置可能影响仓库外文件风险增加允许执行命令白名单python、git、构建命令限制灵活度误执行风险增加输出 token 上限按工具默认值长文件生成可能截断上下文占用增加成本上升最大执行步骤依据任务复杂度复杂任务流程中断步骤多时更容易累积错误建议所有 Skill 的执行限制在独立工作区内禁止访问工作区外的绝对路径。脚本中宁可多做路径校验也不要依赖模型自觉。注意Skill 的脚本和本地命令一样生产环境需要做白名单控制。不要允许 Agent 执行任意命令只允许执行 Skill 中显式声明的命令。6. 常见问题与排查路径6.1 常见问题速查表在实际使用中最容易碰到的问题集中在技能匹配、脚本执行、环境差异三类。可以按下面的表快速定位问题现象可能原因检查方式处理建议技能未触发description 不清晰或输入任务与描述不匹配查看 Agent 是否能列出技能命名和描述改写 description增加触发词和场景示例脚本执行失败Python 依赖缺失或路径不对手动运行python scripts/plan.py补充 requirements 或改为纯标准库脚本生成文件不在预期目录相对路径基于 Agent 的工作目录变化打印os.getcwd()和最终路径统一使用绝对工作区根目录或显式传入 out_dir生成结果被截断上下文或输出 token 限制检查 Agent 日志中的输出长度拆小任务或调整输出 token 上限验收永远失败验证规则与生成逻辑不一致对比 verify 脚本与 scaffold 脚本的产物假设先改生成逻辑再改验证规则危险命令被拒安全策略阻止了命令查看 Agent 工具调用日志将命令加入白名单而不是放开全部权限6.2 按链路排查当问题无法一眼定位时按照下面的顺序逐层排查输入是否正确任务文件是否存在字段名是否与脚本一致。技能是否加载Agent 是否正确读取了SKILL.md里的步骤说明。脚本是否可执行在终端手动运行脚本确认退出码和输出。输出产物是否完整检查目录、文件、关键内容是否存在。验证逻辑是否合理验证规则是否与生成逻辑一致。日志是否明确Agent 的工具调用日志、脚本 stdout 和 stderr 是否记录了关键信息。排查时最忌讳直接修改脚本重试那样容易掩盖真实问题。先手动把每一步跑一遍确认边界在哪里再改代码。6.3 环境差异排查本地能跑通的 Skill换到 CI 或生产容器可能失败。常见差异包括Python 版本不同脚本语法不兼容。构建工具未安装或版本不一致。文件系统权限不同脚本无法写目录。网络环境变化依赖下载失败。工作目录结构不同相对路径解析出错。解决方式是在 Skill 里明确声明所需环境并用requirements.txt、.nvmrc、Dockerfile等文件固化运行时。环境检查脚本也建议放进scripts/执行前先跑一次健康检查。7. 学习环境和生产环境的差异7.1 两套环境的关键差异学习环境可以追求“快速跑通”生产环境必须追求“稳定可追踪”。两者的差异集中在下面几个维度维度学习环境生产环境配置硬编码在脚本里外置到配置文件或环境变量日志打印到终端结构化日志统一收集权限本地用户权限最小权限命令白名单回滚手动删除目录产物版本化可一键回退评测手动验证回归数据集自动评测监控无执行成功率、耗时、失败原因统计成本少量 token用量预算和速率限制7.2 生产化必做清单进入生产环境之前下面这些项必须逐条确认技能目录纳入 Git 管理提交变更走代码评审。脚本运行环境用统一镜像或依赖锁文件固定。所有输出目录在工作区范围内禁止跨越边界。Agent 工具调用有日志审计能追溯每一步执行内容。关键技能配置了回归测试修改后自动跑示例任务。命令执行采用白名单策略未声明命令一律拒绝。设置了 token 和资源用量上限防止异常任务消耗过多资源。失败时有明确告警和重试或终止策略。注意生产环境不是越大越好。一个 Skill 能完成的职责越单一越容易验证、拆解和替换。把多个大流程塞进一个 Skill会把排查成本翻倍。8. 扩展方向从单个 Skill 到 Skill 资产库8.1 构建可复用的 Skill 资产库当团队积累的 Skill 越来越多就值得建一个统一的资产仓库按类别组织skills/ ├── code-review/ # 代码审查技能 ├── module-generator/ # 模块生成技能 ├── migration-check/ # 数据迁移检查技能 ├── api-doc-generator/ # 接口文档生成技能 └── README.md # 使用说明与分类索引技能资产库的价值在于开发流程可以被当作产品来维护。每个 Skill 有版本、作者、更新说明、依赖关系和示例任务团队新人可以直接复用不需要重新理解整套流程。8.2 建立评测集与回归验证要保证 Skill 在迭代过程中不退化需要一组“黄金任务”每个任务都包含输入、期望输出和验收规则。任何 Skill 变更都必须重新跑一遍黄金任务集。评测集不追求数量多而追求覆盖典型场景和边界情况。例如模块生成器至少包含三个任务正常模块生成、字段缺失报错、输出目录已存在。每个任务都应当有稳定的退出码和输出结果用于自动比对。8.3 团队协作与版本治理Skill 的变更会直接影响 AI 的执行结果所以要按代码变更的标准来治理。Skill 目录使用 Git 管理每个变更单独提交。SKILL.md中维护版本号重大变更更新版本。变更必须配套更新示例任务和验证脚本。团队共享 Skill 时使用固定的版本 tag避免成员之间配置漂移。废弃的 Skill 标记 deprecation 信息不要直接删除保留迁移路径。实际项目中最值得投入的不是让模型变得更强而是让已验证过的流程能够稳定地复用。Do Work Skill 解决的就是这个问题它把一次性的个人经验和零散的 AI 对话变成团队共享、可验证、可演进的工程资产。先从一个最小模块生成器开始跑通闭环再逐步把代码审查、测试生成、发布检查这些高频流程沉淀成技能是这一方案中最稳妥的演进路径。