wp-block-themes

wp-block-themes 技能總覽

wp-block-themes 涵蓋哪些內容

wp-block-themes 技能適合處理 WordPress 區塊主題相關工作：theme.json、templates、template parts、patterns、style variations，以及常見的「為什麼我的樣式沒顯示？」除錯路徑。當你需要的是能感知檔案系統、而且貼近 WordPress 實作邏輯的工作流程，而不是一個泛用的區塊主題提示詞時，它最有用。

誰適合使用它

如果你正在實作或維護區塊主題、把傳統主題轉成區塊主題，或是在排查 Site Editor 的行為，建議使用 wp-block-themes 技能。它很適合設計落地工作，尤其是當你需要前台、編輯器與使用者自訂樣式之間都能有可預期的輸出時。

為什麼它不一樣

這個技能是以決策為導向：它會告訴你先檢查什麼、哪些檔案真正重要，以及 WordPress 實際上如何解析主題設定與使用者覆寫。這讓它比單純問模型「幫我處理一個區塊主題」更實用，因為它能減少對範圍、相容性，以及變更應該放在哪裡的猜測。

如何使用 wp-block-themes 技能

正確安裝並界定範圍

請用以下指令安裝：
npx skills add WordPress/agent-skills --skill wp-block-themes

在進行 wp-block-themes 安裝與設定時，先把任務範圍鎖定到目前啟用主題的根目錄，再開始修改。若你的 repo 裡有多個主題，請先確認精確的主題目錄與你要對應的 WordPress 版本，因為 theme.json 的功能與行為會隨 core 版本而不同。

提供正確的輸入內容

wp-block-themes 的使用模式，在你明確指定以下資訊時效果最好：

• 主題根目錄或 repo 根目錄
• 精確的作用範圍：theme.json、templates/、parts/、patterns/ 或 styles/
• 問題出現的位置：Site Editor、文章編輯器、前台，或三者皆有
• 這是新建、轉換，還是除錯

一個很好的提示詞會像這樣：更新目前啟用的區塊主題 theme.json，讓按鈕在編輯器與前台都套用新的品牌色，同時保留使用者覆寫不變。目標 WordPress 6.9。必要時請檢查 template parts。

先閱讀這些檔案

先從 SKILL.md 開始，接著檢查：

• references/theme-json.md
• references/templates-and-parts.md
• references/patterns.md
• references/style-variations.md
• references/debugging.md
• references/creating-new-block-theme.md

如果 repo 結構不清楚，也請一併查看 scripts/detect_block_themes.mjs。wp-block-themes 指南最強的地方，就是在你動手編輯前先走完它的偵測步驟。

按正確順序處理

實務上可依照以下流程：

1. 偵測主題根目錄
2. 確認問題發生的範圍
3. 查看對應的參考檔案
4. 修改應該負責該行為的最小檔案
5. 以使用者自訂與快取的編輯器狀態進行測試

這個順序很重要，因為很多看起來像「壞掉」的區塊主題問題，其實是樣式層級或已儲存的使用者設定出了狀況，不一定是主題檔案本身有錯。

wp-block-themes 技能 FAQ

wp-block-themes 只適合進階使用者嗎？

不是。只要你已經知道自己在編輯哪個主題，而且能清楚描述目標變更，它對初學者也很友善。這個技能會幫你處理 WordPress 特有的路由與判斷，但你仍需要提供主題脈絡與想要的結果。

什麼情況下不該用它？

不要把 wp-block-themes 用在一般 WordPress 外掛工作、區塊主題以外的 PHP template hierarchy 除錯，或是完全不碰主題檔案的視覺設計任務。若你甚至不確定問題是在主題、使用者自訂，還是 Site Editor，這也不是最合適的選擇。

它和一般提示詞有什麼不同？

一般提示詞可能會直接建議修改，卻不會先檢查主題檔案系統、相容範圍，或區塊主題檔案的位置。當你需要在 theme.json、templates、parts 與 styles 之間有紀律地進行 wp-block-themes usage 時，這個技能會更好用，尤其是設計落地這種檔案位置非常關鍵的情境。

什麼通常會卡住導入？

最常見的阻礙是主題範圍不清楚、沒有 WordPress 版本目標，以及混淆主題預設值和使用者選定樣式。如果你一開始答不出這些問題，這個技能仍然能幫上忙，但第一輪的精準度可能會比較有限。

如何改進 wp-block-themes 技能

提供更強的設計輸入

若想讓 wp-block-themes 在 Design Implementation 上有更好的結果，請提供精確的設計意圖與受影響的區塊或區域。例如，應該說「為所有 templates 設定預設標題間距與按鈕圓角」，而不是「讓主題看起來更乾淨」。前者可以直接執行，後者只會迫使模型自己補需求。

把預設值和覆寫分開

常見失敗模式，是以為 theme.json 的變更一定能蓋過使用者自訂。如果問題其實出在已儲存的 global styles 或已選用的 style variation，就要直接說明。想要改善結果時，請清楚標出你要的是：

• 主題預設值
• 編輯器控制項
• style variation
• 單次性的 template 變更

用最小失敗例子反覆迭代

如果第一次輸出已經接近正確，但還不完全對，下一輪就把需求縮小到一個檔案和一個症狀。例如：styles/blue.json 已被選取，但重新載入後沒有反映出來；請說明這是否屬於預期行為，以及應該測試什麼。這比要求全面重設計更能產生有效的除錯結果。

依照 repo 慣例做驗證

在編輯前先確認 repo 是否使用 patterns、style variations，或是最小化的 theme scaffold，wp-block-themes 的效果會更好。如果第一次的結果感覺太泛用，請重新提供 repo 檔案路徑、目前啟用的主題名稱，以及你希望套用的具體參考檔案。