技能标准与扩展开发

这个模块管什么

stitch-skills 是一组面向 Stitch MCP server 的 Agent Skills。每个技能都不是单独的“脚本集合”，而是按 Agent Skills open standard 组织的一段可安装、可被代理识别、可组合调用的能力。

“技能标准与扩展开发”主要约束三件事：

每个技能的目录结构
- SKILL.md
- scripts/
- resources/
- examples/
新增技能的开发边界
- 技能应围绕一个清晰工作流，而不是把多个无关能力塞进一个目录。
- 技能要能被 Codex、Antigravity、Gemini CLI、Claude Code、Cursor 等编码代理理解。
- 需要依赖 Stitch MCP 的能力时，必须在技能说明中写清楚前置条件。
技能之间的组合方式
- 例如设计生成、代码转设计、设计系统管理等能力可能互相依赖。
- 选择性安装技能时，需要明确依赖，避免用户只装了一个技能但运行时缺少必要上下文。

当前仓库中的技能主要通过插件分组：

插件	作用
`stitch-design`	设计生成、代码转设计、设计系统管理等核心设计工作流
`stitch-build`	构建、组件相关工作流
`stitch-utilities`	辅助工具类技能

一个技能目录应该长什么样

推荐结构如下：

text
plugins/
  stitch-design/
    skills/
      generate-design/
        SKILL.md
        scripts/
          ...
        resources/
          ...
        examples/
          ...

以 plugins/stitch-design/skills/generate-design/ 为例，目录职责通常是：

路径	作用
`SKILL.md`	技能入口说明。代理首先读取这里，判断何时使用技能、如何使用技能、有哪些限制。
`scripts/`	可执行脚本。用于把重复、易错、需要工具调用的步骤固化下来。
`resources/`	静态资源、模板、参考文档、提示词片段、设计规范片段等。
`examples/`	可复制的使用样例，帮助代理和开发者理解输入、输出和典型场景。

`SKILL.md` 写的是技能契约

SKILL.md 是技能最重要的文件。它不只是说明文档，也是代理判断技能边界的依据。

一个可维护的 SKILL.md 应该覆盖以下内容：

markdown
# stitch::example-skill

## When to use this skill

Use this skill when the user wants to ...

## What this skill does

- ...
- ...
- ...

## Inputs

- Project name:
- Source path:
- Stitch design URL:
- Design system file:

## Outputs

- ...
- ...

## Required tools

- Stitch MCP server
- Local file access
- Optional scripts in `scripts/`

## Workflow

1. ...
2. ...
3. ...

## Constraints

- ...
- ...

技能名

建议使用命名空间形式：

text
stitch::<skill-name>

例如：

text
stitch::code-to-design
stitch::generate-design
stitch::manage-design-system

这样做有两个好处：

避免和其他项目里的技能重名。
用户可以很快判断这个技能属于 Stitch 生态。

使用时机

When to use this skill 要写得具体，不要只写“用于设计”。

较好的写法：

markdown
Use this skill when the user wants to generate new Stitch screens from text prompts,
image references, or existing screen edits.

不建议：

markdown
Use this skill for design tasks.

前者能帮助代理判断是否该调用技能，后者太宽泛，容易误触发。

输入和输出

技能要明确自己需要什么输入。

例如 code-to-design 这类技能通常需要：

前端项目路径
目标 Stitch project 名称
页面入口或路由
可选设计系统文件
Stitch MCP 访问能力

输出可能是：

新建或更新后的 Stitch design
上传结果链接
转换日志
未能识别的组件或样式列表

如果输入不完整，技能应该指导代理先追问，而不是直接猜。

`scripts/` 放可重复执行的操作

scripts/ 适合放这些内容：

提取 HTML、CSS、设计 token
转换资源格式
检查目录结构
上传前的文件整理
批量处理屏幕或组件
生成中间 JSON
校验 DESIGN.md、资源命名、示例输入

示例结构：

text
scripts/
  extract-html.mjs
  normalize-assets.mjs
  validate-design-system.mjs

脚本应该遵循几个约束：

