Communitygithub.com

Speccanvas

用于生成和维护 Spec Canvas 制品的技能，支持便携式 YAML 规范及通过配置的 MCP 服务器进行持久化。

Speccanvas 是什么？

Speccanvas 技能专注于创建和维护 Spec Canvas 制品，它采用 YAML 格式作为产品意图与实现之间的紧凑桥梁。该技能的核心哲学是“规范优先”，但仅限于有语义意义的变更，而将外观或布局等实现微调排除在规范之外。它支持 UI 规范和数据规范两种制品，前者描述屏幕、导航和用户任务等产品意图与结构，后者描述实体、字段和关系等逻辑领域模型。 该技能适用于多种平台和环境，包括 Claude Code、Cursor 等 AI 代理。当存在名为 `speccanvas` 的 MCP 服务器时，技能会利用 MCP 工具进行实时持久化，否则生成可复用的本地 YAML 文件。它提供了详细的格式定义文件、JSON Schema 和本地验证脚本，确保生成的 YAML 符合规范。对于 UI 任务，它通过“粒度门”判断变更是否应更新规范，从而保持规范的简洁和专注。 Speccanvas 支持多种任务模式：创建新规范、审查修复现有规范、压缩过度详细的 UI 规范，以及从现有应用中逆向构建规范。它强调使用格式文件作为编写指南，Schema 验证作为最终检查，并保持 UI 和数据规范之间的对齐。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add riffi/speccanvas-skills
查看原文→浏览所有技能

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

文档

Speccanvas 是做什么的？

使用本技能生成和维护 Spec Canvas 制品，形式为可移植的 YAML 规范，或通过配置好的 SpecCanvas MCP 服务器进行持久化。

将规范视为结构和意图的唯一真实来源。偏好简洁、可复用的规范，这些规范可以直接粘贴到 Spec Canvas、IDE、终端代理或代码仓库中，无需额外解释。

使用本技能中的格式描述 YAML 文件作为编写指南。使用本技能中捆绑的 JSON Schema 副本以及本地验证逻辑作为事后检查。

核心理念

Spec Canvas 规范是产品意图和实现之间的紧凑桥梁。它们应帮助代理和人类在代码变更前就产品形态达成一致，但不应成为每次 CSS、布局或组件调整的运行日志。

  • UI 规范描述意图和结构。 捕获屏幕、主要区块、导航、关键用户任务、重要状态以及有意义的响应式结构。
  • 数据规范描述逻辑领域。 捕获实体、字段、枚举、关系以及领域约束；避免物理数据库或框架细节。
  • 规范优先适用于语义变更。 在请求改变产品含义、用户旅程或领域结构时，先更新规范再实现。
  • 实现微调可跳过规范。 如果请求是外观、布局或对用户不可见的，直接修改实现，无需触碰规范。
  • 紧凑的规范是更好的规范。 优先使用简短的目的陈述，解释屏幕/区块存在的原因，而非关于如何构建的实现性描述。

粒度门

在编辑 UI 规范之前，判断所请求的变更是否具有足够的语义意义应包含在规范中。

当请求变更涉及以下内容时，更新 UI 规范：

  • 屏幕、屏幕组或主要区块；
  • 用户旅程、导航、入口点或可用操作；
  • 重要的面向用户状态、模式、权限或空/错误/恢复流程；
  • 主要组件的用途或行为；
  • 有意义的响应式结构，例如不同的桌面/移动体验；
  • 产品术语或标签的含义变化；
  • 公共、管理、编辑、播放、引导等产品区域之间的边界。

对于实现微调，不 更新 UI 规范：

  • 间距：内边距、外边距、间距、行高；
  • 精确尺寸：像素值、字体大小、宽度/高度（除非表达高层布局意图）；
  • CSS 类、Tailwind 类、组件名、文件名或框架特定结构；
  • 精确颜色、渐变、阴影、边框半径、图标或装饰性样式；
  • 已描述区块内的局部对齐、排序、换行或外观性重新排列；
  • 动画时序、防抖时间、淡入淡出秒数、吐司位置、加载旋转器机制；
  • 浏览器/平台实现细节，除非是核心面向用户能力；
  • 不改变含义的本地文案编辑；
  • 对用户不可见的重构。

