AI编程助手Skill实战：用自然语言一键生成流程图

最近 AI 编程助手都在聊 skill 这个概念。Claude Code 有 skillCodex 有 skill连 OpenCode 这类开源 Agent 也开始支持。skill 的实际价值不在于多了一个配置文件而是把“每次都要重复叮嘱 AI 的提示词”固化成了可复用的能力。今天我们看的这个 skill主题很聚焦让 AI 根据自然语言描述直接生成流程图省掉手搓绘图的环节。先说痛点。以前画流程图要么打开 draw.io 或者 ProcessOn 手动拖拽要么写 Mermaid 语法然后反复渲染调试。手动拖拽的问题是改一次逻辑就要重新对齐箭头和节点写 Mermaid 的问题是语法细节多方向、分组、连线样式一多就乱。现在有了 skill我们可以把“生成流程图”这个任务交给 Agent直接说“帮我画一个用户登录的流程图”AI 会按约定好的格式输出可渲染的流程图文件我们再导入 Typora、飞书或者 draw.io 就能直接用。这篇文章会讲清楚三件事skill 是什么为什么适合流程图生成这种场景。怎么在自己本地的 Agent 环境里安装并配置这个 skill。怎么用自然语言快速生成不同类型的流程图以及批量生成和接口化改造怎么做。如果你已经在用 Claude Code 或 Codex并且经常要写文档、画业务流程、梳理算法逻辑这篇文章可以直接收藏。1. 核心能力速览能力项说明项目类型Agent skill 配置包用于让 AI 自动生成流程图主要功能自然语言描述生成流程图、流程优化建议、多格式导出支持的流程图类型业务流程图、算法流程图、系统架构流程、状态流转图依赖环境Claude Code、Codex 或 OpenCode 等支持 skill 机制的 Agent硬件门槛无特殊 GPU 要求纯 API 调用或本地小模型即可显存占用不涉及本地大模型推理时显存占用为 0启动方式将 skill 文件放入指定目录通过对话触发是否支持 API支持skill 本身可被 Agent 工具调用也可改造为 HTTP 接口是否支持批量任务支持可配合脚本批量生成多个流程文件适合场景需求文档编写、技术方案设计、算法讲解、课程制作从表格可以看出这个 skill 的门槛不在硬件而在环境配置。你只要有一个能跑 Agent 的机器能联网调用模型 API就能跑起来。2. 适用场景与使用边界流程图 skill 适合以下几类人。第一类是后端工程师。画调用链流程图、微服务交互图、定时任务状态机时以前要在 draw.io 里拖半天现在直接用文字描述AI 生成 Mermaid 或 PlantUML 代码渲染出来基本能看清结构。第二类是算法工程师。比如要解释反向传播算法的工作流程如果手绘从输入层到隐藏层再到损失函数还要标出梯度回传方向画起来非常费劲。用 skill 可以直接描述“画一个反向传播流程图包含前向传播、损失计算、梯度计算、参数更新四个阶段。”AI 会生成结构完整的流程图。第三类是技术文档写作者。这类人经常要画用户管理模块流程图、支付流程、订单状态流转图。skill 的价值在于让 AI 理解流程中的判断分支和异常分支并把这些分支用规范符号表达出来。边界也很明显。如果你要画的图是高度定制化的 UI 原型图skill 并不合适建议用专门的原型工具。如果流程图包含大量手绘风格的箭头、颜色、排版微调skill 生成的代码还需要二次修改。如果描述本身不清楚AI 生成的流程图也会混乱。skill 不能替代需求分析它只能帮你把想清楚的内容快速可视化。合规方面需要提醒如果流程图涉及公司内部业务逻辑、用户数据流转、核心算法流程发布或外发前务必确认脱敏和信息安全边界。用于技术文章或课程时也应避免泄露真实系统的敏感细节。3. skill 流程图环境准备与前置条件在安装这个 skill 之前需要先确认本机环境满足以下条件。3.1 Agent 环境skill 的宿主是 Agent 工具。当前比较主流的有Claude CodeAnthropic 官方命令行工具。CodexOpenAI 出品的命令行编程工具。OpenCode开源终端 Agent。不同 Agent 对 skill 目录的约定不完全一样。一般流程是在项目目录下创建.claude/skills/或~/.codex/skills/文件夹把 skill 描述文件和参考文件放进去。具体路径需要以你使用的 Agent 版本为准不确定就先ls -la看一下现有目录结构。3.2 模型 APIskill 本身不包含模型它只是给大模型提供了一套更规范的任务执行指令。因此你需要能访问一个支持工具调用或代码生成的模型服务比如 OpenAI 兼容接口、Anthropic 接口或者本地部署的 Qwen 等模型。如果走本地部署建议显存不低于 6G但实际表现取决于模型大小不能一概而论。3.3 环境变量大多数 Agent 通过环境变量读取 API Key。以 OpenAI 兼容服务为例至少需要配置export OPENAI_API_KEYsk-xxx export OPENAI_BASE_URLhttps://api.example.com/v1如果你用的是 Claude Code还会用到 Anthropic 的 API Key。这里不展开配置方法在各个 Agent 的官方文档里都有。3.4 目录规划建议按下面的目录结构管理流程相关文件project/ ├── .claude/ │ └── skills/ │ └── flowchart/ │ ├── SKILL.md │ └── references/ │ ├── mermaid-examples.md │ └── flowchart-guidelines.md ├── docs/ │ └── diagrams/ ├── inputs/ └── outputs/inputs/放需求描述文本outputs/放生成的流程图文件docs/diagrams/放最终归档的图表。这样批量生成的时候不会把项目根目录弄乱。4. 安装部署与启动方式4.1 创建 skill 目录以 Claude Code 为例在项目根目录执行mkdir -p .claude/skills/flowchart/references其他 Agent 的目录命名不同但逻辑一致。4.2 编写 SKILL.mdskill 的核心是一个SKILL.md文件。这个文件告诉 AI当用户提到流程图相关任务时你应该按什么规则来工作。下面是一个可用的参考配置--- name: flowchart description: 根据用户描述生成流程图支持 Mermaid 和 PlantUML 格式 --- # 流程图生成 Skill ## 触发条件 当用户需要画流程图、业务流程图、算法流程图、状态机图时使用本 skill。 ## 执行步骤 1. 与用户确认流程中的实体、判断节点、开始和结束节点。 2. 选择输出格式Mermaid 或 PlantUML。 3. 生成可渲染的流程图代码。 4. 将代码保存为 .mmd 或 .puml 文件并给出预览说明。 ## 输出规范 - 必须包含开始节点和结束节点。 - 判断节点使用菱形表示。 - 分支条件写在连接线上。 - 异步任务单独标注。 - 代码中不得出现中文字符变量名。实际使用时你可以把这份配置放到自己的 skill 目录里然后根据你的模型表现不断调整SKILL.md里的规则。这相当于给 AI 立了一套流程图画法规范。4.3 启动验证配置完成后不涉及重启服务。直接在 Agent 对话窗口输入请帮我画一个用户登录的流程图如果 skill 生效AI 会自动调用 flowchart skill并按输出规范生成流程图。如果没有生效检查 skill 目录路径是否正确以及 Agent 是否启用了 skill 功能。4.4 验证 skill 是否被识别在 Claude Code 中可以用/skills命令查看当前项目加载了哪些 skill。如果列表里出现flowchart说明配置成功。5. 功能测试与效果验证skill 部署完成后建议从简单到复杂依次验证。下面给出一套可复制的测试流程。5.1 基础流程测试测试目的验证 AI 是否能生成结构完整的流程图。输入画一个用户注册流程包含填写信息、校验手机号、发送验证码、验证码校验、注册成功。预期输出一份包含开始节点、操作节点、判断节点、结束节点的 Mermaid 代码。graph TD A([开始]) -- B[填写注册信息] B -- C[填写手机号] C -- D[发送验证码] D -- E{验证码是否正确} E --|是| F[注册成功] E --|否| G[提示重新输入] G -- D F -- H([结束])判断标准代码能直接渲染逻辑顺序和输入的描述一致错误分支有闭环。常见失败原因AI 漏掉判断节点或者把验证码校验写成了普通操作节点。遇到这种情况可以在描述里强调“这里需要判断”。5.2 算法流程测试测试目的验证复杂分支逻辑的表达能力。输入用流程图说明反向传播算法的工作原理包含前向传播、损失计算、梯度计算、参数更新。预期输出分阶段清晰的流程图每个阶段有明确的节点和连接线。判断标准AI 能分清前向传播和反向传播的方向。如果生成结果里出现方向混乱建议在SKILL.md输出规范里增加一条“如果流程方向需要区分使用箭头方向表达数据流和梯度流。”5.3 多格式导出测试测试目的验证输出是否方便导入其他工具。操作步骤让 AI 生成 Mermaid 格式流程图。把代码保存为.mmd文件。在 Typora 或飞书中渲染。再让 AI 生成一份 PlantUML 版本对比效果。PlantUML 格式示例startuml |用户| start :输入账号密码; |系统| if (校验通过?) then (yes) :登录成功; else (no) :提示错误; endif stop enduml判断标准两种格式都能在对应渲染器中正常显示节点和连线没有语法报错。5.4 流程优化建议测试测试目的验证 skill 是否能发现流程设计问题。输入下面这个流程缺少异常处理请帮我补全订单创建后直接支付支付失败没有处理。预期输出AI 自动添加支付失败的重试和取消订单分支。这里建议在SKILL.md中加一条规则“如果用户描述的流程明显缺少异常分支应在生成前提醒并主动补全常见异常处理。”这样 skill 就不只是画图工具还能帮你检查流程完整性。5.5 中英文混合描述测试测试目的验证描述混乱时的处理能力。输入就是那个注册功能用户填完信息然后发个验证码再 verify 一下通过了就进入 dashboard。预期输出AI 能理解中英文混写把 verify 翻译成“校验验证码”把 dashboard 翻译成“用户主页面”。判断标准生成的流程图节点命名统一不出现中英混用。如果 AI 保留了英文节点可以在输出规范里补充“节点名称统一使用中文”。6. 接口 API 与批量任务单次对话生成流程图只是第一步。实际工作中我们经常需要批量处理多张流程图比如一整套需求文档里的所有业务流。这类任务可以分两条路走。6.1 批量生成文件利用 Agent 的批量任务能力可以一次性把多个流程描述传给 AI。下面是一个伪代码示例实际命令需要根据你使用的 Agent 调整。# 批量处理 inputs 目录下的所有流程描述文件 # 每个文件是一段纯文本描述 for f in inputs/*.txt; do echo 处理 $f # 调用 Agent 生成流程图输出为 outputs/$(basename $f).mmd done如果是自己写脚本调用模型 API可以用下面的思路import os import requests api_url https://api.example.com/v1/chat/completions api_key os.environ[OPENAI_API_KEY] def generate_flowchart(description: str, output_path: str): prompt f 你是一个流程图生成助手。 根据下面的描述生成 Mermaid 格式流程图。 要求 1. 包含开始和结束节点。 2. 判断节点用菱形。 3. 分支条件写在连线上。 描述 {description} 只输出 Mermaid 代码不要额外解释。 resp requests.post( api_url, headers{Authorization: fBearer {api_key}}, json{ model: qwen-plus, messages: [{role: user, content: prompt}], temperature: 0.2 }, timeout120 ) result resp.json() mermaid_code result[choices][0][message][content] # 去掉可能的代码块标记 mermaid_code mermaid_code.replace(mermaid, ).replace(, ).strip() with open(output_path, w, encodingutf-8) as f: f.write(mermaid_code) # 示例调用 generate_flowchart(用户注册流程填写信息、校验手机号、发送验证码、注册成功, outputs/register.mmd)注意上面的api_url和model需要按你实际使用的模型服务替换。这个脚本的核心思路是把“生成流程图”变成一个可编程的接口任务方便后续接入自动化流程。6.2 接口化改造如果你想把这个能力封装成内部工具建议起一个轻量 HTTP 服务每次请求传一段流程描述返回 Mermaid 代码。from flask import Flask, request, jsonify app Flask(__name__) app.route(/api/flowchart, methods[POST]) def flowchart(): data request.get_json() description data.get(description, ) # 这里调用上面的 generate_flowchart 函数把输出作为字符串返回 # 真实场景中建议把 mermaid_code 存到缓存或对象存储 return jsonify({mermaid: graph TD\\n A[开始]}) if __name__ __main__: app.run(host127.0.0.1, port8900)接口启动后可以用 curl 测试curl -X POST http://127.0.0.1:8900/api/flowchart \ -H Content-Type: application/json \ -d {description: 订单支付流程创建订单、发起支付、支付回调、更新订单状态}这个接口服务可以作为团队内部工具也可以在 CI 流程中自动生成架构文档配图。注意接口服务需要加访问控制和限流避免被内部网络外的请求打到。7. 资源占用与性能观察流程图 skill 的资源占用主要看两处。第一是模型 API 的 Token 消耗。生成一张中等复杂度的流程图输入描述加输出代码整体 Token 消耗并不大。但如果流程图复杂输出代码长消耗会明显上升。建议在 prompt 中要求“只输出代码不输出解释”能省不少 Token。第二是本地 Agent 进程的内存占用。如果跑的是 Claude Code 这类 Node.js 工具启动后内存占用通常不高。如果走本地大模型推理显存占用取决于模型参数不能一概而论。从材料看这个 skill 本身不涉及本地模型加载所以最稳妥的做法是走 API 调用省去显存和 CPU 压力。7.1 性能观察建议用nvidia-smi查看显存占用前提是本地有 GPU 推理。纯 API 调用时这一项可以忽略。用time命令测量每次生成流程图的耗时。批量任务里建议每生成 10 张图暂停 2 秒避免触发 API 频率限制。如果发现输出乱码优先检查模型是否支持中文以及SKILL.md里是否明确要求使用中文节点名。7.2 降低消耗的方法在 prompt 里限制输出格式只输出 Mermaid 代码不要解释。把常用的流程片段写成模板比如“登录流程”“注册流程”“支付流程”生成时直接复用。批量任务失败时先重试一次不要无脑重复同一条请求。8. 常见问题与排查方法问题现象可能原因排查方式解决方案对话中技能未被触发skill 目录路径错误查看 Agent 加载的 skill 列表按 Agent 文档调整目录结构生成的代码渲染报错Mermaid 语法版本不兼容把代码粘贴到 Mermaid Live Editor 测试让 AI 用兼容语法重新输出节点名称中英混合模型对语言判断不稳定检查 SKILL.md 是否规定统一中文输出规范里强制“节点名统一使用中文”缺少异常分支描述中未体现检查提示词是否完整让 AI 主动补全常见异常处理批量生成时 API 报错频率超限查看响应状态码增加重试和休眠生成的图结构太乱描述不够结构化先让 AI 列出主干节点再生成在 SKILL.md 中增加“先生成节点清单”步骤接口服务 502模型服务超时查看后端日志加长 timeout改为异步任务输出文件无法导入 Typora代码块标记未清除检查文件是否包含 markdown脚本里统一过滤标记从实际经验看最容易踩的坑是SKILL.md里没有规定输出格式。AI 可能输出一段解释性文字再加代码块这对手动复制没影响但批量任务就直接炸了。所以在设计 skill 时一定要把“只输出代码”写死并且在生成脚本里再做一层过滤。9. 最佳实践与使用建议9.1 先把 SKILL.md 打磨好skill 的效果取决于SKILL.md的约束质量。建议第一次使用时先让 AI 按默认方式画 3 张不同类型的流程图然后针对暴露的问题逐条补充规则。这个过程和调提示词一样是持续迭代不是一次性写好。9.2 一套文件三类存放建议把文件分成三类存放流程描述源文件放在inputs/后续可以追加上下文。生成出的图表文件放在outputs/可以随时重新生成。已经确认无误的图表归档到docs/diagrams/作为正式文档的一部分。这样批量任务不会污染正式文档目录出错时也容易定位。9.3 批量任务要加日志批量生成 20 张以上流程图时强烈建议给每个任务加上文件名和状态输出echo [$(date %H:%M:%S)] 生成订单流程 - $f generate.log这样即使中途失败也能快速定位到具体文件只重跑失败的几张。9.4 涉及业务数据注意合规如果你的流程描述里包含真实的用户数据流转、内部系统路径、员工信息等在生成和分享前必须做脱敏处理。流程图发布到外部技术社区时不要带敏感的系统名和内网地址。9.5 安全使用边界skill 只能加载你允许的目录内容不要手动把整个磁盘告诉 AI。接口服务不要直接暴露到公网加一层 Token 校验更安全。如果模型服务有历史记录功能敏感流程描述尽量不要长期留存用后即删。10. 总结与下一步这个 flowchart skill 值得尝试的第一个点是它把“画流程图”从一个手动拖拽的重复劳动变成了一个可以对话、可以存档、可以批量调用的接口能力。你描述清楚逻辑AI 负责把逻辑转成规范图表这符合 AI 辅助文档工作的基本方向。建议先做一次最小验证配置好 skill 目录用“用户登录流程”或者“订单支付流程”这种简单场景跑一遍确认输出能正常渲染再逐步增加复杂度。最容易踩的坑是SKILL.md输出规范不够明确导致 AI 生成结果不稳定。解决办法也很直接每遇到一次格式问题就往SKILL.md里加一条对应规则迭代几次后效果就会稳定很多。后续值得扩展的方向有三个。第一把 skill 从单次对话改成团队共享放到内部文档仓库里所有成员都可以直接用。 第二结合 CI 流程在文档更新时自动生成对应的流程图保证图表跟代码同步。 第三接入更多输出格式比如 SVG、PNG甚至生成可交互的网页流程图让流程图不只躺在文档里还能直接嵌入内部工具。如果你已经在写技术方案或者维护项目文档这个 skill 可以帮你省下不少画图时间。建议收藏备用等需要画流程图的时候直接拿出来用。