可重复执行
- 多次运行不会破坏项目。
- 临时文件写到明确目录，例如 .stitch-tmp/。
参数明确
- 不依赖代理“猜”当前路径。
- 尽量支持 --input、--output、--project 等参数。
错误可读
- 缺少文件、缺少环境变量、MCP 未配置时，要输出明确错误。
不写死用户环境
- 不要假设用户一定使用 macOS、某个 shell、某个包管理器。
- Node 脚本建议使用跨平台写法。

示例脚本入口：

bash
node scripts/validate-skill.mjs --skill plugins/stitch-design/skills/generate-design

`resources/` 放技能运行时会参考的资料

resources/ 不是垃圾桶，适合放稳定、可复用的上下文。

常见内容：

text
resources/
  prompt-template.md
  design-token-mapping.json
  accessibility-checklist.md
  component-naming.md

适合放入 resources/ 的资料：

设计系统映射规则
组件命名规范
上传前清洗规则
可访问性检查清单
生成提示词模板
Stitch MCP 调用说明片段

不适合放入 resources/ 的内容：

用户私有设计稿
临时导出的图片
大体积构建产物
密钥、cookie、token
与技能无关的通用资料

`examples/` 写给代理和维护者看

examples/ 应该包含真实场景，而不是只有抽象描述。

推荐结构：

text
examples/
  mobile-browse-tab.md
  dashboard-migration.md
  design-system-upload.md

示例可以包含：

markdown
# Upload a dashboard frontend to Stitch

User request:

> Upload the frontend code at `/path/to/dashboard` into a Stitch project named
> `Dashboard-Migration-2026`.

Expected behavior:

1. Inspect the frontend app.
2. Extract renderable HTML and CSS.
3. Apply available design system guidance.
4. Upload the result through Stitch MCP.
5. Return the Stitch project or design URL.

好的示例应该说明：

用户会怎么说
技能应该怎么拆解任务
需要哪些输入
预期产出是什么
哪些情况需要追问

现有技能的开发口径

`stitch::code-to-design`

适用场景：

“把 /path/to/dashboard 里的前端页面上传到 Stitch 项目 Dashboard-Migration-2026。”

该技能重点是把已有前端代码转成 Stitch design。典型流程包括：

读取前端项目。
提取页面结构、样式、资源。
结合设计系统信息。
通过 Stitch MCP 上传。
返回上传结果。

新增同类能力时，不要把“代码分析”“设计上传”“组件重构”全部混在一起。可以拆成：

页面提取脚本
资源归一化脚本
上传工作流说明
示例请求

`stitch::generate-design`

适用场景：

“做一个移动端约会灵感 App 的 browse tab。”
“把登录页加上 Remember Me 复选框，按钮改成蓝色。”
“基于首页生成 3 个深色、高密度布局变体。”

该技能重点是从文本、图片或已有屏幕生成和修改设计。它应该清楚区分：

生成新屏幕
编辑已有屏幕
生成多个变体
使用图片作为参考
应用已有主题或设计系统

如果任务涉及大规模设计系统治理，应转交或依赖 stitch::manage-design-system。

`stitch::manage-design-system`

适用场景：

“上传 DESIGN.md 并把主题应用到这些屏幕。”

该技能负责设计系统相关操作，例如：

上传 DESIGN.md
应用主题
管理 token、颜色、字体、组件规范
让生成结果遵循统一视觉语言

新增功能时，要避免让设计系统技能直接承担“生成完整产品界面”的职责。它应该提供规范和应用规范，而不是替代生成技能。

本地创建一个新技能骨架

下面示例可以直接运行，会在当前目录生成一个新的技能目录。

bash
mkdir -p plugins/stitch-design/skills/a11y-review/{scripts,resources,examples}

cat > plugins/stitch-design/skills/a11y-review/SKILL.md <<'EOF'
# stitch::a11y-review

## When to use this skill

Use this skill when the user wants to review Stitch screens or frontend-derived designs
for accessibility issues such as contrast, touch target size, hierarchy, and readable text.

## What this skill does

- Reviews a screen or design flow for accessibility risks.
- Produces a prioritized list of issues.
- Suggests concrete design changes.
- Can use checklist resources from `resources/`.