如果用户请求外观或布局微调，直接进行代码更改，明确避免触及 UI 规范。

默认文件放置

除非用户明确指定其他位置，否则在项目根目录下的 spec/ 目录中创建和更新 Spec Canvas 文件。

  • UI 规范路径：spec/ui-spec.yaml
  • 数据规范路径：spec/data-spec.yaml

如果 spec/ 目录不存在，则创建它。当仅请求一个制品时，仅创建相关文件。

MCP 模式

当用户要求与实时 SpecCanvas 项目、文档、修订、实现、存档交互，或环境中明显存在 MCP 工具时，使用名为 speccanvas 的配置好的 MCP 服务器。

  • 如果 MCP 可用，在创建或更新实时 SpecCanvas 数据之前读取 references/mcp-workflow.md。
  • 如果任务创建或更新 UI 规范，还需读取 references/ui-spec-workflow.md。
  • 如果任务创建屏幕实现，还需读取 references/implementation-workflow.md。
  • 如果 MCP 不可用，不要虚构连接细节。使用可移植的 YAML 文件，或要求用户配置 speccanvas MCP 服务器。
  • 不要将 MCP URL、Bearer Token、暂存主机或本地密钥存储在本技能中。这些应属于代理的 MCP 配置和环境变量。

MCP 模型身份规则

当通过 MCP 保存代理撰写的屏幕实现时，始终提供稳定的模型身份作为 { identityKey, provider, model, version }。

  • 在调用 add_implementation 之前，从全局代理规则、环境变量或当前会话解析活动模型。
  • 对于 add_implementation，直接传递 modelIdentity。不要将其替换为 agentName。
  • agentName 仅是手动/遗留的备用选项。仅当实现由人类上传或模型身份故意不可用时，以 modelIdentity: null 使用它。
  • 如果活动模型未知、不明确或未注册，停止并要求澄清，而不是默默使用 agentName 保存。

工作流程

  1. 识别制品边界。 确定任务需要：

    • 仅 UI 规范
    • 仅数据规范
    • 两个规范
    • 对现有规范的解释、审查、清理或验证
    • 无需规范变更（因为请求是实现微调）
    • 实时的 MCP 持久化（项目、规范、修订、实现或存档）

  2. 应用粒度门。 对于 UI 工作，判断请求是否改变产品意图/结构，还是仅改变实现细节。如果仅是微调，保持规范不变。

  3. 收集源材料。 仅使用定义结构的输入：

    • 产品想法或功能请求
    • 现有截图或 UI 描述
    • 代码库结构
    • 当前 YAML 规范
    • 实体列表、API 笔记或领域规则

  4. 读取所需工作流程和格式参考。

  5. 起草或修订规范。 保持文档为有效的 YAML，并保持在格式字段内。除非格式明确允许，否则不要发明自定义顶级部分。进行最小的语义更新以保留意图；不要用像素级实现笔记扩展规范。

  6. 验证结果。 如果 scripts/validate-spec.mjs 可用，在返回结果前针对最终 YAML 运行它。在返回规范前修复验证错误。

  7. 返回结果。 返回验证后的 YAML，或者对于审查任务，先返回问题，然后返回修正后的代码片段或文件。

核心规则

使用格式文件作为编写来源

格式描述 YAML 文件是本技能的主要编写参考。首先遵循其结构、字段命名、示例和指导。对于 UI 规范，references/ui-spec-format-0-0-3.yaml 是当前的本地真值来源，并预期与捆绑的模式和验证器保持一致。

使用模式验证作为事后检查

模式验证不是编写指南。它是最终的验证步骤。

  • 从格式文件编写规范。
  • 使用 scripts/validate-spec.mjs 验证编写的规范。
  • 在返回最终 YAML 之前修复模式和验证规则失败。

schemas/ 中捆绑的模式应与 Spec Canvas 实现以及本技能中的格式描述参考保持同步。如果它们似乎不同，请将其视为技能错误，并明确指出，而不是默默发明折衷方案。

保持 UI 和数据对齐

