extract

extract 技能總覽

extract 能做什麼

extract 技能可協助你把重複出現的 UI 程式碼整理成可重用的 design system 資產：共享元件、design tokens，以及標準化模式。它是為已經有產品 UI、想把零散重複收斂成更有系統做法的團隊而設計，不是給只想要一個通用腦力激盪提示的人使用。

extract 最適合哪些人

extract 對前端工程師、design-system 維護者，以及想清理不同畫面或功能之間漂移問題的產品團隊特別有用。尤其當你已經懷疑同一種 button、card、form pattern、spacing scale 或 color 用法在多處重複出現，而且應該被統一起來時，它會很適合。

extract 真正要解決的工作

extract 技能的真正價值，不只是「找出重複」。它會推動 agent 去：

• 先找到既有的 design system 或共享 UI layer
• 辨識真正值得抽取的模式
• 避免過早抽象化
• 有計畫地把重複程式碼遷移到可重用系統中

這讓它比一般「幫我重構這段 UI」的 prompt 更實用，尤其是在 extract for Design Systems 這類工作中，命名、結構與遷移風險都很關鍵。

這個 extract 技能有什麼不同

這個技能有明確的工作流程：先探索現有系統、找出可抽取候選、判斷是否真的值得系統化，接著再謹慎地抽取與遷移。它其中一個最有力的差異點，是有一條很明確的 guardrail：如果目前根本沒有 design system，它會先要求 agent 詢問，而不是自行憑空創建。這能降低一種常見失敗情境：AI 產生一套與 repository 完全不相容的任意元件架構。

什麼時候該安裝 extract

如果你的主要需求是把重複的 UI 模式收斂進既有或預計建立的 design system，那就值得安裝 extract。如果你只是想快速做出一個一次性的元件，直接下 prompt 可能就夠了。當你更在意一致性、可重用性與遷移品質，而不只是速度時，安裝 extract 的判斷才特別合理。

如何使用 extract 技能

安裝 extract 技能

一個實用的安裝指令是：

npx skills add https://github.com/pbakaus/impeccable --skill extract

由於這個技能位於 .claude/skills/extract，你不需要先掃完整個 repository 才能開始使用。

先讀這個檔案

請先從這裡開始：

• SKILL.md

在這個案例裡，SKILL.md 就是主要依據。從 repository 證據來看，沒有額外暴露出 scripts、rules 或 reference folders，因此大部分可直接使用的指引都集中在這個檔案中。

先了解預期的呼叫方式

這個技能被標記為可由使用者直接呼叫，並提供如下參數提示：

[target]

實務上，這代表你的請求應該點名一個具體目標區域，例如：

• 某個 feature folder
• 某一頁面
• 一組元件
• 一個有重複模式的 UI surface

像「improve our design system」這種模糊請求，效果會遠不如「run extract on src/features/billing and identify reusable form and card patterns」。

給 extract 一個明確目標，不要只給寬泛願景

extract 技能在目標邊界清楚時效果最好。好的目標通常會落在以下幾種：

• 一個有重複 UI 的目錄
• 一個明顯存在不一致的產品區域
• 從 hard-coded styles 遷移到 tokens 的工作
• 一群應該被整理成 variants 的相似元件

這能提高訊號品質，因為這個技能的設計是用來判斷真實的重用機會，而不是在抽象層面憑空發明 abstraction。

把模糊目標改寫成更強的 extract prompt

弱的 prompt：

• “Use extract on our app.”

更強的 prompt：

• “Use extract on src/app/settings and src/components/settings. Find repeated controls, hard-coded spacing and color values, and any patterns already close to our shared UI conventions. Propose what should become a shared component or token, what should stay local, and a safe migration order.”

為什麼這樣更有效：

• 它明確指出目標範圍
• 它把元件抽取與 token 抽取分開要求
• 它要求判斷哪些應維持 local，能降低過度抽象化
• 它要求遷移排序，而這在真實 repository 中非常重要