## Inputs

- Stitch design URL or screen name.
- Target platform, such as mobile web, desktop web, iOS, or Android.
- Optional accessibility standard or checklist.

## Outputs

- Accessibility review summary.
- Blocking issues.
- Recommended fixes.
- Follow-up questions when the input is incomplete.

## Required tools

- Stitch MCP server, when inspecting or updating Stitch designs.
- Local file access, when using resources or examples in this skill.

## Workflow

1. Confirm the target screen or design flow.
2. Check visual hierarchy, contrast, spacing, text size, and touch targets.
3. Compare findings against the checklist in `resources/accessibility-checklist.md`.
4. Return prioritized issues.
5. If requested, propose edits that can be applied through Stitch MCP.

## Constraints

- Do not claim WCAG compliance unless enough evidence is available.
- Do not change a design without explicit user approval.
- Ask for the target platform when it changes the accessibility expectation.
EOF

cat > plugins/stitch-design/skills/a11y-review/resources/accessibility-checklist.md <<'EOF'
# Accessibility checklist

- Text has sufficient contrast against its background.
- Primary actions are visually distinct.
- Touch targets are large enough for the target platform.
- Headings and labels communicate purpose.
- Error states include clear recovery guidance.
- Color is not the only way to communicate state.
EOF

cat > plugins/stitch-design/skills/a11y-review/examples/mobile-checkout-review.md <<'EOF'
# Review mobile checkout accessibility

User request:

> Review the mobile checkout screen for accessibility issues.

Expected behavior:

1. Ask for the Stitch design URL if it was not provided.
2. Inspect the checkout screen.
3. Check contrast, form labels, error states, and button target size.
4. Return prioritized issues and recommended fixes.
EOF

cat > plugins/stitch-design/skills/a11y-review/scripts/validate-input.mjs <<'EOF'
#!/usr/bin/env node

const args = process.argv.slice(2);

if (args.includes("--help")) {
  console.log("Usage: node scripts/validate-input.mjs --design-url <url> --platform <platform>");
  process.exit(0);
}

const getArg = (name) => {
  const index = args.indexOf(name);
  return index >= 0 ? args[index + 1] : undefined;
};

const designUrl = getArg("--design-url");
const platform = getArg("--platform");

if (!designUrl) {
  console.error("Missing required argument: --design-url");
  process.exit(1);
}

if (!platform) {
  console.error("Missing required argument: --platform");
  process.exit(1);
}

console.log(JSON.stringify({
  ok: true,
  designUrl,
  platform
}, null, 2));
EOF

chmod +x plugins/stitch-design/skills/a11y-review/scripts/validate-input.mjs

find plugins/stitch-design/skills/a11y-review -maxdepth 3 -type f | sort

运行后应该看到类似输出：

text
plugins/stitch-design/skills/a11y-review/SKILL.md
plugins/stitch-design/skills/a11y-review/examples/mobile-checkout-review.md
plugins/stitch-design/skills/a11y-review/resources/accessibility-checklist.md
plugins/stitch-design/skills/a11y-review/scripts/validate-input.mjs

再运行脚本检查参数：

bash
node plugins/stitch-design/skills/a11y-review/scripts/validate-input.mjs \
  --design-url "https://stitch.withgoogle.com/projects/example/designs/checkout" \
  --platform "mobile-web"

预期输出：

json
{
  "ok": true,
  "designUrl": "https://stitch.withgoogle.com/projects/example/designs/checkout",
  "platform": "mobile-web"
}

检查技能目录是否合格

下面这个检查脚本可以直接放到仓库根目录运行，用来确认每个技能是否包含标准目录和 SKILL.md。

bash
cat > check-skills.mjs <<'EOF'
#!/usr/bin/env node

import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] || "plugins";

function walk(dir) {
  if (!fs.existsSync(dir)) return [];

  const entries = fs.readdirSync(dir, { withFileTypes: true });
  const result = [];

  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory()) {
      result.push(fullPath);
      result.push(...walk(fullPath));
    }
  }

  return result;
}

