wp-block-development

wp-block-development 技能概览

wp-block-development 的作用

wp-block-development 是一项实用技能，适合构建和修复 WordPress Gutenberg blocks，尤其是问题出在 block.json、block registration、已保存标记，或 build tooling 的时候。wp-block-development 技能最适合需要把 block 安全交付出去的人，而不只是想理解 API 表面的人。

最适合的使用场景

当你在创建新 block、更新现有 block、排查 invalid block，或把 block 逐步改成 dynamic rendering 时，可以使用这份 wp-block-development 指南。它也适用于涉及 viewScript、viewScriptModule、supports、wrapper output，或 frontend/editor parity 的 Frontend Development 工作。

它有什么不同

这项技能以决策为导向：它会帮你选择合适的 block pattern，在问题落地前识别 breaking changes，并避开 WordPress 里常见的坑，比如脆弱的 attribute source 或缺少 deprecation path。wp-block-development 技能的核心价值，是减少在 registration、serialization 和 compatibility 上的猜测。

如何使用 wp-block-development 技能

正确安装并限定作用范围

使用 npx skills add WordPress/agent-skills --skill wp-block-development 安装 wp-block-development 技能。然后在提问前先限定任务范围：写明 repo root、block namespace、如果已知则写出 block path，以及需要支持的 WordPress version range。这个上下文很重要，因为 wp-block-development 的行为会随着 apiVersion、modules 和 server rendering support 的变化而变化。

先从正确的文件读起

先读 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。如果你需要快速定位 block，可以用 scripts/list_blocks.mjs 找到 block.json root，而不是靠猜。

提供可执行的提示词

高质量的 wp-block-development 提示词会同时说明目标、当前故障和约束。例如：“更新 my-plugin/blocks/cta，让按钮图标在保存后仍然保留，保持现有文章有效，并支持 WordPress 6.9+。”这比“帮我修一下 block”更好，因为它能让技能判断是要改 markup、添加 deprecated，还是调整 registration。

采用与 block 类型匹配的工作流

对于 static blocks，重点看 attribute sources、serialized markup 和 save()。对于 dynamic blocks，重点看 render.php、render_callback 和 wrapper attributes。对于 container blocks，在改 template rules 之前先检查 InnerBlocks 结构。这个 wp-block-development 安装模式在你先读 block root、再测试一条小改动路径时最有效，而不是一上来就做大范围重构。

wp-block-development 技能常见问题

wp-block-development 只适合创建 Gutenberg block 吗？

不是。wp-block-development 技能同样适合排障和维护：invalid content、editor styles 缺失、registration 失败、deprecations，以及 frontend 输出漂移。如果你的工作碰到 block metadata 或 serialization，这项技能就相关。

如果我已经懂 WordPress，还需要这个技能吗？

如果你已经懂 WordPress，但希望在 block implementation 上少踩坑，那还是需要。普通提示词常常会忽略 block development 里那些隐性的兼容性工作，而 wp-block-development 会把你引向那些真正影响已保存内容和 editor behavior 的文件与决策。

什么时候不该用 wp-block-development？

如果是通用 PHP plugin architecture、theme styling，或无关的 JavaScript app work，就不要用它。它最适合的问题，是围绕 block registration、block markup、dynamic rendering，或 WordPress editor behavior 展开的。

wp-block-development 适合初学者吗？

适合，前提是任务边界清楚。这个技能会把初学者带到真正重要的文件，并把 static、dynamic 和 nested block patterns 分开讲清楚。若你无法确认 block root，或者不知道这个 block 是保存 markup 还是由 server 渲染，它就没那么有帮助。

如何改进 wp-block-development 技能

先把 block 事实交代清楚

想要得到最好的 wp-block-development 结果，输入里最好包含 block name、所在文件夹、它是 static 还是 dynamic，以及必须支持的 WordPress version。如果你能贴出当前的 block.json、edit/save 结构，或者失败的 markup，技能就能基于兼容性做判断，而不是靠猜。

说明故障模式，而不只是功能需求

告诉模型到底哪里坏了：“attributes 在更新后被重置”“editor 显示 invalid block”“frontend CSS 在 iframe 里缺失”“新 markup 不能破坏旧文章”。这些信息会决定 wp-block-development 应该建议 migration、registration 修复、wrapper 调整，还是 build 变更。

保护现有内容

最重要的改进习惯，是保住旧文章。如果 saved HTML 会变，应该要求提供 deprecated 路径和 migration 方案。如果 attribute 来源依赖脆弱的 selector，最好提供当前 HTML 和期望输出，这样 wp-block-development 指南才能建议更稳妥的来源。

用窄范围测试循环迭代

第一次回答后，每次只测试一个 block、一个 post 和一个 WordPress version。如果结果还是不对，就把确切的 console warning、invalid-content 消息，或 rendered HTML diff 反馈回去。这样下一轮 wp-block-development 迭代会准确得多，也通常能避免不必要的重构。