uml

uml skill 概览

uml skill 是做什么的

uml skill 可以把一个粗略的软件想法，转换成使用 PlantUML 语法编写的 UML 图。它最适合那些需要一种快速、以文本为先的方式来建模类图、时序图、活动图、状态图、组件图、部署图、用例图及相关关系的人，而且不需要手工绘图。

最适合哪些人

如果你要文档化代码结构、系统行为、服务边界，或者需要把某个流程保持在 markdown 中并纳入版本管理，那么就适合用 uml skill。它尤其适合开发者、架构师、技术写作者，以及为仓库或设计文档生成图表代码的 AI agent。

什么时候该选它

当输出需要精确、可编辑、并且能够自动排版时，适合用 uml 来做 Diagramming。它非常适合依赖关系图、包层级结构和交互流程图。但如果你需要的是分层架构图、数据可视化，或者 BPMN 风格的业务流程，那么它就不是合适的 skill。

如何使用 uml skill

安装并检查正确的文件

使用 npx skills add markdown-viewer/skills --skill uml 安装 uml skill。然后先打开 SKILL.md，再查看与你目标相匹配的示例文件。最值得优先看的起点是 examples/class-diagram.md、examples/sequence-diagram.md、examples/activity-diagram.md 和 examples/deployment-diagram.md。

给模型的是图的意图，不只是话题

低质量提示会说：“给我画一个认证的 UML 图。” 更好的 uml 使用提示会说明你需要哪种图、必须出现哪些实体或参与者，以及应该展示什么关系或流程。例如：“创建一个登录的 sequence diagram，包含 user、API、auth service 和 database；要包含成功和密码错误两条分支。” 这样 skill 才有足够的结构信息，产出可用的 PlantUML。

让输入内容匹配图表类型

uml 指南在你一开始就选对图表类型时，效果最好。类图适合结构和继承，sequence diagram 适合消息流，activity diagram 适合分支工作流，state machine 适合生命周期变化，component diagram 适合服务依赖，deployment diagram 适合运行时部署位置。如果你不确定，先看对应的 examples/*.md 文件再提问，这样第一次输出就会更接近你想要的记法。

有意识地使用语法约束

PlantUML 输出应该以 @startuml 开头、以 @enduml 结尾，代码块应使用 ```plantuml 或 ```puml。当你需要可直接渲染的结果时，应该把这个要求写进提示词里。如果你想要风格一致，可以要求加入 skinparam 设置、命名别名、notes，或者指定继承、组合、依赖等关系箭头。

uml skill 常见问题

uml skill 适合新手吗？

适合，前提是你已经了解自己要画的业务或系统。这个 skill 能减少你对语法的猜测，但你仍然需要提供图表类型、主要元素以及它们之间的关系。新手最好先从一个示例文件入手，再在此基础上改写，而不是直接要求一个完全抽象的图。

它和普通提示词有什么不同？

普通提示词可能只会得到一段模糊的图示描述。uml skill 更适合生成可重复、可渲染的输出，因为它是以 PlantUML 语法和具体 UML 约定为基础的。这让它在文档、评审和基于仓库的工作流里更可靠，因为这些场景更看重准确性，而不是散文式表达。

什么时候不该用 uml？

如果你需要的是仪表盘图表、业务流程符号，或者更适合其他 skill 处理的宏观架构草图，就不要用 uml skill。它也不适合高层头脑风暴、而且还没有固定实体或关系的场景，因为这种语法本身就依赖具体输入。

如何改进 uml skill

提供图表真正需要的事实

最强的 uml 安装和使用效果，来自具体输入：名称、角色、边界、关键交互，以及这张图要回答的准确问题。比如，不要只说“展示我的系统”，而要说“展示 web client 如何调用 API gateway，再由它路由到 auth、orders 和 billing services”。这样能改善布局、关系选择以及整体可用性。

说明范围，而不只是内容

一个常见失败模式是图太满、太拥挤。你可以通过明确要省略什么来改进 uml skill 输出：比如“排除内部 helper classes”，“只展示 happy path 加一条错误分支”，或者“component diagram 只保留 public interfaces”。这样可以保持图的可读性，避免不必要的节点。

从第一次渲染开始迭代

如果第一版图太密，可以要求更窄的范围、更少的标签，或者换一种图表类型。如果结果结构正确但视觉上很乱，可以要求清理命名、增加 alias，或者调整 skinparam。如果它偏离了语义，就补上缺失的关系类型或 sequence 步骤，再重新生成。最好的 uml 指南工作流通常是两轮：先定结构，再做样式。