automattic/agent-skills

Overview

This skill helps build, extend, and debug WordPress REST API endpoints and routes. It covers registering routes, controller classes, schema/argument validation, permission checks, response shaping, and exposing custom post types and taxonomies via show_in_rest. Use it to make endpoints robust, secure, and discoverable.

How this skill works

I inspect the repository for rest_api_init usage, register_rest_route calls, WP_REST_Controller subclasses, and show_in_rest flags to locate existing REST logic. I recommend patterns: exposing CPTs via show_in_rest, creating custom routes on rest_api_init, using controller classes for non-trivial endpoints, and defining args schemas with validate/sanitize callbacks. I also verify authentication, permissions, response shaping (register_rest_field/register_meta), and discovery/pagination behavior.

When to use it

• Adding or updating REST routes and controller logic
• Debugging 401/403/404 errors, missing nonces, or permission issues
• Adding custom fields or meta to REST responses
• Exposing custom post types or taxonomies via show_in_rest
• Implementing schema and argument validation for endpoint inputs

Best practices

• Use a unique namespace like vendor/v1; avoid colliding with wp/*
• Always provide a permission_callback; use capability checks for auth
• Define args with type/default/required and validate/sanitize callbacks or JSON Schema
• Return responses with rest_ensure_response() and errors as WP_Error with status
• Prefer controller classes for complex endpoints and register_meta/show_in_rest for meta

Example use cases

• Expose a custom post type to wp/v2 by setting show_in_rest and a rest_base
• Create a search endpoint with a WP_REST_Controller subclass and paginated responses
• Add a computed field to post responses using register_rest_field and a callback
• Debug a 403 from missing X-WP-Nonce in admin AJAX by checking cookie auth flow
• Validate complex JSON input using rest_validate_value_from_schema and schema defs