實戰手冊 · Field Manual 2026 夏季號

github.com/mblode/agent-skills · 63 ★

GitHub Field Manual · Software Delivery

把軟體交付,
拆成 26 個
Agent Skills

mblode/agent-skills 收錄 26 個軟體交付技能，涵蓋架構、產品與 UI 設計、技術寫作、品質稽核、PR 與 npm 發布。README 明列 Claude Code、OpenCode、Codex 與 Cursor 相容。

GitHub Stars

軟體交付技能

技能分類

MIT

開源授權

工具定位

從產品判斷到
發布驗證

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.」

— mblode/agent-skills README

skills CLI

安裝全部或
單一技能

官方 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

安裝驗證:執行 ls ~/.claude/skills/pr-reviewer/。通過條件是目錄內存在 SKILL.md；部分技能另含 references/。

26 個 Agent Skills

六類交付工作的
責任邊界

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 權限分流。

TIP 01

以 artifact 分流設計技能

Brief、spec 與 mockup 由 product-design 決定行為；code、diff 或 running UI 交給 ui-audit。

來源 · product-design/SKILL.md

TIP 02

Product Design 不負責 styling

product-design 決定 control、scope、consequence 與 states；視覺與 code 建置轉交 ui-design。

來源 · product-design/SKILL.md

TIP 03

Planning 有 Create 與 Review 模式

Create mode 產出實作計畫；Review mode 驗證 claims，並評估 completeness、feasibility、scope、testability、risk 與 assumptions。

來源 · planning/SKILL.md

TIP 04

Review 與 Tidy 不可混用

pr-reviewer 只回報 findings；tidy 會直接修改 diff，並在完成後執行 build verification。

來源 · README Shipping

TIP 05

Tidy 先合併 findings 再改檔

四個 review agent 只回報；orchestrator 去重、移除 false positive、處理衝突後才套用修正。

來源 · tidy/SKILL.md

TIP 06

技能規範限制 body 長度

Agent skill 的 body 應低於 500 行；需要更多內容時拆到一層深度的 reference file。

來源 · repo AGENTS.md

TIP 07

Reference 必須由 SKILL.md 明列

只把檔案放進 references/ 不會自動載入；SKILL.md 必須明確列出讀取條件。

來源 · repo AGENTS.md Gotchas

TIP 08

Autoship 只處理 npm release

autoship 適用既有 changesets package；feature PR 使用 pr-creator，一般 PR 監看使用 pr-babysitter。

來源 · autoship/SKILL.md

TIP 09

Autoship 不在本機改版本

只 push pending changeset；Version Packages PR、version bump、changelog 與 npm publish 由 CI 接手。

來源 · autoship/SKILL.md

TIP 10

個人語氣資料留在 repo 外

tone-of-voice 內附虛構 persona；實際 profile 存在 ~/.config/tone-of-voice/，避免提交個人資料。

來源 · repo AGENTS.md Gotchas

跨技能交接

從互動決策到
PR 建立

下列示例以 workspace 刪除流程說明技能分工。先由 product-design 定義行為，再由 ui-design 建置，最後以 audit、review 與 PR 技能驗證。

~/projects/admin-console · codex

You › Use product-design to spec workspace deletion. Owners can delete; members cannot.

You › Apply product-design in action mode.

[loaded product-design/SKILL.md] [mode: action · authority: user constraints + AGENTS.md]

Agent › 先確認 object、scope、consequence、reversibility、permissions 與 reachable states。目前缺少資料保留期與背景刪除失敗時的 recovery policy。

Q1 / 刪除是立即且不可逆，還是排程後可取消？ Q2 / 失敗時 workspace 保持可用、唯讀，或顯示 recovery state？

You › 排程 7 天後刪除，期間 owner 可取消。背景工作失敗時恢復 active，保留 audit event 並通知 owner。

Claude › Decision: · CTA names object and consequence: Schedule workspace deletion · Members see no destructive control · Scheduled state exposes deadline and Cancel deletion

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

DECISION COMPLETE: Interaction contract and states are ready for implementation.

[saved docs/workspace-deletion-spec.md] [no code changed]

You › Use ui-design to implement the approved spec.

[reads project design system and approved spec] [implements owner-only action and all reachable states] [runs project verification commands]

Claude › Implementation complete. The next step checks rendered behavior and code-level UX. · Keyboard completion and visible focus · Failure recovery and input preservation · Member permission boundary

You › Use ui-audit on the changed route and local diff.

[returns severity-tiered findings and ship verdict]

You › Use pr-reviewer. Report only.

[reviews local diff · no files changed] [reports one P1 recovery-state gap]

You › Use tidy to fix the reviewed diff, then verify.

[four review agents return findings; orchestrator merges them] FIXED: failed background deletion restores the active state. [lint · typecheck · tests pass]

You › Use pr-creator to open the feature PR.

PR title and description created from the verified diff Reviewer guidance includes permission and recovery paths

「Dispatch on the artifact, not the topic.」

— product-design/SKILL.md

權限與責任的交接

Product Design 停在 decision altitude。它不修改 UI；ui-design 接手建置，ui-audit 驗證已完成的 code 與 rendered surface。

pr-reviewer 的 report-only 邊界可讓使用者先看 findings。只有使用者明確要求 tidy 時，工作流才會修改 diff 並重新執行驗證。

使用限制

Mutation、發布與
維護邊界

tidy 會直接修改工作樹。需要先看建議時改用 report-only 的 pr-reviewer。
autoship 包含外部狀態變更。完整模式會 push changeset、監看 CI、merge Version Packages PR 並確認 npm publish。
tidy 需要四個並行 review agent。不支援 subagent 的 host 無法完整執行原始工作流。
Repo 沒有自動測試套件。AGENTS.md 指定以安裝後的目錄 smoke test 驗證技能是否落盤。
文件數量曾發生 drift。docs/index.mdx 仍寫 24 個技能；目前 README、docs/skills.mdx 與資料夾均為 26 個。
Personal voice data 不應提交。tone-of-voice 的 repo 內容是虛構 persona；真實設定存於使用者 config 目錄。
ui.sh token 只屬於 maintainer 環境。重新同步 ui-design 來源時不可把 token 寫入 repo。
專案規則優先。技能明訂 user constraint、實際 codebase、AGENTS.md、設計系統與 sibling ownership 高於一般預設。

進階路徑

建立分層的
交付管線

先依 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.」