const dirs = walk(root);
const skillDirs = dirs.filter((dir) => fs.existsSync(path.join(dir, "SKILL.md")));

if (skillDirs.length === 0) {
  console.error(`No skills found under ${root}`);
  process.exit(1);
}

let failed = false;

for (const skillDir of skillDirs) {
  const required = ["SKILL.md", "scripts", "resources", "examples"];
  const missing = required.filter((item) => !fs.existsSync(path.join(skillDir, item)));

  if (missing.length > 0) {
    failed = true;
    console.error(`✗ ${skillDir}`);
    console.error(`  Missing: ${missing.join(", ")}`);
  } else {
    console.log(`✓ ${skillDir}`);
  }
}

if (failed) {
  process.exit(1);
}
EOF

node check-skills.mjs plugins

如果刚才创建了 a11y-review，会看到：

text
✓ plugins/stitch-design/skills/a11y-review

在真实仓库中，这个检查可以接入 CI，用来防止新增技能缺少基础结构。

新增技能可以从哪些方向做

从设计生成链路扩展

适合新增为技能的方向：

候选技能	具体场景
`stitch::generate-onboarding-flow`	根据产品说明生成完整 onboarding 流程。
`stitch::generate-empty-states`	为列表页、搜索页、错误页生成空状态设计。
`stitch::generate-responsive-variants`	为同一页面生成 mobile、tablet、desktop 变体。
`stitch::generate-localized-screens`	根据语言和地区要求生成本地化界面变体。

判断标准：

是否有稳定、重复的用户请求？
是否需要独立的示例和资源？
是否会被其他技能复用？
是否比放在 generate-design 里更清晰？

从代码迁移链路扩展

适合新增为技能的方向：

候选技能	具体场景
`stitch::extract-design-tokens-from-code`	从 CSS、Tailwind、theme 文件中提取设计 token。
`stitch::map-components-to-stitch`	将前端组件映射到 Stitch 组件或设计结构。
`stitch::audit-code-to-design-readiness`	上传前检查前端项目是否适合转换。
`stitch::normalize-assets-for-upload`	统一整理图片、字体、图标资源。

这类技能要注意不要和 code-to-design 主流程重复。主流程可以调用它们，但它们应该有独立价值。

从设计系统治理扩展

适合新增为技能的方向：

候选技能	具体场景
`stitch::review-design-system`	检查 `DESIGN.md` 是否完整、一致。
`stitch::sync-design-tokens`	将 token 文件转换成 Stitch 可用的设计系统说明。
`stitch::theme-screen-set`	对一组屏幕批量应用主题。
`stitch::document-components`	根据组件生成设计系统文档。

这类技能应尽量围绕 DESIGN.md、token、主题、组件规范展开。

从质量检查扩展

适合新增为技能的方向：

候选技能	具体场景
`stitch::a11y-review`	检查对比度、字号、触控区域、状态表达。
`stitch::visual-consistency-review`	检查同一产品中间距、按钮、标题层级是否一致。
`stitch::design-handoff-review`	检查交付给开发前是否缺少状态、规格、资源。
`stitch::ux-flow-review`	检查流程是否有断点、重复步骤或缺失反馈。

质量检查类技能要区分“建议”和“自动修改”。默认只审查，除非用户明确要求修改设计。

新技能开发约束

一个技能只解决一个工作流

不要创建这样的技能：

text
stitch::design-everything

它太宽泛，代理很难判断何时使用，也很难维护。

更好的拆法：

text
stitch::generate-design
stitch::manage-design-system
stitch::a11y-review
stitch::code-to-design

每个技能都应该能用一句话说明：

当用户想要 X 时，使用这个技能完成 Y，并输出 Z。

依赖关系要写明

README 已经提醒：Stitch Design Skills 经常有相互依赖。选择性安装时，用户需要同时安装依赖技能。

因此新增技能时要在 SKILL.md 中写清楚：

markdown
## Dependencies

- stitch::manage-design-system, when applying a DESIGN.md theme.
- stitch::generate-design, when creating new screens before review.

如果没有显式依赖，也建议写：

markdown
## Dependencies

