CC Workflow Studio Skill 节点集成：从需求规范到可视化工作流实战

• AI 应用
• Agent 工作流
• 开发工具
• MCP 服务

导读：本文围绕 CC Workflow Studio（cc-wf-studio）仓库中001-skill-node特性（Skill 节点集成）的需求规范与功能规格展开，完整讲解该特性从"可视化画布新增 Skill 节点"到"浏览、引用、新建 Claude Code Skills 并导出到工作流"的完整闭环。读完本文，你将掌握 Skill 节点的数据模型与校验规则、浏览/新建/校验三大能力的扩展端与 Webview 端调用链，以及缺失文件、命名冲突、非法 YAML 等边界情况的处理策略，并能直接据此在可视化编辑器中配置可运行的 Skill 工作流。

特性背景：为什么需要 Skill 节点

Claude Code Skills 是以SKILL.md（带 YAML frontmatter 的 Markdown 文件）为载体的可复用 Agent 能力单元，通常存放在个人目录~/.claude/skills/<skill-name>/或项目目录.claude/skills/<skill-name>/下。此前，CC Workflow Studio 的可视化画布虽然已经支持 SubAgent、AskUserQuestion 等多种节点，却无法把这类既有的 Agent 能力直接编排进可视化工作流——用户只能手工书写指令，无法复用团队已经沉淀好的 Skill。

001-skill-node特性（功能分支001-skill-node，规格创建于 2025-11-08）正是为了解决这个断层：在画布节点面板中新增Skill节点类型，允许用户引用个人或项目中的既有 Skill，也可以直接在可视化编辑器中新建 Skill，从而打通"可视化工作流设计"与"可复用的模型调用式 Agent 能力"之间的桥梁。该特性的需求质量清单位于 requirements.md，完整功能规格位于 spec.md。

需求规范与验收标准总览

需求清单把特性划分为三个维度进行校验：内容质量（Content Quality）、需求完备性（Requirement Completeness）与功能就绪度（Feature Readiness），三项均以 ✅ PASS 通过：

• 内容质量：规范只回答 WHAT 与 WHY，不出现 TypeScript、React、VSCode API 等实现细节；面向业务干系人编写（用户故事 + 验收场景）；所有必填章节（用户场景、需求、成功标准）均已填写。
• 需求完备性：16 条功能需求（FR-001 ~ FR-016）全部可测试、无歧义；成功标准包含可量化的指标（30 秒、95%、2 分钟）；3 条按优先级排序的用户故事均带验收场景；识别出 5 个边界情况并给出处理策略；Out of Scope 清晰划定边界；Assumptions 记录了依赖前提。
• 功能就绪度：每条 FR 都能映射到用户场景（FR-003/FR-004 → P1，FR-008/FR-009 → P3）；主流程覆盖"浏览 → 选择 → 配置 → 导出"，次流程为"新建 Skill"；成功标准覆盖核心价值 SC-001（配置速度）与 SC-004（创建速度）。

该清单的最终结论是："规格已完成，可进入/speckit.plan规划阶段"。核心思路是"先重用在重造"：P1 复用既有个人 Skill（最高频场景）、P2 团队项目级 Skill 协作、P3 从可视化编辑器直接新建 Skill（MVP 的便利性功能，不阻断主路径）。

成功标准（可量化指标）

规格定义了 6 条可测量的成功标准，这些数字在后续实现与测试中就是验收红线：

Skill 节点数据模型与核心实体

SkillNodeData（节点数据结构）

从核心类型定义 workflow-definition.ts 可以看到，Skill 节点的数据结构比最初规格更丰富，实际实现扩展了executionMode、executionPrompt、source、pluginName等字段：

