wp-abilities-api

wp-abilities-api 技能概览

wp-abilities-api 是用来做什么的

wp-abilities-api 技能帮助你端到端处理 WordPress Abilities API：用 PHP 注册 ability 和 category，通过 REST 暴露出来，并在 @wordpress/abilities 中消费它们。它最适合你需要一套可靠的 wp-abilities-api 技能工作流，而不是靠猜 hook 顺序、REST 可见性或权限行为的时候。

最适合的使用场景

这个技能适合后端开发任务：ability 需要被客户端发现、出现在 /wp-json/wp-abilities/v1/* 中，或者需要在插件、主题、mu-plugin，甚至 WordPress core checkout 里被干净地注册。它尤其适合处理“ability 没显示出来”这类问题、接入新的服务端 ability，或者验证客户端是否真的能看到服务端已注册的内容。

最重要的点

wp-abilities-api 的最大价值在于减少生命周期层面的失误。仓库强调注册时机、源码扫描和 REST 暴露检查，这比泛泛的提示词写法更重要，因为这个 API 很容易接错，哪怕代码看起来没问题。

如何使用 wp-abilities-api 技能

安装并放到正确的上下文里

使用 npx skills add WordPress/agent-skills --skill wp-abilities-api 安装。然后把 agent 指向仓库根目录，并告诉它这项工作属于 core、插件、主题还是 mu-plugin。对于 wp-abilities-api install 的判断，还要提供目标 WordPress 版本，因为 WP 6.9+ 的支持会影响技能是可以依赖 core 行为，还是需要走插件/package 路径。

给技能提供正确输入

最有效的 wp-abilities-api usage 总是从一个具体任务开始，而不是笼统目标。好的输入要写清 ability ID、category ID、期望的 label、callback 形态，以及是否必须在 REST 中可见。比如：“在这个插件里添加一个 site/clear-cache ability，暴露到 REST，并确保客户端可以列出来。” 这比“配置 abilities”更好，因为它明确告诉技能应该产出什么、显示在哪里。

先读这些文件

先看 SKILL.md，然后检查 references/php-registration.md 和 references/rest-api.md。这两个文件包含最关键的决策信息：category 必须先于 ability 注册、所需 hooks，以及你应该验证的 REST 路由。如果你是在判断现有代码库是否适用 wp-abilities-api guide，先搜索 wp_register_ability(、wp_register_ability_category(、wp_abilities_api_init、wp_abilities_api_categories_init、wp-abilities/v1 和 @wordpress/abilities。

使用能避免“假成功”的工作流

一套实用的 wp-abilities-api 工作流是：先确认版本支持，再定位已有注册，然后先加 category 再加 ability，最后验证 REST 暴露和客户端可见性。如果你在意输出质量，可以要求 agent 写明改了哪些文件路径、每个注册用了哪个 hook，以及它是如何确认 ability 出现在 wp-abilities/v1/abilities 或 wp-abilities/v1/categories 中的。

wp-abilities-api 技能常见问题

wp-abilities-api 只适合后端开发吗？

不是，但它在后端开发场景下最强。wp-abilities-api for Backend Development 这个用例正是它最擅长的部分：PHP 注册、生命周期 hooks、REST 暴露，以及类似 capability 的检查。如果你只需要一次性的 UI 提示词或静态代码片段，通用提示词可能就够了。

这和自己写提示词有什么不同？

通用提示词可以描述目标，但 wp-abilities-api 提供的是一套面向 WordPress 特定约束的聚焦工作流：hook 时机、REST 可见性、版本兼容性，以及在新增之前先检查已有注册的需求。这能减少“代码里有了，但 REST 里没有”的反复试错。

新手需要懂 WordPress 内部机制吗？

有基础会更顺手，但只要你能定位仓库根目录，并知道插件或主题代码放在哪里，这个技能仍然可以用。新手最容易踩的坑，是跳过必需输入：WordPress 版本、项目类型，以及修改应该落在哪一层。没有这些信息，agent 可能会选错注册路径。

什么时候不该用这个技能？

如果任务和 WordPress abilities 无关，如果项目低于 WP 6.9 且你不能添加所需的 package/plugin 路径，或者你并不需要客户端可见的 ability 注册，就不要用 wp-abilities-api。在这些情况下，这个技能带来的流程开销大于收益。

如何改进 wp-abilities-api 技能

提供精确的注册目标

最好的结果来自一开始就把 ability ID、category 和期望暴露方式说清楚。不要只说“加一个管理员 ability”，而是说“把 acme/reindex-search 注册到 acme-tools 下，暴露到 REST，并让 JS 客户端可用”。这样 wp-abilities-api 技能就有足够结构，避免输出含糊或对不上。

补充会改变实现方式的约束

提到 WordPress 版本、这是 core 还是插件/主题、以及是否有 WP-CLI。这些信息会影响安装路径、hook 用法和验证步骤。如果省略这些内容，agent 可能写出看起来没问题、但在你的环境里会失败的代码。

要求验证，不只是要代码

最常见的失败模式是 hook 顺序不对、缺少 meta.show_in_rest，或者想当然地认为 ability 会自动出现在路由里却没有检查。要求 agent 对照 wp-abilities/v1/abilities 做验证，并解释为什么某个注册应该放在 wp_abilities_api_categories_init 或 wp_abilities_api_init 上。这样 wp-abilities-api guide 才会变成可核验的工作流。

基于仓库证据迭代

如果第一轮结果不完整，就把 agent 指到具体已有文件，让它对齐现有实现，而不是从头重写。比如：“沿用 includes/abilities.php 里的现有注册模式，保持 category 命名一致，只在需要时调整 REST 可见性标志。” 这是在不偏离代码库的前提下，提升 wp-abilities-api usage 的最快方式。