本技能面向 Diagram Design 项目的代码贡献者，而非普通使用者。资料明确说明：只有在直接修改 Diagram Design 本身（新增图表类型、修改 extractor、更换图标集）时才需要阅读本文件；普通用户只需使用 01–06 部分。
用途与定位 本文件提供一条能在 push 前于本地通过全部 CI 关卡的分支流程，内容全部为 shell 命令。它不依赖 01–06，但建议先读 04，因为 extractor 的退出码契约是不得破坏的部分。
准备工作 克隆仓库：
git clone git@github.com:cathrynlavery/diagram-design.git cd diagram-design python3 --version # 必须 >= 3.10；CI 在 Linux/Windows/macOS 上运行 3.11 和 3.12
无需 npm install，也没有强制 venv。仅两项可选依赖：
python3 -m pip install playwright && python3 -m playwright install chromium # 用于 lint-render + 渲染截图 python3 -m pip install "Pillow==12.1.1" # 用于校验 README 缩略图
两者的版本在 CI 中硬编码（PLAYWRIGHT_VERSION: "1.62.0"，PILLOW_VERSION: "12.1.1"）。ci.yml 中说明：lint-render.py 的判定基准是像素，因此浏览器是契约的一部分，升级 Playwright 与 Chromium 必须同时、有意识地完成。
流程规则（CONTRIBUTING.md §"Before you start"）：任何非琐碎改动（新类型、行为变更、触及 import 语法）先建 issue；小修与文档可直接提 PR；在分支上工作，绝不直接提交到 main；一个 PR 只做一件事。
规则一：不要在 PR 中提升版本号 三个 manifest（.claude-plugin/plugin.json、.codex-plugin/plugin.json、.factory-plugin/plugin.json）在每次合并后由 auto-bump.yml 在 main 上自动提升（ADR 0009）。PR 必须保持三者不变，CI 会拒绝任何对它们的改动：
python3 scripts/verify-plugin-package.py --require-no-bump origin/main
需要更大的 release？在 PR 描述中写明，维护者会在合并前打上 release:minor 或 release:major 标签。scripts/bump-plugin-version.py 仍存在，但只供 workflow 与维护者使用，贡献者不应运行。设计原因：避免各开放 PR 在每次合并时互相冲突。
SKILL.md 的 40,000 字节预算 semantic-pattern 关卡将 skills/diagram-design/SKILL.md 限制在 40,000 字节以内（ADR 0004；常量 MAX_SKILL_BYTES = 40_000 位于 scripts/verify-semantic-motion.py:23）。在 commit 4451ead 处测得 39996 字节，仅剩 4 字节。新增一个词就会使 CI 失败。该关卡失败时应减少重复，或把细节移到被路由的 references/ 文件；绝不能从 frontmatter 中移除路由词汇，因为那是技能在恰当时机被激活的关键。
push 前运行全部关卡 CONTRIBUTING.md 提供了一条约 48 条命令的 && 链，需原样粘贴执行，涵盖插件打包、维护者策略、无版本变更校验、claude plugin validate --strict、a11y lint、semantic-motion（markdown-only 与 example-only）、motion、skin lint、render lint、polar/sequence-oauth/drawio/mermaid 导入校验、doctor、文档同步、截图新鲜度、README 缩略图、self-check、几何、treemap、dumbbell、slopegraph、ridgeline、sankey、bubble、bump、beeswarm、skin-polarity 等各类校验及其配套测试。
模式特征：每个 verifier 都配有一个 test。verify-sankey.py 检查真实文件；test-verify-sankey.py 检查该 verifier 能否同时捕获正确与对抗用例。损坏的 linter 不允许报告仓库干净。修改 verifier 必须同步修改其测试。
在 macOS、Python 3.9.6、commit 4451ead 干净克隆下测得：lint-skin.py --all --baseline 返回 0（153 个文件检查，20 跳过，0 发现）；verify-geometry.py --all 返回 0（155 个文件，0 发现）；verify-semantic-motion.py --markdown-only 返回 0；verify-motion.py --shipped 返回 0；verify-drawio-import.py 与 verify-mermaid-import.py 均通过；verify-docs-sync.py 返回 0；test-self-check.py 返回 0；verify-plugin-package.py --current-only 返回 0（Claude/Codex/Factory 均为 2.6.12）；verify-doctor.py 返回 1。
verify-doctor.py 警告：它不是单元测试，而是真正运行 doctor 并按机器状况返回 rc。在 Python 3.9.6 上会输出 FAIL（3 pass, 1 warn, 1 fail），其中 FAIL 项为 Python 版本不满足 >= 3.10。该关卡失败源于环境而非改动，升级 python3 至 3.10+ 后重跑即可。Playwright 警告是已知的假阴性：scripts/verify-doctor.py:158 的探测使用了 playwright.version，而该包属性并不存在。部分关卡可在 3.9 运行（CI 另有 python39-compat 任务运行 test-lint-a11y.py 与 lint-skin.py --all --baseline），但开发需要 3.10+。
如何阅读关卡错误 verify-plugin-package.py 报告版本变更时，从分支中撤销 manifest 修改；报告打包问题时，保持所有 marketplace 指向根仓库，技能共用 skills/diagram-design/SKILL.md。lint-skin.py 会给出文件、行号与类别（color、font-family、a11y、external-asset、pure-black、script）。颜色须取自 style-guide.md 的 palette，字体须来自允许列表；linter 还要求 verbatim 使用 template-motion.html 中的 pin-SHA controller，并拒绝远程资源、CSS @import、非 fragment 的 CSS url()、事件处理器、srcdoc、可执行 URL 及多余脚本。verify-*.py 失败表示 extractor 行为不再匹配 fixture/文档，或 reference/command/prompt 接线错位；应修正事实来源，而非放宽测试。verify-geometry.py 失败表示 label mask 与其后声明的节点重叠，需把 label 移到连接线空白段，按 SKILL.md §6 保持与线条 6–10px 间距，不得缩小 mask 规避。verify-slopegraph.py 失败表示两轴刻度/原点不一致或端点绘制位置错误，应修正坐标而非标签。verify-ridgeline.py、verify-bubble.py、verify-bump.py、verify-beeswarm.py、verify-skin-polarity.py、verify-treemap.py 各有对应的几何与语义约束说明。verify-screenshot-freshness.py 失败时安装 Playwright，运行 python3 scripts/render-canonical-screenshots.py，检查全部 39 个渲染，然后提交新 PNG 与 docs/screenshots/manifest.json。build-readme-thumbs.py --check 失败时安装 Pillow==12.1.1，运行 build-readme-thumbs.py，提交 WebP 与 docs/screenshots/thumbs/manifest.json。修改 scripts/vendor/icons/ 或 scripts/build-icons.py 后产物过期时，运行 python3 scripts/build-icons.py 并提交 icons.html 与 references/primitive-icons.md。
最重要的禁止规则：不要为规避而向 scripts/lint-skin-baseline.txt 添加文件。该 baseline（当前 20 行）仅用于前 2.0 时代的 legacy example，且它们仍受 a11y 检查；新增文件即属作弊。
按变更类型选择的最小关卡：新增 example 先跑 lint-skin.py 单文件再跑 --all --baseline；新增图表类型需添加 references/type-*.md + example + SKILL.md §3 表格条目，然后跑 verify-docs-sync.py + lint-skin.py --all + 检查 40,000 字节预算；触及导入路径跑 verify-drawio-import.py + test-verify-drawio-import.py + verify-mermaid-import.py；图标集改动跑 build-icons.py 后对 icons.html 与 primitive-icons.md 执行 git diff --exit-code；motion 改动跑 verify-motion.py --shipped + test-verify-motion.py + verify-semantic-motion.py（两种 mode）；doctor 改动跑 verify-doctor.py + test-verify-doctor.py；任何文档改动跑 verify-docs-sync.py（它同时检查 reference 链接与 command/prompt 表面）。
ADR：docs/adr/ 有 9 项决策，最常涉及的是 0001（默认静态、单一 pin controller）、0003（reveal 是唯一允许的 autoplay）、0004（SKILL.md 字节阈值 + 富触发 description）、0009（合并后在 main 上 bump 版本，而非 PR 内）。另见 docs/cookbook.md（操作配方）与 docs/superpowers/（新类型的 plan 与 spec 模板，以 polar chart 为例）。
完成条件：完整 && 链在本地全绿（verify-doctor.py 需 Python 3.10+ 才绿）；diff 中没有任何 manifest 版本被改动；wc -c < skills/diagram-design/SKILL.md 仍低于 40,000；scripts/lint-skin-baseline.txt 中没有新增行。