哪些輸入能實質提升輸出品質

想讓 extract usage 更好，建議提供：

• 你現有 design system 或 shared UI folder 的位置
• framework 與 styling stack，例如 React、Tailwind、CSS Modules 或 styled-components
• 你目前使用的命名慣例
• 任何 token source、theme file 或 style dictionary
• 你要的是 proposal only，還是直接修改程式碼

沒有這些上下文時，agent 仍能辨識重複，但提出的抽取方案更容易和你的架構衝突。

依照 repository 預期的工作流程來用

這個技能的流程很簡單，但很重要：

1. 找出 design system
2. 辨識重複模式與 hard-coded values
3. 評估是否真的值得抽取
4. 抽取並補強系統
5. 遷移使用端

其中「先評估價值再抽取」這一步非常關鍵。技能本身明確提醒：不是所有東西都該被抽取。只出現一兩次的模式，可能還不到應進入共享系統的時候。

把 extract 用在 Design Systems，不只是去重

extract for Design Systems 最好的用法，不是機械式刪除重複程式碼，而是判斷哪些東西應該放進 system layer，哪些應維持 feature-local code。你可以要求技能把發現分類成：

• 可重用元件
• design tokens
• composition patterns
• 應保留在原地的 local-only code

這樣產出的結果，才會是你真的能審查並採用的內容。

先要 proposal，再要求實作修改

一個實際可行的導入流程如下：

1. 先請 extract 提出 findings 與候選項
2. 審查命名、歸屬與遷移範圍
3. 再要求它實作抽取
4. 分小批次遷移

這會比一開始就要求它橫跨整個 app 直接動手改安全得多，尤其當你目前的 design system 還不完整時更是如此。

通常效果不錯的 prompt 模式

可以使用像這樣的請求：

“Use extract on [target]. First locate our existing design system or shared UI directory and summarize its conventions. Then identify repeated components, inconsistent variants, and hard-coded visual values worth turning into tokens. For each candidate, say whether it should be extracted now, deferred, or kept local. After that, propose a migration plan with the lowest-risk order.”

這種寫法和技能原生工作流程高度對齊，通常比一般泛泛的 refactor request 更能得到高品質輸出。

執行 extract 前要先決定的常見限制

在使用 extract 技能前，先決定以下事項：

• agent 可以建立新的 shared components，還是只能提出建議？
• 現在要導入 tokens，還是只做元件整併？
• 你是否需要嚴格的 backward compatibility？
• imports 與 file locations 能不能變動？

這些限制會實質改變建議內容。當技能知道自己是在規劃、實作，還是遷移時，它的價值會高很多。

extract 技能 FAQ

extract 會比一般 refactor prompt 更好嗎？

通常會，前提是你的問題是「系統化整理」，而不是單點清理。一般 prompt 很容易直接跳到程式碼修改；extract 則更擅長先檢查現有 design-system 結構、辨識哪些東西真的值得重用，並避免做出 repository 根本承接不了的 abstraction。

extract 對新手友善嗎？

友善，只要目標範圍有收斂。新手只要把 extract 技能指向某個 feature area，並先要求 proposal，就能有效使用。真正變難的情況，是你要求它重塑整體 UI 架構，卻沒有提供任何慣例或邊界。

extract 一定需要既有 design system 嗎？

不一定，但你需要先做出決策。如果目前沒有 design system，這個技能會明確指示 agent 先詢問，再決定是否建立新的系統。這對導入來說反而是好事，因為它避免了默默發明一套架構。

什麼情況不該用 extract？

以下情況不建議使用 extract：

• 你只需要一個一次性元件
• UI 還太早期，尚未值得做 abstraction
• 該模式只出現一次
• 你追求的是 pixel polish，而不是重用
• 團隊尚未對 shared UI 應該放哪裡達成共識

這些情況下，先用更簡單的 prompt，或先做 design decision，通常會更省時間。

extract 會找哪些類型的模式？

這個技能主要聚焦於：

