woocommerce-plugin-development
Skill1 starsChanged 18 days agoMITView on GitHub
Build and change WooCommerce plugins with hooks, CRUD data stores, HPOS-safe order access, nonces, capabilities, and gettext. Use when writing or reviewing a plugin that reads or writes WooCommerce products, orders, customers, or checkout.
In this repository28 other files it gives its agents.
- b2b-pricingSkill
- catalog-import-and-migrationSkill
- checkout-ux-and-conversionSkill
- conversion-event-trackingSkill
- ecommerce-seo-structured-dataSkill
- fraud-and-risk-basicsSkill
- google-merchant-product-feedsSkill
- headless-nextjs-storefrontSkill
- inventory-and-multi-warehouseSkill
- iranian-payment-gatewaysSkill
- marketplace-search-and-rankingSkill
- mcp-store-toolingSkill
- multi-vendor-payoutsSkill
- order-and-webhook-reliabilitySkill
- payment-gateway-integrationSkill
- product-catalog-modelingSkill
- product-description-guardrailsSkill
- returns-and-refundsSkill
- rtl-and-persian-localizationSkill
- shopify-app-developmentSkill
- storefront-accessibilitySkill
- storefront-performanceSkill
- stripe-paymentsSkill
- subscription-billingSkill
- tax-and-shippingSkill
- vector-product-searchSkill
- woocommerce-rest-apiSkill
- wordpress-plugin-securitySkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Stop direct requests with defined( 'ABSPATH' ) || exit;.
- Very specific: line 18
Read and write products and orders through CRUD.
- Very specific: line 37
Do not call update_post_meta(), get_post_meta(), wp_insert_post(), or get_posts() for orders.
- Distinctive: line 78
If both checkouts are enabled, place one classic order and one block order.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
WooCommerce plugin development
Use this skill for a WordPress plugin that depends on WooCommerce. Use the REST API skill for an external HTTP client. Use the payment and webhook skills for capture and notification handling. Use the WordPress plugin security skill for the authorization details of any new endpoint.
Procedure
- Declare the dependency in the main plugin file. WordPress 6.5+ understands
Requires Plugins: woocommerce. SetWC tested up toas well. WooCommerce only surfaces High-Performance Order Storage (HPOS) compatibility in the plugins list when that header is present. - Stop direct requests with
defined( 'ABSPATH' ) || exit;. - Read and write products and orders through CRUD. Load with
wc_get_product()orwc_get_order(), change setters, then callsave()once. List orders withwc_get_orders(). Do not querywp_postsforshop_order. - From the main plugin file, on
before_woocommerce_init, declare feature compatibility. Pass__FILE__from that main file. Declarecustom_order_tablesonly when every order read and write uses CRUD orOrderUtil. Declarecart_checkout_blocksonly when checkout behavior also runs for the Checkout block. - Hook the specific action. Cover both checkout stacks when the code runs during checkout. Open the hook notes before choosing one.
- Authorize every write with a capability and a nonce. A nonce is not authentication.
- Send user-facing strings through gettext with the plugin text domain.
A skeleton header and the compatibility declaration are in assets/main-plugin-file.php. Copy it into a new plugin only after you delete the declaration you cannot yet keep.
Order and product writes
$order = wc_get_order( $order_id );
if ( ! $order ) {
return;
}
$order->update_meta_data( '_carrier_code', sanitize_text_field( $carrier ) );
$order->save();Do not call update_post_meta(), get_post_meta(), wp_insert_post(), or get_posts() for orders. Those use the posts tables. Under HPOS the order may be absent there, or the row may be a stale compatibility copy.
HPOS is the default for new installations from WooCommerce 8.2 onward. Older shops may still use posts storage. CRUD serves both. Compatibility mode can mirror orders into posts; code that reads those posts still fails when a merchant turns the mirror off.
Open the HPOS notes before adding an admin order screen, a custom order query, or SQL.
Checkout hooks
Classic shortcode checkout and the Checkout block do not share one hook.
- Classic checkout, before the first save:
woocommerce_checkout_create_orderreceives theWC_Orderand the posted data. - Classic checkout, after the order exists:
woocommerce_checkout_order_processed. - Checkout block and Store API:
woocommerce_store_api_checkout_update_order_from_requestandwoocommerce_store_api_checkout_order_processed.
A plugin that hooks only the classic actions does not run during block checkout.
Admin order screens
wc_get_page_screen_id( 'shop-order' ) returns shop_order on posts storage and the HPOS orders screen id otherwise. Use it for metaboxes. The callback may receive a WP_Post or a WC_Order. Normalize with wc_get_order() and ignore the original argument after that. Link to an order with $order->get_edit_order_url().
save_post_shop_order does not run for HPOS orders. Persist admin fields from woocommerce_process_shop_order_meta, then wc_get_order() and save().
Internationalization
- The text domain matches the plugin slug. Set the
Text Domainheader. - Print with
esc_html__(),esc_attr__(), andesc_html_e(). Usesprintfplaceholders. Do not concatenate translated fragments. - Language packs for plugins hosted on WordPress.org load from the slug. For any other distribution, call
load_plugin_textdomain()oninit. WordPress 6.7 reports a notice when translations load earlier. - RTL layout is a separate task. Use the Persian and RTL skill when the storefront needs it.
Gotchas
save()writes the object. Set the fields for this change, then save once.- Refunds are orders of type
shop_order_refund. Create them withwc_create_refund(). Flipping the parent status torefundeddoes not record a refund. - Stock reduction is tied to payment completion and status transitions. A second decrement double-counts. Core tracks this with
_order_stock_reducedinsidewc_maybe_reduce_stock_levels(). woocommerce_checkout_update_order_metastill runs. Examples that callupdate_post_meta()inside it are not HPOS-safe.- Declaring
custom_order_tablescompatibilitytrueis a promise. If any order path still uses post APIs, declarefalseuntil that path is gone. - SQL against
{$wpdb->prefix}wc_ordersskips caches and the posts fallback. Limit it to a measured report, and branch withOrderUtil::custom_orders_table_usage_is_enabled().
Verification
- With HPOS on and compatibility mode off, create and edit an order through the plugin. The change is visible in admin and in
wc_get_order(). - If both checkouts are enabled, place one classic order and one block order.
- A user without the required capability cannot perform the write. A missing or reused nonce is rejected.
- New strings are escaped where printed and are picked up by
wp i18n make-pot.
Evaluation
Worked examples and the checks they must satisfy are in evals/tasks.json.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

