Package a commerce app directory into a registry-ready ZIP file. This skill handles BOTH new apps AND version bumps of existing apps. Use this IMMEDIATELY when users mention "package", "ZIP", "build app", "ready to submit", "bump version", "new version", "update version", "release", "patch", "minor update", "major release", or after ANY changes to an app directory. Trigger proactively whenever you see a commerce-*-app-v* directory that needs packaging - don't wait for explicit requests.
Build a registry-ready Commerce App Package (CAP) ZIP from an app directory.
| Input | Example | Required |
|---|---|---|
| App name | avalara-tax | Yes |
| Display name | Avalara Tax | Yes |
| Domain | tax | Yes |
| Version | 0.2.8 | Yes |
| Description | Short description | Yes |
| Publisher name | Avalara | Yes |
| Publisher URL | https://developer.avalara.com/ | Yes |
Valid domains: tax, payment, shipping, gift-cards, ratings-and-reviews, loyalty, search, , , ,
address-verificationanalyticsapproaching-discountsfraudStructure: Apps must be at {domain}/{appName}/ where {appName} matches the "id" field. See references/folder-structure.md.
Check for existing catalog.json:
cat <domain>/<appName>/catalog.json
Decision tree:
"latest": {"version": "INIT"} and "versions": []: Ask user to replace or bumpVersion validation:
Ensure version matches throughout:
{
"id": "<appName>",
"name": "<displayName>",
"description": "<description>",
"domain": "<domain>",
"version": "<version>",
"publisher": {
"name": "<publisherName>",
"url": "<publisherUrl>",
"support": "<publisherUrl>"
},
"dependencies": {}
}
CRITICAL: Validate before packaging:
/validate-app
Checks architecture, structure, manifest, impex, icons, translations, and security. Address all failures before continuing.
cd <domain>/<appName>/
rm -f <appName>-v*.zip
cd <domain>/<appName>/
zip -r <appName>-v<version>.zip commerce-<appName>-app-v<version>/ \
-x "*.DS_Store" -x "__MACOSX/*" -x "*/.*" -x "Thumbs.db"
Verify structure:
unzip -l <appName>-v<version>.zip | head -20
Confirm:
commerce-<appName>-app-v<version>/shasum -a 256 <domain>/<appName>/<appName>-v<version>.zip
Update commerce-apps-manifest/manifest.json:
{
"id": "<appName>",
"name": "<displayName>",
"description": "<description>",
"iconName": "<appName>.png",
"domain": "<domain>",
"type": "app",
"provider": "thirdParty",
"version": "<version>",
"zip": "<appName>-v<version>.zip",
"sha256": "<computed_hash>"
}
Icon: Must match filename in ZIP's icons/ directory. CI extracts automatically.
Update commerce-apps-manifest/translations/en-US.json (minimum):
jq '. + {"<appName>": {"name": "<displayName>", "description": "<description>"}}' \
commerce-apps-manifest/translations/en-US.json > temp.json && \
mv temp.json commerce-apps-manifest/translations/en-US.json
Repeat for other locales or use English as fallback.
{
"latest": {"version": "INIT", "tag": "INIT"},
"versions": []
}
/validate-app
All checks must pass.
cd <domain>/<appName>/
rm -rf commerce-<appName>-app-v<version>/
Commit only:
<appName>-v<version>.zipcommerce-apps-manifest/manifest.jsoncommerce-apps-manifest/translations/*.jsoncatalog.json (new apps only)Don't commit: