使用手冊

GitHub Field Manual · Software Delivery

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

mblode/agent-skills 繁體中文實戰手冊,涵蓋 26 個架構、設計、寫作、品質、發布與技能製作工作流。

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

mblode/agent-skills
星標
63
分支
6
授權
—
資料截至
閱讀時間
10 分
更新日期
開啟原始報告
GitHub Stars
63
軟體交付技能
26
技能分類
6
開源授權
MIT

01工具定位

從產品判斷到發布驗證

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。

  1. Shape

  2. Plan

  3. Build

  4. Audit

  5. Tidy

  6. PR

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

02skills CLI

安裝全部或單一技能

官方 Quickstart 使用 skills CLI。執行預設安裝後,依互動提示選擇目標 Agent 與安裝範圍。

bash
npx skills add mblode/agent-skills

只安裝 pr-reviewer

只需要單一能力時,以 --skill 指定名稱。-g 代表全域安裝,-y 略過確認。

bash
npx skills add mblode/agent-skills -g --skill pr-reviewer -y

0326 個 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 UIui-audit稽核 code 與 rendered surface
需要先看 findings 的 local diffpr-reviewer唯讀報告
已授權直接清理的 local difftidy修改檔案並執行驗證

04官方操作規則

先辨識權限, 再執行技能

下列規則整理自官方 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

05跨技能交接

從互動決策到 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]


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.


# [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: 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.


# [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]
claude: FIXED: failed background deletion restores the active state.
# [lint · typecheck · tests pass]


$ 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/SKILL.md

權限與責任的交接

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

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

06使用限制

Mutation、發布與維護邊界

07進階路徑

建立分層的交付管線

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

— product-design/SKILL.md