当两个规范都存在时：

  • 匹配屏幕、实体和操作之间的命名
  • 确保 UI 操作暗示真实的实体或工作流程
  • 确保数据规范关系支持 UI 结构
  • 标记差距，而不是默默发明后端概念

保持格式可移植

生成可存放在仓库中并由任何代理重用的纯 YAML 文件。不要使规范依赖于 Spec Canvas UI 状态、隐藏元数据或仅聊天的假设。

保持 UI 规范高于实现细节

不要将 UI 规范用作 CSS、组件文档或变更日志的替代品。良好的 purpose 从用户角度解释屏幕或区块的用途。不应列举精确的间距、类名、像素大小、瞬态实现机制或每个小控件（如果这些细节不改变产品含义）。

任务模式

创建新的 UI 规范

  • 从 docType、format_version 和 metadata 开始。
  • 在 UI 规范中，metadata.description 是必需的，应承载顶级产品意图。
  • 一旦知道主要应用形状，立即添加 screens。
  • 当用户希望看到可见结构时添加 blocks；在探索阶段可以省略 blocks。
  • 仅当它们有实质性帮助时，才添加 templates、navigation 或响应式字段。
  • 当前本地格式支持的 UI 响应式编写包括 metadata.breakpoints、自适应 screen.template、自适应 block.columns 和 block.visible。
  • 保留原始格式文件的约定，包括 UI 格式文件中的引号指导。
  • 在可用时使用 scripts/validate-spec.mjs 验证完成后的文件。

创建新的数据规范

  • 描述逻辑领域模型，而非物理数据库。
  • 仅在共享受控词汇表重要时添加 enums。
  • 使用具有业务意义的 fields 定义 entities。
  • 使用 relations 进行逻辑跨实体结构。
  • 避免泄露仅与实现相关的问题，如索引、迁移或 ORM 特定语法，除非用户明确在规范之外请求它们。
  • 在可用时使用 scripts/validate-spec.mjs 验证完成后的文件。

审查或修复现有规范

检查：

  • 无效或不支持的字段
  • 缺少必需部分
  • 损坏的屏幕、模板或导航引用
  • 数据规范中的枚举、外键或关系错误
  • 本地验证规则暴露的自定义验证失败
  • 原始格式文件与当前本地实现之间的模式-格式不匹配
  • 描述实现机制而非产品意图的过于详细的 UI purpose 文本

修复时，保留原始产品意图，并进行最小的修正以恢复清晰性。

压缩过度详细的 UI 规范

  • 保持现有屏幕、模板、区域和区块 ID 稳定，除非产品结构确实变化。
  • 将长的 purpose 段落替换为面向用户意图的单句摘要。
  • 保留屏幕、主要区块、导航、重要状态和有意义的模式。
  • 移除 CSS/布局微观细节、平台怪癖、精确时序、日志行为和组件内部机制。
  • 避免整个文件的 YAML 重新格式化；使用有针对性的编辑，使差异保持可审查。
  • 编辑后验证。

从现有应用重建规范

  • 从可见工作流程推断屏幕
  • 从重复区域和用户任务推断区块
  • 从领域名词和状态变化推断实体
  • 区分观察到的和猜测的
  • 当源材料不完整时，明确指出不确定性

验证

在可用时使用 scripts/validate-spec.mjs。

  • 输入：YAML 规范文件的路径
  • 从 docType 检测文档类型
  • 针对本技能捆绑的 JSON Schema 进行验证
  • 运行相关的自定义验证规则
  • 将警告视为建议
  • 错误视为最终输出的阻塞项（当返回修正后的规范时）

如果由于缺少本地 Spec Canvas 依赖项而无法运行脚本，简要说明并回退到使用格式文件和验证规则引用进行手动审查。

输出期望

当返回规范时：

  • 提供有效的 YAML
  • 在格式期望的地方保持 ID 为 snake_case
  • 保持字段名称与格式文件定义的完全一致
  • 当假设对结构产生实质性影响时提及
  • 提及是否运行了验证

当返回审查而非重写的文件时：

  • 首先列出结构性问题
  • 然后给出具体修复方案
  • 如果有用，提供修正后的代码片段或完整规范

相关技能

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community