從產品判斷到發布驗證
mblode/agent-skills 是一組以 SKILL.md 為核心的軟體交付工作流。技能按 artifact 與執行階段分工,包含決策型、建置型、唯讀稽核型與會直接修改或發布的執行型技能。
設計技能明確區分 product-design、ui-design 與 ui-audit 的 authority。PR 流程則區分唯讀的 pr-reviewer、直接修正 diff 的 tidy、建立 PR 的 pr-creator 與監看的 pr-babysitter。
Repo 也包含架構 scaffolding、技術文件、SEO、AX/DX 稽核與 changesets-based npm release。使用前先確認技能是否只回報、會改檔,或會執行 push、merge 與 publish。
Shape
Plan
Build
Audit
Tidy
PR
Release
「Code review catches logic bugs. Nobody checks the loading states, the type scale, or whether half the diff is AI slop. These skills do.」
安裝全部或單一技能
官方 Quickstart 使用 skills CLI。執行預設安裝後,依互動提示選擇目標 Agent 與安裝範圍。
npx skills add mblode/agent-skills只安裝 pr-reviewer
只需要單一能力時,以 --skill 指定名稱。-g 代表全域安裝,-y 略過確認。
npx skills add mblode/agent-skills -g --skill pr-reviewer -y六類交付工作的責任邊界
README 將技能分成架構、設計、寫作、品質、發布與 authoring 六類。先依現有 artifact 與動作選技能,特別區分 report-only 與會修改或發布的流程。
Architecture · 01
define-architecture
系統邊界
定義 TypeScript app 的目錄、module contract、middleware pipeline 與 agent guardrail。
Architecture · 02
scaffold-nextjs
Next.js 骨架
建立 TypeScript turborepo、Blode UI、Ultracite、GitHub 與 Vercel 配置。
Architecture · 03
scaffold-cli
CLI 與 npm 套件
建立 ESM、雙 tsdown build、vitest、Ultracite、changesets 與 GitHub Actions。
Architecture · 04
multi-tenant-architecture
多租戶架構
規劃 Cloudflare 或 Vercel 的 domain、tenant isolation、routing 與 custom domain。
Design · 05
product-design
互動決策
在建置前決定 interaction、action scope、reachable states、resilience 與 accessibility。
Design · 06
ui-design
UI 建置
建立視覺方向、Tailwind UI、比較版本、dark mode、responsive 與 component extraction。
Design · 07
ui-animation
介面動態
設計、實作、審查與逆向分析 spring、gesture、easing 與 CSS transition。
Design · 08
presentation-creator
簡報製作
建立 dark-first deck、敘事結構、speaker notes 與 QA pass。
Writing · 09
copywriting
產品文案
撰寫短文案、UI states、CTA,並執行七輪 audit 與 AI-ism 清理。
Writing · 10
blog-post
長篇內容
從來源或 brief 建立 listicle、tutorial、narrative 與 thought leadership。
Writing · 11
docs-writing
技術文件
以 Diataxis 與 Stripe-style clarity 執行寫作或 52-rule audit。
Writing · 12
readme-creator
README 製作
辨識 CLI、library、app、framework、monorepo 或 skill bundle,再套用對應結構。
Writing · 13
tone-of-voice
個人語氣
依 Slack、email、WhatsApp、LinkedIn 與 Linear profile 草擬或改寫訊息。
Quality · 14
ui-audit
前端 UX 稽核
以 95 rules、12 playbooks 與三層 ship verdict 審查 React/Next.js UI。
Quality · 15
ax-audit
Agentic UX 稽核
以 23 條架構與信任規則輸出 ship verdict 與 AX Relationship Summary。
Quality · 16
dx-audit
Developer UX 稽核
檢查 API、SDK、CLI、types、onboarding、bundle 與 configuration ergonomics。
Quality · 17
typography-audit
排版稽核
以 10 類 90 條規則檢查字體、尺寸、間距、OpenType、層級與配對。
Quality · 18
optimise-seo
Next.js SEO
處理 sitemap、metadata、structured data、hreflang、CWV、headers 與 resilience。
Shipping · 19
planning
計畫建立與審查
Create mode 建立計畫;Review mode 驗證 codebase claims 並評分六個維度。
Shipping · 20
pr-reviewer
唯讀 PR 審查
依嚴重度回報 bug、結構品質、AI slop 與按需 security finding,不修改檔案。
Shipping · 21
tidy
Diff 修正
並行執行 reuse、quality、efficiency 與 test-discipline review,再套用修正。
Shipping · 22
pr-creator
PR 建立
建立簡短、人寫語氣的 PR 描述,處理 Linear ID、commit 結構與 reviewer guidance。
Shipping · 23
pr-babysitter
PR 監看
持續檢查 conflict、CI、review comment 與 merge readiness,並修正安全範圍內的問題。
Shipping · 24
autoship
npm 發布
完成 changeset、quality gates、CI、Version Packages PR、publish 與 npm 驗證。
Authoring · 25
agents-md
指令檔稽核
以 10-check triage 或 45-check full audit 重構 AGENTS.md 與 CLAUDE.md。
Authoring · 26
agent-skills-creator
Skill 製作
依 open format spec 建立或改善技能、frontmatter、references 與漸進式揭露。
依 artifact 與授權選技能
| 目前 artifact | 技能 | 行為 |
|---|---|---|
| Brief、spec、mockup 或未定案流程 | product-design | 決定 interaction 與 states,不寫 code |
| 已建置的 React/Next.js UI | ui-audit | 稽核 code 與 rendered surface |
| 需要先看 findings 的 local diff | pr-reviewer | 唯讀報告 |
| 已授權直接清理的 local diff | tidy | 修改檔案並執行驗證 |
先辨識權限, 再執行技能
下列規則整理自官方 README、AGENTS.md 與技能檔。相近技能以 artifact、動作與 mutation 權限分流。
以 artifact 分流設計技能
Brief、spec 與 mockup 由 product-design 決定行為;code、diff 或 running UI 交給 ui-audit。
來源 · product-design/SKILL.md
Product Design 不負責 styling
product-design 決定 control、scope、consequence 與 states;視覺與 code 建置轉交 ui-design。
來源 · product-design/SKILL.md
Planning 有 Create 與 Review 模式
Create mode 產出實作計畫;Review mode 驗證 claims,並評估 completeness、feasibility、scope、testability、risk 與 assumptions。
來源 · planning/SKILL.md
Review 與 Tidy 不可混用
pr-reviewer 只回報 findings;tidy 會直接修改 diff,並在完成後執行 build verification。
來源 · README Shipping
Tidy 先合併 findings 再改檔
四個 review agent 只回報;orchestrator 去重、移除 false positive、處理衝突後才套用修正。
來源 · tidy/SKILL.md
技能規範限制 body 長度
Agent skill 的 body 應低於 500 行;需要更多內容時拆到一層深度的 reference file。
來源 · repo AGENTS.md
Reference 必須由 SKILL.md 明列
只把檔案放進 references/ 不會自動載入;SKILL.md 必須明確列出讀取條件。
來源 · repo AGENTS.md Gotchas
Autoship 只處理 npm release
autoship 適用既有 changesets package;feature PR 使用 pr-creator,一般 PR 監看使用 pr-babysitter。
來源 · autoship/SKILL.md
Autoship 不在本機改版本
只 push pending changeset;Version Packages PR、version bump、changelog 與 npm publish 由 CI 接手。
來源 · autoship/SKILL.md
個人語氣資料留在 repo 外
tone-of-voice 內附虛構 persona;實際 profile 存在 ~/.config/tone-of-voice/,避免提交個人資料。
來源 · repo AGENTS.md Gotchas
從互動決策到 PR 建立
下列示例以 workspace 刪除流程說明技能分工。先由 product-design 定義行為,再由 ui-design 建置,最後以 audit、review 與 PR 技能驗證。
$ You ›
Use product-design to spec workspace deletion. Owners can delete; members cannot.
$ You › Apply product-design in action mode.
claude: Agent ›
先確認 object、scope、consequence、reversibility、permissions 與 reachable states。
目前缺少資料保留期與背景刪除失敗時的 recovery policy。
hl: Q1 / 刪除是立即且不可逆,還是排程後可取消?
hl: Q2 / 失敗時 workspace 保持可用、唯讀,或顯示 recovery state?
$ You ›
排程 7 天後刪除,期間 owner 可取消。背景工作失敗時恢復 active,
保留 audit event 並通知 owner。
claude: Claude ›
Decision:
· CTA names object and consequence: Schedule workspace deletion
· Members see no destructive control
· Scheduled state exposes deadline and Cancel deletion
hl: Required states: idle, confirming, scheduled, cancelling, failed, deleted.
[writes compact internal brief]
1. User and job
2. Object, scope and consequence
3. Reversibility and permissions
4. Reachable states and recovery
5. Success signal and non-goals
[routes follow-on work]
· ui-design owns implementation
· copywriting owns final UI strings
· ui-audit owns built-result verification
ok: DECISION COMPLETE:
ok: Interaction contract and states are ready for implementation.
$ You › Use ui-design to implement the approved spec.
claude: Claude ›
Implementation complete. The next step checks rendered behavior and code-level UX.
hl: · Keyboard completion and visible focus
hl: · Failure recovery and input preservation
hl: · Member permission boundary
$ You › Use ui-audit on the changed route and local diff.
$ You › Use pr-reviewer. Report only.
$ You › Use tidy to fix the reviewed diff, then verify.
claude: FIXED: failed background deletion restores the active state.
$ You › Use pr-creator to open the feature PR.
ok: PR title and description created from the verified diff
ok: Reviewer guidance includes permission and recovery paths
「Dispatch on the artifact, not the topic.」
權限與責任的交接
**Product Design 停在 decision altitude。**它不修改 UI;ui-design 接手建置,ui-audit 驗證已完成的 code 與 rendered surface。
pr-reviewer 的 report-only 邊界可讓使用者先看 findings。只有使用者明確要求 tidy 時,工作流才會修改 diff 並重新執行驗證。
Mutation、發布與維護邊界
建立分層的交付管線
先依 artifact 與 mutation 權限建立技能路由,再把專案命令、設計系統與發布政策寫入 AGENTS.md。技能只補充專案尚未定義的操作規則。
進階玩法地圖
**1. 建立決策層。**用 product-design 與 planning 固定行為、scope、states、風險與驗證條件。
**2. 建立實作層。**依需求交給 ui-design、scaffold-nextjs、scaffold-cli 或既有專案程式碼。
**3. 建立驗證層。**依 surface 使用 ui-audit、ax-audit、dx-audit、typography-audit 或 optimise-seo。
**4. 建立變更層。**先用 pr-reviewer 檢視 findings;需要直接修正時再授權 tidy。
**5. 建立發布層。**使用 pr-creator、pr-babysitter 管理 feature PR;只有 npm changesets release 使用 autoship。
最該讀的三份延伸閱讀
① README.md:26 個技能與安裝方式。 ② product-design/SKILL.md:設計責任、mode 與 authority。 ③ autoship/SKILL.md:changesets release 與安全條件。
「One artifact often needs both in sequence: product-design decides the states that must exist, ui-audit verifies the built result.」