impeccable

1实现原理 · 为什么它能做到

编译式多宿主分发：skill/ 是唯一 master 源（SKILL.src.md + scripts/ + reference/ + agents/），同一时刻仓库内已有 .claude/.cursor/.agents/.gemini 等 20 个宿主目录的编译副本，副本把占位符（{{scripts_path}}/{{command_hint}}…）展开为宿主路径、写入宿主 frontmatter（如 version: 4.3.1、user-invocable、allowed-tools）并剥掉  一致性注释。

skill/SKILL.src.md

allowed-tools: - Bash(npx impeccable *) - Bash({{scripts_path}}/impeccable *)

注：对照 .claude/skills/impeccable/SKILL.md 前 20 行可见同一段展开为 '.claude/skills/impeccable/scripts/impeccable *' 并带 'version: 4.3.1'——diff 证实两文件除占位符展开与 rule 注释外逐字相同。

会话启动协议：每会话先跑 `<skill-base-dir>/scripts/impeccable context`（launcher 是 POSIX shell，定位自含引擎二进制），让引擎读入 PRODUCT.md/DESIGN.md/匹配的 surface brief 并把指令（含 CONTEXT_STALE 等 directive）交回 agent；launcher 失败有显式降级——明示后直接读现有 PRODUCT.md/DESIGN.md 继续。

.claude/skills/impeccable/SKILL.md

Run `<skill-base-dir>/scripts/impeccable context` once per session, where `<skill-base-dir>` is the directory that contains this SKILL.md (the skill folder, not a plugin root two levels above it); keep cwd at the user's project.

注：降级协议原文：'On refusal or failure, send a separate message **before the next tool call**: "Context loading did not run; I'll read the existing project context directly."'——launcher 故障不阻塞规划与编辑。

能力核心是随附引擎二进制（非 Node 运行时）：launcher 按序找 IMPECCABLE_BIN → 同目录 bin/<os>-<arch>/ → ~/.impeccable/bin → 版本钉住缓存 → PATH 上的 impeccable，最后兜底从作者 GitHub release 下载该版本二进制到用户缓存并做 sha256 sidecar 校验（fail closed：校验缺失/不符即拒绝执行）。

skill/scripts/impeccable

base="${IMPECCABLE_DOWNLOAD_BASE:-https://github.com/pbakaus/impeccable/releases/download}"

注：下载段原文 'Last resort: fetch this version's binary for the current platform from the public release channel into the user cache'；校验段 'Fail closed: a freshly downloaded binary runs only after verifying against its .sha256 sidecar.'；无外网 sandbox 可预装二进制到 PATH（launcher 注释自述）。

23 命令 + routing 的指令面：SKILL.md 主体是一张命令表（Build/Evaluate/Refine/Enhance/Fix + live 迭代），无参调用只出 context-aware 菜单绝不自动跑命令；每个命令对应 reference/ 下独立 playbook，规则以  标记嵌入源文件供发布期一致性检查。

.claude/skills/impeccable/SKILL.md

**No argument:** read [routing.md](reference/routing.md) and present its context-aware menu; never auto-run a command.