export interface SkillNodeData { name: string; // 从 SKILL.md frontmatter 提取的 Skill 名称 description: string; // 从 SKILL.md frontmatter 提取的描述 skillPath: string; // SKILL.md 路径（user/local 为绝对路径，project 为相对路径） scope: 'user' | 'project' | 'local'; allowedTools?: string; // 可选：来自 frontmatter 的 allowed-tools validationStatus: 'valid' | 'missing' | 'invalid'; outputPorts: 1; // 固定为 1（与 SubAgent 节点一致） source?: 'claude' | 'copilot'; // project 级 Skill 的来源目录 executionMode?: 'load' | 'execute'; // execute=执行；load=仅加载为上下文 executionPrompt?: string; // execute 模式下附加的定制执行提示 pluginName?: string; // 插件提供的 Skill 名称前缀（如 'with-me:skill-name'） }

关键实体关系

• Skill Node：表示一次 Claude Code Skill 调用的工作流节点。属性为节点 ID、位置、引用的 Skill 路径、Skill 元数据（名称、描述）；通过输入/输出端口与其他节点连接。
• Skill Reference：指向某个 SKILL.md 文件的指针。属性为文件路径（绝对或相对）、Skill 名称、描述、作用域（personal/project）；校验确保 YAML frontmatter 合法且必备字段齐全。
• Skill Metadata：从 SKILL.md frontmatter 解析出的信息（name、description、allowed-tools）。

属性面板的 Schema 驱动渲染

Skill 节点属性面板由 skill-schema.ts 的skillPropertySchema驱动（注册于 node-schema-registry.ts），覆盖 name、description、skillPath、scope、validationStatus、allowedTools、executionMode、executionPrompt、source、pluginName 等字段，其中 scope / validationStatus / executionMode 在 Webview 面板中以徽章/图标形式定制渲染。由于 Skill 属性来自 SKILL.md 文件，面板整体为只读模式，修改入口是底部的编辑对话框（见 skill-panel.tsx，提示语明确指出"Skill properties are read-only and loaded from SKILL.md file. To modify, edit the source file directly."）。

用户故事与验收场景

P1：引用既有个人 Skill

用户把个人目录~/.claude/skills/中已沉淀的 Skill（例如pdf-form-filler）拖入可视化工作流，无需重新实现即可复用专项能力。独立测试：创建一个 Skill 节点指向~/.claude/skills/test-skill/SKILL.md，导出工作流，运行后验证 Skill 是否按 description 触发而自动激活。

验收场景要点：拖入 Skill 节点后出现配置项 → 点击属性面板"Browse Skills"显示~/.claude/skills/与.claude/skills/中的 Skill 列表 → 选中后节点标签更新为 Skill 名称，SKILL.md 路径写入节点数据 → 导出的 SlashCommand 执行时引用 Skill 自动激活。

P2：引用项目共享 Skill（团队协作）

团队成员引用项目目录.claude/skills/下由他人提交的 Skill，保证全团队工作流执行一致。关键点：

• 浏览时同时列出个人与项目 Skill，并以明确标识（图标或 "Personal" / "Project" 标签）区分来源；
• 保存工作流时，项目 Skill 使用相对路径（.claude/skills/team-skill/SKILL.md），保证跨团队成员环境可移植；
• 团队成员个人目录缺少该 Skill 时，引用依然有效、无断链。

这一点在实现中被严格执行：scanSkills对scope === 'project'的 Skill 会调用toRelativePath把绝对路径转换为相对路径后存入节点数据（见 skill-service.ts）。

P3：从可视化编辑器新建 Skill

在 Skill 节点属性面板点击 "Create New Skill"，填写表单（名称、描述、指令、allowed-tools、作用域）后保存，系统在对应目录生成新的SKILL.md，且对话框关闭后节点自动引用新创建的 Skill；非法输入（空名称、特殊字符）时显示带明确指引的校验错误。

功能需求（FR）全集

规格共 16 条功能需求，全部可测试、无歧义：

• FR-001：系统必须在节点面板中新增 "Skill" 节点类型（与 SubAgent、AskUserQuestion 等并列）。
• FR-002：Skill 节点必须在面板与画布上显示区别于其他节点类型的图标与标签。
• FR-003：系统必须允许用户浏览~/.claude/skills/与.claude/skills/中的既有 Skill。
• FR-004：Skill 浏览器必须展示 Skill 列表（名称、来自 YAML frontmatter 的描述、来源位置 Personal/Project）。
• FR-005：系统必须校验所选 Skill 文件包含合法 YAML frontmatter 且必备字段（name、description）齐全。
• FR-006：Skill 节点属性面板必须显示所引用 Skill 的名称、描述与完整文件路径。
• FR-007：系统必须允许用户重新打开浏览器、更换所引用的 Skill。
• FR-008：系统必须在 Skill 节点属性面板提供 "Create New Skill" 按钮。
• FR-009：Skill 创建对话框必须包含以下字段：
  • Skill 名称（小写、连字符、最长 64 字符、需校验）
  • 描述（最长 1024 字符）
  • 指令（Markdown 内容）
  • Allowed-tools（可选，从可用工具列表多选）
  • 作用域（Personal 或 Project）
• FR-010：新建 Skill 时系统必须创建目录~/.claude/skills/[skill-name]/或.claude/skills/[skill-name]/。
• FR-011：系统必须生成带合法 YAML frontmatter 与 Markdown 内容的SKILL.md文件。
• FR-012：系统必须阻止在目标目录创建同名 Skill。
• FR-013：Skill 节点必须在节点数据中存储所引用 SKILL.md 的完整文件路径。
• FR-014：系统必须检测引用 Skill 文件缺失/不可访问，并在 Skill 节点上显示警告。
• FR-015：导出的工作流必须包含说明所引用 Skill 依赖关系的文档。
• FR-016：Skill 节点必须有且仅有 1 个输入端口与 1 个输出端口（与 SubAgent 节点行为一致）。

边界情况与处理策略

规格明确定义了 5 个边界情况及其处理策略，这些都在后续实现中落地为可观测行为：

Out of Scope（明确不做的范围）

为避免范围蔓延，规格明确排除：从可视化编辑器编辑既有 SKILL.md 文件；创建对话框支持高级 Skill 特性（reference.md、scripts/、templates/ 等支持文件）；Skill 的版本控制集成（如新建 Skill 自动提交 git）；Skill 指令的实时校验；基于工作流上下文的自动 Skill 发现/推荐；从远程仓库或市场导入 Skill。

实现纵深：从契约到源码的调用链

以下结合仓库实际实现，说明规格如何在扩展端（Extension Host）与 Webview 端落地。

消息契约

扩展端 ↔ Webview 的全部消息类型定义在 skill-messages.ts，包含三个请求方向：

• Webview → Extension：BROWSE_SKILLS（扫描~/.claude/skills/与.claude/skills/）、CREATE_SKILL（携带CreateSkillPayload）、VALIDATE_SKILL_FILE（校验单个文件）。
• Extension → Webview：SKILL_LIST_LOADED（返回SkillReference[]与 personal/project 计数）、SKILL_CREATION_SUCCESS/SKILL_CREATION_FAILED、SKILL_VALIDATION_SUCCESS/SKILL_VALIDATION_FAILED。

SkillReference数据结构：

interface SkillReference { skillPath: string; // SKILL.md 绝对路径 name: string; // 来自 YAML frontmatter description: string; // 来自 YAML frontmatter scope: 'personal' | 'project'; validationStatus: 'valid' | 'invalid'; allowedTools?: string; // 可选 }

错误通过SkillValidationErrorPayload.errorCode枚举化，便于 i18n 查找：SKILL_NOT_FOUND、INVALID_FRONTMATTER、NAME_CONFLICT、INVALID_NAME_FORMAT、DESCRIPTION_TOO_LONG、INSTRUCTIONS_EMPTY、FILE_WRITE_ERROR、UNKNOWN_ERROR。

扩展端：Skill 服务（文件 I/O）

skill-service.ts 是文件级实现核心，包含三个导出能力：

• scanSkills(baseDir, scope, source)：遍历目录下每个子目录读取SKILL.md，调用 frontmatter 解析器提取元数据；合法则收集（project 作用域转相对路径，frontmatter 缺 name 时回退到目录名），非法则console.warn后跳过，目录不存在则返回空数组。
• scanAllSkills()：并发扫描 7 类 Agent 来源（claude、copilot、codex、roo、gemini、antigravity、cursor）的 user 目录与 project 目录，外加通过scanPluginSkills()扫描插件 Skill（读取~/.claude/plugins/installed_plugins.json与known_marketplaces.json，按 projectPath 匹配当前工作区，本地优先于用户作用域），返回{ user, project, local }三组 Skill。所有来源都展示、不去重，让用户看到全部可用 Skill。
• validateSkillFile(skillPath)：读取并解析文件；frontmatter 非法抛Invalid SKILL.md frontmatter: missing required fields，文件不存在（ENOENT）抛SKILL.md file not found at ...。
• createSkill(payload)：按 scope 取基础目录（user 用getUserSkillsDir()，project 用getProjectSkillsDir()）；fs.access检测同名目录（存在即抛 NAME_CONFLICT 类错误）；mkdir递归建目录；用generateSkillFileContent生成内容并写入SKILL.md；写失败时递归清理已建目录（fs.rm）后抛错，保证不留半成品。

SKILL.md 内容生成器

skill-file-generator.ts 按 CreateSkillPayload 生成标准 SKILL.md 内容：

--- name: test-generator description: Generates unit tests allowed-tools: Read, Write # 仅当提供了 allowedTools 时输出 --- # Test Generator Generates tests...

生成逻辑（第 50-67 行）：固定输出---与name、description两行必填 frontmatter；allowedTools非空时追加allowed-tools行；最后拼接指令正文。这与 Claude Code Skills 的标准 frontmatter 格式保持一致。

YAML frontmatter 解析器

yaml-parser.ts 刻意零依赖实现解析：用正则^---\r?\n([\s\S]*?)\r?\n---提取 frontmatter 块（同时兼容 LF 与 CRLF），再用行级正则提取name、description、allowed-tools；description缺失即返回 null（必填），name缺失则回退为空字符串交由调用方用目录名兜底。

扩展端命令处理器

skill-operations.ts 承接 Webview 的三个请求并写入输出通道CC Workflow Studio（记录扫描耗时与找到的 user/project/local 数量）：

• handleBrowseSkills：调用scanAllSkills()，合并三组后回发SKILL_LIST_LOADED，含userCount/projectCount/localCount与 ISO 时间戳。
• handleCreateSkill：调用createSkill(payload)，成功后回发SKILL_CREATION_SUCCESS（含创建的skillPath与时间戳）。
• handleValidateSkillFile：调用validateSkillFile，并根据路径归一化（Windows 兼容的\→/）后是否包含/.claude/skills判断 scope；错误消息包含file not found时映射SKILL_NOT_FOUND，包含Invalid SKILL.md frontmatter时映射INVALID_FRONTMATTER。

Webview 端：Skill 浏览器服务

skill-browser-service.ts 用 requestId 关联响应，三个方法browseSkills()、createSkill()、validateSkillFile()均带10 秒超时（REQUEST_TIMEOUT = 10000），超时或错误时 reject 并移除监听器，避免悬挂 Promise。

Webview 端：三个对话框组件

• SkillBrowserDialog.tsx：打开时异步加载 Skill 并按 scope 分为 user/project/local 三个 Tab；提供关键词过滤、按来源（claude/copilot/codex/roo/gemini/antigravity/cursor）分组的跳转导航与来源徽章；Skill 行展示名称（插件 Skill 显示pluginName:name）、描述、scope 徽章、校验状态图标（✓/⚠/✗）；选择后进入第二步配置 executionMode 与 executionPrompt，最后以"避开既有节点重叠位置"算法计算坐标，通过addNode将 Skill 节点写入画布（data 完整携带 name、description、skillPath、scope、validationStatus、allowedTools、outputPorts: 1、source、pluginName、executionMode、executionPrompt）。
• SkillCreationDialog.tsx：表单包含名称（必填，占位符my-skill）、描述（必填，3 行）、指令（必填，8 行 Markdown）、allowed-tools（可选，占位符Read, Grep, Glob, Bash）、作用域（user/project 单选）；描述与指令支持点击EditInEditorButton在编辑器内编写；提交前走前端校验，成功后刷新列表。
• SkillNodeEditDialog.tsx：编辑 Skill 节点的executionMode（execute/load 单选）与executionPrompt（execute 模式专用，maxLength受VALIDATION_RULES.SKILL.EXECUTION_PROMPT_MAX_LENGTH约束，实时显示字数）。

前端校验规则

skill-validation.ts 实现四类字段校验，与核心层VALIDATION_RULES.SKILL（见 workflow-definition.ts）保持一致：

• 名称：^[a-z0-9-]+$（小写字母、数字、连字符），1~64 字符；
• 描述：1~1024 字符；
• 指令：至少 1 个字符（非空）；
• 作用域：必须为user或project。

错误以 i18n key（如skill.validation.nameInvalidFormat）返回，由翻译层展示。

节点画布渲染与校验状态可视化

SkillNode.tsx 定义了画布上的 Skill 节点渲染：

• 头部为Zap 闪电图标 + "Skill" 大写标签，与 FR-002 的要求对应；
• 校验状态实时可视化：valid显示绿色 ✓、missing显示警告色 ⚠、invalid显示错误色 ✗（悬停有 tooltip），对应 FR-014；
• 名称区显示pluginName:name（插件 Skill）或name，未命名时显示Untitled Skill；
• 展示 description 或 executionPrompt（两行截断）；
• scope、来源（AIProviderBadge）、LOAD ONLY徽章（executionMode === 'load' 时显示）与 🔧 allowed-tools 一目了然；
• 左侧 1 个输入 Handle、右侧 1 个输出 Handle，即 FR-016 的"恰好 1 进 1 出"。

在核心校验层 validate-workflow.ts，validateSkillNode对节点数据做结构校验：必填字段（name、description、scope、validationStatus、outputPorts）缺失报SKILL_MISSING_FIELD；validationStatus !== 'missing'时 skillPath 必填；名称不符NAME_PATTERN报SKILL_INVALID_NAME、超长报SKILL_NAME_TOO_LONG；描述超长报SKILL_DESC_TOO_LONG；outputPorts !== 1报SKILL_INVALID_PORTS（提示需要分支请使用 ifElse 或 switch 节点）；executionPrompt 超长报SKILL_EXECUTION_PROMPT_TOO_LONG。

导出与运行：Skill 如何进入真实工作流

工作流提示词生成（执行语义）

workflow-prompt-generator.ts 定义了 Skill 节点在生成工作流提示词时的三种语义：

#### skill-node-id(skill-name) - **Prompt**: skill "skill-name" # execute 模式，无附加提示 - **Prompt**: skill "skill-name" "执行提示内容" # execute 模式 + executionPrompt - **Prompt**: skill "skill-name" load-skill-knowledge-into-context-only # load 模式

插件 Skill 使用pluginName:skillName形式供 Claude Code 解析，与画布/浏览器中的展示一致。

工作流整体导出为 Skill

值得注意的演进是：Claude Code 正将.claude/commands/并入.claude/skills/，因此 workflow-export.ts 现在把整个工作流作为"Workflow-as-Skill"导出——入口文件落在.claude/skills/<workflow-name>/SKILL.md，与 cursor、codex、antigravity 等 Agent 的<root>/skills/<name>/SKILL.md目录约定保持一致。这与 FR-015"导出工作流必须包含对引用 Skill 依赖的说明"一脉相承：工作流本身也是一个可被模型调用的 Skill，其内部依赖的 Skill 节点会以提示词方式被引用。

运行与查看方式

• 运行工作流：通过packages/cli提供的 CLI（如run、render、export等命令，见 CLI 命令目录）执行导出的工作流；Skill 节点按上述提示词语义触发对应 Skill。
• 在仓库中查看本特性：完整契约见 skill-messages.ts，扩展端实现见 skill-operations.ts 与 skill-service.ts，Webview 端见 skill-browser-service.ts 及三个对话框组件；核心校验规则见 validate-workflow.ts 与 workflow-definition.ts。

假设与适用前提

• 用户对 Claude Code Skills 与 SKILL.md 格式有基本了解；
• ~/.claude/skills/与.claude/skills/对扩展可读可写（若未打开工作区文件夹，创建 project Skill 会报 "No workspace folder is open"）；
• SKILL.md 遵循标准格式（YAML frontmatter，name + description 必备）；
• 可视化编辑器支持动态节点类型注册；
• MVP 阶段 Skill 节点不需要复杂分支逻辑（1 进 1 出即可）。

小结

Skill 节点集成特性遵循"先重用在重造"的优先级设计：P1 复用个人 Skill、P2 团队项目协作、P3 编辑器内新建，并以 6 条可量化成功标准与 5 类边界处理策略收口。仓库中的实际实现完整覆盖了规格：schema 驱动的只读属性面板、零依赖的 frontmatter 解析、多 Agent 来源并发扫描、带超时与 requestId 关联的 Webview 消息链路、前后端双层校验，以及导出为 Workflow-as-Skill 的统一路径。无论你是想在工作流中编排既有 Claude Code Skills，还是想从可视化编辑器快速沉淀新的可复用能力，Skill 节点都是 CC Workflow Studio 中连接"可视化设计"与"Agent 能力复用"的关键一环。

• AI 应用
• Agent 工作流
• 开发工具
• MCP 服务