acf-skill

A Claude Code skill for operating Advanced Custom Fields (ACF) Pro on a user's own live WordPress site:

• Register field groups / fields / options pages / ACF Blocks in code
• Read & write field values, including repeater / flexible content / clone traversal
• Query posts by ACF meta
• A mandatory verification step that introspects the live site's installed ACF version, Pro status and available field types, then adapts
• A safety protocol for destructive operations — every write op supports dry_run for preview-before-execute

The ACF logic is written once as PHP and executed through one of two interchangeable transports:

• WP-CLI mode (default, no extra tooling) — runs the ACF PHP API via wp eval-file. Novamira is not a dependency in this mode.
• Novamira mode (fallback / by preference) — runs the same PHP through the Novamira MCP server, which gives agents PHP execution and filesystem access to WordPress. Setup & docs: https://github.com/use-novamira/novamira.

There is one canonical copy of the skill at skills/acf/. Both distribution channels below point at that same directory — the implementation is never forked per channel.

The API in the reference files was verified against ACF Pro source 6.8.1. The skill always re-checks the live site at runtime and adapts to whatever version is actually installed.

Repository layout

acf-skill/
├── .claude-plugin/
│   ├── plugin.json          # Claude plugin manifest
│   └── marketplace.json     # Claude marketplace manifest (this repo as a marketplace)
├── bin/cli.mjs              # npx entry point (install / path / run / selftest)
├── skills/
│   └── acf/                 # ← THE canonical skill (single source of truth)
│       ├── SKILL.md
│       ├── references/      # verified API docs (progressive disclosure)
│       └── scripts/         # acf-exec.mjs runner + snippets/*.php
├── package.json
└── README.md

Channel 1 — npx (no global install)

Run an ACF operation directly, without installing anything:

npx acf-skill run -- --detect
npx acf-skill run -- --mode wp --snippet verify-env --path /var/www/site
npx acf-skill run -- --mode wp --snippet get-value --args '{"post_id":42,"selector":"subtitle"}'

Install the skill into a Claude skills directory:

# into ./.claude/skills/acf (project scope, default)
npx acf-skill install

# into ~/.claude/skills/acf (user scope)
npx acf-skill install --user

# print where the bundled skill lives
npx acf-skill path

npx acf-skill selftest validates the bundled package.

Channel 2 — Claude plugin marketplace

This repository is itself a marketplace (.claude-plugin/marketplace.json) hosting one plugin (.claude-plugin/plugin.json); the skill is auto-discovered from skills/.

# add this repo as a marketplace (local path, git URL, or github owner/repo all work)
claude plugin marketplace add ./acf-skill
# or: claude plugin marketplace add mekko-digital/acf-skill

# install the plugin
claude plugin install acf-skill@acf-skill-marketplace

Once installed the skill is available in Claude Code (namespaced as acf-skill:acf) and activates automatically from its description when you ask about ACF.

Using the skill

Inside Claude Code, just describe the ACF task ("add a repeater row to post 42", "register an options page", "find products where featured is true"). The skill:

1. Detects/asks the execution mode.
2. Verifies the live ACF environment first and adapts.
3. For destructive ops, runs a dry_run preview, shows the diff, asks for confirmation, then executes.
4. Runs the matching PHP snippet through the chosen transport and returns structured JSON.

See skills/acf/SKILL.md and skills/acf/scripts/README.md for details.

Security

• The runner spawns WP-CLI without a shell on POSIX (shell: false) and shell-quotes every argument on Windows where wp.bat/wp.cmd shims require cmd.exe. The --wp and --path flags are not shell-injection surfaces.
• User-supplied JSON (--args) is never string-interpolated into PHP. WP-CLI mode passes it via the ACF_ARGS env var; Novamira mode base64-inlines it. The runner validates the JSON before render.
• Every snippet that mutates state supports dry_run and is gated by the safety protocol in SKILL.md §Step 4. The --php <file> ad-hoc mode runs arbitrary PHP and is treated as destructive by default.
• WP-CLI calls have a default 60 s timeout (--timeout <seconds> to override).
• The Novamira mode writes the rendered PHP to a tmp file and reports the path; it does not echo the rendered PHP inline, because the file embeds the base64-encoded args (which may contain sensitive field values). The agent is responsible for deleting the file after the hand-off.

Requirements

• Node.js 18+ (for the runner / npx CLI)
• One transport: WP-CLI with access to the WordPress install, or the Novamira MCP server configured against it
• ACF (Pro features require ACF Pro — the verify step reports this)

Testing

npm test runs the bundled selftest (manifests valid, snippets present, runner renders PHP without executing it). A full end-to-end smoke test against a real WordPress + ACF Pro install is a future stretch goal (e.g. a docker-compose harness running verify-env and asserting ok:true); contributions welcome.

Credits

Built by the Mekko Digital team — a small studio that ships fast Webflow & Fullstack MVP solutions. If this skill saves your team hours of "wait, what's the actual key?" debugging, star the repo and tell us in Discussions. We'll keep it up to date with ACF releases.

Check out our other free tools at Mekko Tools.

Tayyab Ul Islam

Hamza Zafar

License

MIT — see LICENSE.