注：README 自述 '1 skill, 23 commands'；命令表实际行数 23（含 deprecated 的 craft）；reference/ 目录 35+ 个 playbook（init/shape/audit/polish/live/hooks/craft-floor…），另有 degraded/ 与 agents/*.md 子代理提示。

PRODUCT.md/DESIGN.md 双文档持久真相：init 只写 PRODUCT.md（产品真相：用户/任务/约束/平台），不碰视觉世界；document/extract 从成品代码反写 DESIGN.md（设计系统/token/组件），视觉方向在 new-work 决定并替换 DESIGN.md——『证据是权威，不是文件名』。

skill/reference/init.md

`init` captures durable product truth in PRODUCT.md. It does not invent a visual world and does not write DESIGN.md; [new-work.md](new-work.md) creates or expands one, and [document.md](document.md) records an incumbent one.

注：SKILL.md 三条『How to design』原则把改写语义定死：'Refinement preserves; redesign replaces.' + 'Visual authority is evidence, not a filename.'；brief 优先：'**The brief wins.** Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning.'

确定性检测器（61 条规则）以 hook 形式内建到宿主：hooks on 后 Claude Code/Codex/Copilot 用 post-tool-use hook 在每次 UI 文件编辑后自动跑检测器并把发现推回上下文；Cursor 用 preToolUse 在坏写入落地前拦截。配置在 .impeccable/config.json（本地覆盖 .impeccable/config.local.json）。

skill/reference/hooks.md

The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`).

注：Cursor 拦截语义原文：'Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.'；README 声明 61 条确定性规则 'run the deterministic rules with no LLM and no API key'；每次编辑即触发 + session Stop 时深扫全量，是『检测器-钩子-上下文』闭环。

live 浏览器变体模式：在本地 dev server（HMR）上把选中元素交给 AI 生成 HTML+CSS 变体热替换；通过轮询事件循环（_instructions 字段为权威下一步）与 .impeccable/live/ 会话 journal 保证断线可恢复；明文禁止注入生产站点/削弱 CSP。

skill/reference/live.md

Interactive live variant mode: select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via the dev server's HMR.

注：边界原文：'Live editing requires a local checkout; injection into deployed production sites (including HTTPS) is unsupported. …Do not disable browser security or weaken production CSP to enable live mode.'

2核心能力

0123 命令设计词汇表：craft/shape/init/document/extract（Build）、critique/audit（Evaluate）、polish/bolder/quieter/distill/harden/onboard（Refine）、animate/colorize/typeset/layout/delight/overdrive（Enhance）、clarify/adapt/optimize（Fix）、live（Iterate）

02PRODUCT.md 产品真相捕获（init：用户/任务/机制/约束，禁问视觉偏好）+ DESIGN.md 设计系统记录（document/extract：从成品反写 token/组件）

0361 条确定性检测器（无 LLM 无 API key 本地跑，覆盖 AI slop 模式与通用设计质量）+ per-edit/Stop 两级 hook 接入宿主

04craft-floor 编辑前必读：质量地板、绝对禁令、检测器抓不到的 reflexes

05live 浏览器变体迭代（HMR 热替换、事件轮询、journal 恢复、禁止生产注入）

06模式分类学（Persuade/Operate/Read/Experience）+ 模式持久化纪律（只落在对应 surface brief）

07版本化引擎自管理：doctor 修复 PRODUCT.md/DESIGN.md/config/hook 漂移；pin/unpin 生成独立快捷命令；引擎多级定位 + sha256 校验下载

08验证预算纪律：bounded passes 上限覆盖整周期，禁无休止自 QA

3外部依赖

类型	依赖
cli	impeccable 引擎（自含二进制，随 skill 的 scripts/impeccable launcher 定位/下载；技能通过 Bash 调用）
network	引擎二进制下载通道（仅首次且缺二进制时）：GitHub Releases，engine-v<version> 资产 + .sha256 sidecar
package	npx impeccable（SKILL 授权 Bash(npx impeccable *) 的发布安装路径；README quick start 亦用 npx impeccable install）
network	文档站/知识引用（非运行时调用）：impeccable.style、github.com/pbakaus/impeccable（README/docs 内链接）、google-labs-code/design.md spec（reference/document.md 内引用）

4风险提醒风险提醒：黄色 · 留意使用

风险提醒：黄色 · 留意使用

供应链集中：核心能力是作者 release 通道的二进制，首次使用需联网下载并执行远程代码（sha256 校验只防传输损坏/通道劫持，不防作者侧投毒）。 — skill/scripts/impeccable 下载段；无外网环境须 IMPECCABLE_BIN/预装
hook 自动执行面：启用后每次 UI 文件编辑都会跑检测器并写宿主 manifest；多宿主清单（含团队共享的 .github/hooks/impeccable.json）意味着 hook 可随仓库传播到协作者。 — hooks.md 支持的 harness 清单与 'on' 动作安装/修复 manifest
live 注入面：向本地 dev server 页面注入 JS、信任引擎回传的 _instructions；页面内容（可能含敏感数据）会进入生成上下文。 — live.md '_instructions…is the authoritative next step'
设计判断集中化：61 规则与 craft-floor 由作者（及其审美）定义，输出会强烈偏向 impeccable 的风格观；'out-of-distribution craft' 承诺本质是主观标准，可能不适合追求保守/品牌自有的团队。 — SKILL.md 开场 'award-winning design director' 定位 [INFERENCE]

风险提醒：黄色，留意使用。接触面：① 网络外发唯一且可预期——首次运行时从作者官方 GitHub Releases 下载引擎二进制（sha256 sidecar 校验、版本钉住、fail-closed，可 IMPECCABLE_BIN/离线预装规避），属常规官方通道下载；② 本地写面广：PRODUCT.md/DESIGN.md/.impeccable 配置、hook manifest 写入宿主清单（.claude/settings.local.json 等）并让检测器在每次 UI 编辑后自动运行；③ 无凭证读取、无第三方外发。注意点：引擎二进制供应链、hook 自动执行面、live 注入面，均需用户知情使用（默认仅在用户安装/启用后生效）。

5第二遍独立确认

[ok] 单一 master 源 + 多宿主编译副本 — diff skill/SKILL.src.md 与 .cursor/.claude 副本：差异仅为占位符展开（{{scripts_path}}→宿主路径）、frontmatter 增删（version/argument-hint/allowed-tools）、 注释剥离；正文结构一致。
[ok] 每会话 context + 降级协议 — 编译副本与 src 均含 Setup 三步与 'Launcher unavailable' 段；引文逐字存在。
[ok] 引擎二进制下载仅首次且 fail-closed — launcher 第 60-200 行精读：候选顺序 IMPECCABLE_BIN→sibling bin→~/.impeccable/bin→version cache→PATH probe→下载；下载后必须 sha256 sidecar 匹配才 chmod+mv+exec，sidecar 不可得/不匹配/空文件均拒绝（exit 127）。
[ok] 61 规则与无 LLM 声明 — README 两处声明一致（'61 deterministic detector rules'、'no LLM and no API key'）；hooks.md 描述 per-edit 与 Stop 深扫两级；规则实体位于引擎二进制内（本仓库 skill 目录不含规则源码，属引擎发布物 [INFERENCE]）。
[ok] 23 命令数 — SKILL.md 命令表逐行计数 = 23（craft 为 deprecated alias 仍列）；与 README '23 commands' 一致。
[ok] hook 安装面与宿主 manifest — hooks.md 列出全部宿主清单路径（.claude/settings.local.json/.cursor/hooks.json/.codex/hooks.json/.github/hooks/impeccable.json/.grok/hooks/impeccable.json）；'reset' 动作会从 on 安装过的 manifest 移除条目。
[ok] live 仅限本地 + journal 恢复 — live.md 明确 'requires a local checkout'、'injection into deployed production sites (including HTTPS) is unsupported'；.impeccable/live/sessions/ journal 与 live-status/resume 流程存在。
[ok] 无凭证读取 — skill 目录（src/scripts/reference/agents + 编译副本）无 API key/token/secret/.env 读取代码；引擎行为以 README『no API key』声明 + 引文为据（引擎二进制内部未逐一审计 [INFERENCE]）。

6结论

把『设计质量』工程化为确定性检测器 + 宿主 hook（编辑即触发、坏写入前置拦截），不只是又一份 prompt 建议。

双文档权威模型 + 改写语义（brief wins / refinement preserves / redesign replaces）防止 agent 用个人品味覆盖用户既定方向，是同类设计 skill 少有的纪律。

编译式多宿主分发让同一技能在 20 个宿主行为一致，且 rule 注释可机检发布一致性——工程治理成熟。

launcher 下载 fail-closed（sha256 sidecar 校验 + 版本钉住 + 可预装规避），网络面单一且自述『sandboxes without egress preinstall the binary on PATH』。

失败语义工程化：launcher 降级、live journal 恢复、CONTEXT_STALE 只报不修、bounded passes 验证预算——工具不可用/数据过期都有定义好的出路。

适合：适合认真做前端设计/重构、愿意为质量闸门安装引擎与 hook 的 AI 编码用户（Claude Code/Cursor/Codex 等）；适合有 PRODUCT.md/DESIGN.md 双文档习惯或想建立的团队；适合需要确定性 a11y/质量检测与『编辑即触发』拦截的工程流程；首次使用前需联网下载引擎（或预装二进制）。

不适合：不适合纯后端/非 UI 任务（description 自述 'Not for backend-only or non-UI tasks.'）；不适合不允许任何本地 hook 自动运行或零网络沙箱（可用 hooks off + 手动 detect + 预装规避，但体验打折）；不适合不接受『引擎二进制+作者审美标准』的零信任/最小化环境；追求自由发挥而非既定设计纪律的创意流程会感到被约束。

安装 agent 直装可复制

① 本站镜像更新 2026-09-09

方式 A · 人下载镜像包下载 impeccable.tar.gz

sha256: 1467f7553455c007…

方式 B · JSON 格式安装指南，复制给 agent

安装指南

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② 上游 GitHub · 原始来源

能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗

本页镜像锁定 commit cd12f8660e；上游为实时仓库。

来源信息 GitHub 原始

作者 / 仓库pbakaus / pbakaus/impeccable

原始 GitHubpbakaus/impeccable ↗

Stars66816

最近推送2026-09-09

本 skill commitcd12f8660e

许可Apache-2.0（GitHub API spdx Apache-2.0；仓库根 LICENSE 文件为 Apache License Version 2.0, January 2004）

本站信息

收录日期2026-09-06

分类基础工具与工作流

侦查报告2026-09-06 · 2 遍

本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。

1实现原理 · 为什么它能做到

2核心能力

3外部依赖

4风险提醒 风险提醒：黄色 · 留意使用

5第二遍独立确认

6结论

4风险提醒风险提醒：黄色 · 留意使用