WP Plugin Zip: WordPress zips that install the first time
A skill for Claude Code and Claude Desktop. Claude packages your plugin or theme with a script that checks what WordPress checks, refuses to write a broken zip and shows you the name and version before you upload it. If you already have a zip that fails, it tells you why.
- Works in
- Claude Code and Claude Desktop (Code tab and chats)
- For
- WordPress plugins and themes
- Requirements
- Python 3. PHP optional, to check syntax with php -l
- Privacy
- No network: it only reads your files and writes the zip
- Licence
- MIT, free
- Version
- 1.0.0
Why a zip that looks fine still fails
- Windows PowerShell’s
Compress-Archivecan write names with\. On a Linux server WordPress creates a flat file instead of the folder and says “Plugin file does not exist”. - A BOM before
<?phpbreaks activation with “headers already sent”. - The main file sits one folder too deep, or its header is past the first 8 KB, which is all WordPress reads.
- GitHub’s “Download ZIP” creates a
my-plugin-mainfolder, and updates no longer match the installed plugin. - A marketplace download holds a zip inside another zip: “No valid plugins were found”.
How to install it
In Claude Code, as a plugin
Type these two commands in Claude Code:
/plugin marketplace add agenciaRSE/wp-plugin-zip
/plugin install wp-plugin-zip@wp-plugin-zipIn Claude Code, by hand
Copy the skills/wp-plugin-zip folder from the repository into ~/.claude/skills/.
In Claude Desktop
Download wp-plugin-zip.zip from the latest release on GitHub.
Upload it in Settings → Capabilities → Skills.
Use it
Ask Claude to “package the plugin”, “make the release zip” or “why does this zip say Plugin file does not exist?”.
Or run the script without Claude
You need Python 3. build creates the zip and check inspects one you already have:
python wp_zip.py build my-plugin --lint
python wp_zip.py check my-plugin.zipWhat it does
- Builds the right zip: one folder named after the slug,
/separators and explicit folder entries. - Checks it before writing:
Plugin Name:header (orstyle.csswithTheme Name:) in the first 8 KB, no BOM and no UTF-16. With--lint, it runsphp -lon every PHP file. - Leaves out the junk:
.git,node_modules,.DS_Store,Thumbs.db,desktop.ini, other zips, source maps and logs. - LF line endings even on Windows, so two packages of the same code come out identical.
- Checks any zip, yours, a client’s or a marketplace download, and explains each problem with its fix.
- Shows the name, version and author of what you are about to upload, so you never ship an old build.
Privacy and security
wp_zip.pyuses the Python standard library only: no network, nothing installed.- It reads the plugin folder and writes the zip where you say. It does not change your files: LF conversion happens only inside the zip.
- It is open source: you can read the script before you run it.
Built and maintained by AGENCIA RSE, a WordPress and custom software studio in A Coruña, Spain. We use it for every release of our own plugins. See all our Claude skills
Frequently asked questions
Why does WordPress say “Plugin file does not exist”?
Usually because the zip was made with PowerShell’s Compress-Archive, which can write names with “\”. On the server, WordPress creates a flat file instead of the plugin folder. The other common cause is a main file one folder too deep.
What does “No valid plugins were found” mean?
WordPress cannot find a PHP file with a “Plugin Name:” header directly inside the plugin folder. It happens a lot with marketplace downloads, which ship the plugin as a zip inside another zip with the documentation.
Why does activation fail with “headers already sent”?
Usually a BOM: invisible bytes some editors save before “<?php”. The skill detects it and will not write the zip until the file is saved as UTF-8 without BOM.
Does it work for themes?
Yes. If there is no plugin, it looks for a style.css with a “Theme Name:” header in the top folder.
Do I need PHP installed?
No. Only Python 3. If you have PHP, the --lint option also checks the syntax of every file.
Is it free?
Yes. It is open source under the MIT licence.
Need a custom Claude skill?
We build Claude skills to order around your team’s processes, templates and scripts, for Claude Code, Claude Desktop and claude.ai.
Your first consultation is free. We look at what you tell us and reply within 48 business hours.