wp-block-development

wp-block-development 技能概覽

wp-block-development 的用途

wp-block-development 是一個實用技能，專門用來開發與修正 WordPress Gutenberg 區塊，特別適合問題出在 block.json、區塊註冊、已儲存的標記，或建置工具鏈的情境。wp-block-development 技能最適合需要安全地交付一個區塊的人，而不只是理解 API 表面。

最適合的使用情境

當你正在建立新區塊、更新既有區塊、診斷無效區塊，或把區塊往動態渲染方向調整時，就該使用這份 wp-block-development 指南。它也很適合涉及 viewScript、viewScriptModule、supports、wrapper 輸出，或前台／編輯器一致性的 Frontend Development 工作。

它的差異在哪裡

這個技能是以決策為導向：它能幫你選對區塊模式、在變更落地前找出破壞性修改，並避開 WordPress 常見陷阱，例如脆弱的屬性來源或缺少 deprecation 路徑。wp-block-development 技能的核心價值，在於降低註冊、序列化與相容性上的猜測成本。

如何使用 wp-block-development 技能

正確安裝並界定範圍

使用 npx skills add WordPress/agent-skills --skill wp-block-development 安裝 wp-block-development 技能。接著在下指令前先界定任務範圍：指定 repo 根目錄、區塊 namespace、若已知則提供區塊路徑，以及 WordPress 版本範圍。這些脈絡很重要，因為 wp-block-development 的行為會隨 apiVersion、modules 與 server rendering 支援而改變。

先從正確的檔案開始

先讀 SKILL.md，再依你的任務查看最相關的參考檔案：references/block-json.md、references/attributes-and-serialization.md、references/creating-new-blocks.md、references/dynamic-rendering.md、references/deprecations.md 與 references/debugging.md。如果你需要快速找出區塊，請用 scripts/list_blocks.mjs 來定位 block.json 根目錄，不要靠猜。

提供一個可執行的提示詞

有效的 wp-block-development 使用提示，會清楚說出目標、目前的失敗點與限制條件。例如：“Update my-plugin/blocks/cta so the button icon persists after save, keep existing posts valid, and support WordPress 6.9+.” 這樣比 “fix my block” 好，因為它能讓技能判斷要改標記、加入 deprecated，還是調整註冊方式。

採用符合區塊類型的工作流程

靜態區塊要聚焦在屬性來源、序列化標記與 save()。動態區塊要聚焦在 render.php、render_callback 與 wrapper attributes。容器區塊在改 template 規則前，先檢查 InnerBlocks 結構。這種 wp-block-development 安裝與使用模式，最適合先讀區塊根目錄，再用小範圍變更驗證路徑，最後才做大規模重構。

wp-block-development 技能 FAQ

wp-block-development 只適合做 Gutenberg 區塊建立嗎？

不是。wp-block-development 技能也很適合除錯與維護：無效內容、缺少編輯器樣式、註冊失敗、deprecations，以及前台輸出漂移。如果你的工作碰到區塊 metadata 或序列化，這個技能就有關。

如果我已經懂 WordPress，還需要這個技能嗎？

如果你已經熟悉 WordPress，但想在區塊實作上少犯錯，那還是需要。一般提示詞常常忽略區塊開發裡那些隱性的相容性工作，而 wp-block-development 會把你導向真正影響已儲存內容與編輯器行為的檔案與決策。

什麼情況下不該用 wp-block-development？

不要把它用在一般 PHP 外掛架構、佈景主題樣式，或不相關的 JavaScript 應用工作上。它最有用的場景，是問題核心在區塊註冊、區塊標記、動態渲染，或 WordPress 編輯器行為時。

wp-block-development 對初學者友善嗎？

如果任務範圍夠明確，那是友善的。這個技能會把初學者導向真正重要的檔案，並清楚區分靜態、動態與巢狀區塊模式。若你無法辨識區塊根目錄，或不知道區塊是儲存標記還是由伺服器渲染，這個技能就沒那麼有幫助。

如何改進 wp-block-development 技能

先把區塊資訊講清楚

wp-block-development 要得到好結果，輸入內容最好包含區塊名稱、所在資料夾、它是靜態還是動態，以及你必須支援的 WordPress 版本。如果你能貼上目前的 block.json、edit/save 結構，或出錯的標記，技能就能基於相容性做判斷，而不是靠猜。

描述故障模式，不只描述功能

直接告訴模型到底壞在哪裡：“attributes reset after update,” “editor shows invalid block,” “frontend CSS missing in iframe,” 或 “new markup must not break old posts.” 這些細節會決定 wp-block-development 應該建議 migration、註冊修正、wrapper 調整，還是建置變更。

保護既有內容

最重要的改進習慣，是保住舊文章。如果已儲存的 HTML 會變動，就要要求 deprecated 路徑與 migration 計畫。如果屬性來源來自脆弱的選擇器，請提供目前 HTML 與預期輸出，讓 wp-block-development 指南能建議更安全的來源。

用窄範圍測試迭代

拿到第一版答案後，一次只測一個區塊、一篇文章、單一個 WordPress 版本。如果結果還是不對，就回饋精確的 console warning、invalid-content 訊息，或渲染後的 HTML diff。這會讓下一輪 wp-block-development 的建議更精準，也通常能避免不必要的重構。