wp-plugin-development: hook timing, CPT queryability, gotchas/traps, secrets, i18n

[sboisvert]

Summary

Adds three new reference files and several procedure improvements to the wp-plugin-development skill.

New reference files

File	Covers
references/security-deep-cuts.md	Nonce internals (lifetime, generation, verification return values), password hashing, capability edge cases (super-admin, primitive vs meta caps), KSES defaults
references/gotchas-and-traps.md	Return-value traps that defeat "did it succeed?" checks: get_post_meta returning '', \$wpdb->insert() returning rows-affected not insert ID, update_post_meta() returning false on identical values, is_admin() checking URL not role, wp_redirect() not exiting; plus numeric limits, hook ordering, WP_Query vs get_posts()
references/i18n-gotchas.md	Text-domain-must-be-literal-string rule, why locale functions only return reliable values after init, escaping and translating in the same call

SKILL.md updates

• Hook-registration timing: Register add_action/add_filter at plugin load time — not from inside a method that itself runs on init. Calling add_action() from an init callback re-registers on every request and causes hooks to fire multiple times.
• CPT publicly_queryable matching: When requirements describe a "landing page" or "URL per resource", the CPT needs publicly_queryable => true (or an explicit alternative documented as a design decision). Mismatched queryability is a common source of "where's my page?" bugs.
• Server-side validation: Enforce min/max/required/format constraints in save handlers, not only in JS. Direct POST and API requests bypass client-side validation entirely.
• Secrets storage: API keys and credentials belong in environment variables or a host-provided secrets store, not in wp_options / post meta / transients.
• New section "Avoid common WordPress gotchas" routes to the new reference files.

Why this is useful

These cover failures that look correct in code review and break under realistic conditions:

• The add_action-from-an-init-callback bug is invisible until production traffic — at which point the same callback runs 5–50 times per request.
• update_post_meta() returning false for identical values is the most common "my code seems broken" misread when calls are wrapped in if ( ! update_post_meta(...) ).
• Client-side-only validation looks complete but is bypassed by every API consumer that isn't the editor UI.

Test plan

• Confirm all new reference files render correctly on GitHub
• Confirm SKILL.md frontmatter is upstream-compatible (no Principal-specific fields)
• (Optional) Add eval scenarios for: hook-registration timing detection, gotcha return-value checks

🤖 Generated with Claude Code