• 重複元件
• 同一概念卻有不一致實作
• hard-coded 的 colors、spacing、typography 或 shadows
• 可重用的 layout 或 interaction patterns

因此它很適合做 token extraction 與 shared component 工作，而不只是 JSX 去重而已。

extract 如何適配不同前端技術棧？

核心邏輯和技術棧無關，因為它的本質是辨識重用機會與系統邊界。不過，輸出品質仍很依賴你是否清楚說明 stack 與慣例。如果你的 app 使用 Tailwind、CSS variables，或有一層 component library wrapper，請一開始就講清楚，這樣抽取方案才會貼合你的 codebase 實際運作方式。

如何改善 extract 技能的使用效果

一開始的 target 要比你直覺認為的更窄

最常見的錯誤就是範圍抓太大。更好的做法，是先對一個 feature、一個 route group，或一個 component family 執行 extract。這能讓 agent 有足夠重複內容可分析，同時不至於被迫過早設計全域架構。

明確告訴 extract design system 在哪裡

如果你知道 shared UI 的位置，請直接說明，例如：

• src/components/ui
• packages/design-system
• app/shared/components

這能減少猜測，讓建議更尊重現有的 import、命名與 ownership patterns。

不只要抽取候選，也要它說明抽取標準

一個很強的改進型 prompt 會是：

• “Use extract, but explain why each candidate should be shared now, later, or never.”

這能把重用判斷背後的門檻與理由攤開來看，幫助你避免把 design system 膨脹成充滿弱抽象的集合。

在請求中把 tokens 和 components 分開

很多使用者會把所有重用工作混在一起提。更好的輸出通常來自於把它拆成：

• token opportunities：colors、spacing、type、shadows
• component opportunities：buttons、cards、inputs、banners
• composition opportunities：layouts、form sections、重複組裝的結構

這會讓結果更容易實作，也更容易審查。

要求它評估 migration risk 和 blast radius

導入上的最大阻力之一，就是大家擔心大範圍回歸風險。要改善 extract usage，可要求它提供：

• 會受影響的檔案或區域
• 可能的 breaking changes
• 哪些是 easy wins、哪些抽取風險較高
• 建議的遷移順序

這樣第一輪輸出就會更接近維護者可直接審核的材料。

提供哪些情況應維持 local 的例子

一個很有幫助的 prompt 補充是：

• “Keep product-specific or one-off logic local unless reuse is clearly justified.”

這能對抗 AI 很典型的失敗模式：只要看起來相似就全部抽出去，即使語意其實不同，長期維護反而會更糟。

第一輪結果出來後要繼續迭代

拿到第一版 extract guide 輸出後，可以接著補問：

• “Narrow this to only token extraction.”
• “Rework the plan to fit our existing component naming.”
• “Only include patterns used 3+ times.”
• “Convert this proposal into a phased migration checklist.”

當你在看過初步發現後，進一步收緊抽取門檻，這個技能的輸出品質通常會明顯提升。

注意過度抽象化

一種常見失敗模式，是發明出高度可配置的元件，但其實用更簡單的 shared primitive 或 token 就夠了。如果你看到提案裡有太多 props 或 variants，請要求 agent 優先考慮：

• 更少的 shared components
• 更多 tokenization
• 更小的 composition units
• 在產品語意不同時改用 local wrappers

這通常會得到更健康的 design system。

在實作前，把 extract 當成決策輔助工具

對很多團隊來說，extract 技能最好的用法是先做診斷，再進入實作。先請它盤點機會與權衡，再開始寫程式。這在 legacy codebase 裡特別有價值，因為錯的 abstraction 往往會帶來比它省下的還更多的遷移成本。

用 repository 專屬語言來提升輸出品質

如果你的團隊會使用像是 “primitives”、“recipes”、“slots”、“tokens” 或 “foundations” 這類術語，請把這些詞放進 prompt。當 extract 技能能直接沿用維護者已熟悉的詞彙與結構時，它給出的建議會更容易合併，也更容易長期維持。