None.

Stitch MCP 是前置条件，不要隐藏

这些技能需要 Stitch MCP server 已经在代理环境中配置并运行。

技能不能假设 MCP 一定可用。遇到需要访问 Stitch 的操作时，应先确认：

MCP server 是否配置
用户是否有权限
必要环境变量和凭证是否存在
目标项目或设计是否可访问

技能说明中建议写：

markdown
## Prerequisites

The Stitch MCP server must be configured and available in the agent environment.

不要提交用户私有数据

禁止放入仓库：

用户真实设计稿
私有项目 URL
访问 token
cookie
内部接口地址
未脱敏截图
大体积上传产物

示例里可以使用占位符：

text
/path/to/dashboard
Dashboard-Migration-2026
https://stitch.withgoogle.com/projects/example

不要使用真实客户名称或内部项目名。

脚本要能在代理环境运行

很多代理会在受限环境里执行命令。脚本应避免：

要求全局安装冷门工具
默认写系统目录
弹出交互式 UI
依赖本地浏览器配置
静默联网下载大文件

示例要覆盖失败路径

除了成功案例，建议至少写一个输入不足的例子。

例如：

markdown
# Missing design URL

User request:

> Review my checkout page.

Expected behavior:

Ask the user for the Stitch design URL or the project/screen name before running the review.

这样代理不会在缺少关键信息时胡乱执行。

安装和验证时的常用命令

安装完整插件套件时，可以使用 Codex marketplace：

bash
codex plugin marketplace add google-labs-code/stitch-skills --ref main \
  --sparse .agents/plugins \
  --sparse plugins/stitch-design \
  --sparse plugins/stitch-build \
  --sparse plugins/stitch-utilities

Claude Code 项目级安装：

bash
npx plugins add google-labs-code/stitch-skills --scope project --target claude-code

Cursor workspace 级安装：

bash
npx plugins add google-labs-code/stitch-skills --scope workspace --target cursor

选择性安装技能：

bash
npx skills add google-labs-code/stitch-skills

查看工具帮助：

bash
npx plugins --help
npx skills --help

选择性安装时要特别注意依赖。比如只安装某个生成技能，但没有安装它依赖的设计系统管理技能，代理可能无法完整执行主题应用、token 对齐等步骤。

提交新技能前的检查清单

提交前至少确认：

技能目录包含 SKILL.md、scripts/、resources/、examples/。
SKILL.md 写清楚使用时机、输入、输出、工作流、限制。
技能名使用 stitch::<name> 格式。
依赖其他技能时已经显式说明。
需要 Stitch MCP 时已经写明前置条件。
示例包含至少一个真实场景。
脚本可以用命令行直接运行。
脚本参数和错误信息清楚。
没有提交密钥、私有 URL、用户数据。
没有把多个无关工作流塞进同一个技能。
资源文件体积合理，内容与技能直接相关。
选择性安装时不会让用户缺少关键依赖而不知情。

模块拆解：技能标准与扩展开发

技能标准与扩展开发

这个模块管什么

一个技能目录应该长什么样

SKILL.md 写的是技能契约

技能名

使用时机

输入和输出

scripts/ 放可重复执行的操作

resources/ 放技能运行时会参考的资料

examples/ 写给代理和维护者看

现有技能的开发口径

stitch::code-to-design

stitch::generate-design

stitch::manage-design-system

本地创建一个新技能骨架

检查技能目录是否合格

新增技能可以从哪些方向做

从设计生成链路扩展

从代码迁移链路扩展

从设计系统治理扩展

从质量检查扩展

新技能开发约束

一个技能只解决一个工作流

依赖关系要写明

Stitch MCP 是前置条件，不要隐藏

不要提交用户私有数据

脚本要能在代理环境运行

示例要覆盖失败路径

安装和验证时的常用命令

提交新技能前的检查清单

`SKILL.md` 写的是技能契约

`scripts/` 放可重复执行的操作

`resources/` 放技能运行时会参考的资料

`examples/` 写给代理和维护者看

`stitch::code-to-design`

`stitch::generate-design`

`stitch::manage-design-system`