Packaging a Claude skill as a ZIP that installs cleanly
A skill ZIP should unzip to exactly one folder with SKILL.md at its top. How to build one that way, keep junk files out, and validate it before it ships.
Most failed skill installs come down to the ZIP: an extra folder level, missing files, or macOS metadata. Build it the same way every time and check it before it leaves.
The shape
glass-instrument-ui.zip
glass-instrument-ui/
SKILL.md
README.md
LICENSE
references/tokens.css
references/components.mdBuild it from a staging copy
cp -R skills/my-skill stage/my-skill
cp skills/_shared/LICENSE stage/my-skill/
(cd stage && zip -X -q -r ../dist/my-skill.zip my-skill)
unzip -l dist/my-skill.zip-X drops extended attributes, so no ._ files ship. Copying shared files in at pack time keeps one licence and one companion guide across every skill.
Refuse to pack a broken skill
Our pack step checks frontmatter, names, referenced files and banned characters, and fails the build on any problem, listed in skill folder structure. Then test the ZIP itself on a clean machine: a Docker harness.
Questions
What should a skill ZIP contain?
One top-level folder named after the skill, with SKILL.md directly inside it, plus references, scripts, a README and a licence as needed.
Why do Mac ZIPs sometimes contain strange extra files?
macOS can add __MACOSX folders and ._ metadata files. Zip from the command line with the option that drops extended attributes, and check the listing.
Should the ZIP include the README?
Yes. It is the first thing a person opens: what the skill does, requirements, how to install and what to try first.