Skip to content

Commit 026411f

Browse files
jbisaSFjbisaSF
committed
Update generate CAP skills
1 parent 8be0939 commit 026411f

2 files changed

Lines changed: 88 additions & 18 deletions

File tree

  • .claude/skills/generate-commerce-app
  • .cursor/skills/generate-commerce-app

‎.claude/skills/generate-commerce-app/SKILL.md‎

Lines changed: 44 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,42 @@ Gather from the user (or infer from context):
2828
| Publisher name | `Avalara` | Yes |
2929
| Publisher URL | `https://developer.avalara.com/` | Yes |
3030

31-
## Step 2: Verify directory structure
31+
## Step 2: Check version and determine strategy
32+
33+
**CRITICAL:** Before proceeding, check if this is a new app or an update to an existing app.
34+
35+
1. **Check for existing catalog.json:**
36+
```bash
37+
cat <domain>/<isv-name>/catalog.json
38+
```
39+
40+
2. **Determine versioning strategy:**
41+
42+
- **IF catalog.json does NOT exist:**
43+
- This is a brand new app
44+
- Proceed with the version from commerce-app.json
45+
- Skip to Step 3
46+
47+
- **IF catalog.json shows `"latest": { "version": "INIT" }` AND `"versions": []`:**
48+
- Version hasn't been published yet
49+
- **ASK USER:** "The current version `<version>` hasn't been published. Do you want to:"
50+
1. Replace `<version>` with your changes (recommended if no one has it)
51+
2. Bump to a new version (e.g., `<next-version>`) for better tracking
52+
- Wait for user choice before proceeding
53+
54+
- **IF the version from commerce-app.json EXISTS in catalog.json's `versions` array:**
55+
- **FORCE VERSION BUMP** - no option to replace
56+
- **STOP and tell the user:** "Version `<version>` already exists in catalog.json and cannot be replaced. Please bump to a new version."
57+
- **ASK USER:** "What version should this release be? (e.g., `<suggested-next-version>`)"
58+
- Use `/update-app-version` skill instead for proper version bumping
59+
- Do NOT proceed until user provides a new version number
60+
61+
3. **Version validation rules:**
62+
- If version exists in `catalog.json` versions → MUST bump version (no exceptions)
63+
- Always confirm version with user before generating ZIP
64+
- Never silently change version without explicit user approval
65+
66+
## Step 3: Verify directory structure
3267

3368
The extracted app directory must be named `commerce-<appName>-app-v<version>/` and contain:
3469

@@ -71,7 +106,7 @@ commerce-<appName>-app-v<version>/
71106

72107
Validate that every file referenced by the code actually exists and vice versa.
73108

74-
## Step 3: Update commerce-app.json
109+
## Step 4: Update commerce-app.json
75110

76111
This file provides package-level identity. Update it to match the current version:
77112

@@ -91,7 +126,7 @@ This file provides package-level identity. Update it to match the current versio
91126
}
92127
```
93128

94-
## Step 4: Delete old ZIP versions
129+
## Step 5: Delete old ZIP versions
95130

96131
**CRITICAL:** Before generating the new ZIP, delete any existing ZIP files for this app to avoid clutter:
97132

@@ -105,7 +140,7 @@ This ensures:
105140
- No confusion about which ZIP is current
106141
- Clean git status
107142

108-
## Step 5: Generate the ZIP
143+
## Step 6: Generate the ZIP
109144

110145
Run from the **parent directory** of the app folder so the root entry is `commerce-<appName>-app-v<version>/`:
111146

@@ -122,7 +157,7 @@ Verify the ZIP:
122157
- No `.DS_Store`, `__MACOSX`, or hidden files
123158
- No duplicate directory trees
124159

125-
## Step 6: Compute SHA256 hash
160+
## Step 7: Compute SHA256 hash
126161

127162
Generate the hash for the ZIP:
128163

@@ -132,7 +167,7 @@ shasum -a 256 <domain>/<isv-name>/<appName>-v<version>.zip
132167

133168
Copy the hex digest (the long string before the filename).
134169

135-
## Step 7: Update root manifest
170+
## Step 8: Update root manifest
136171

137172
**CRITICAL:** Update the root manifest at `commerce-apps-manifest/manifest.json`:
138173

@@ -158,7 +193,7 @@ Valid domains: `tax`, `payment`, `shipping`, `gift-cards`, `ratings-and-reviews`
158193
**For new apps:** Add a new entry to the appropriate domain array.
159194
**For updates:** Update the existing entry's `version`, `zip`, and `sha256` fields.
160195

161-
## Step 8: Handle catalog.json
196+
## Step 9: Handle catalog.json
162197

163198
- **Existing app**: Do not modify `catalog.json` — CI updates it on merge.
164199
- **Brand new app**: Create `catalog.json` next to the ZIP:
@@ -173,7 +208,7 @@ Valid domains: `tax`, `payment`, `shipping`, `gift-cards`, `ratings-and-reviews`
173208
}
174209
```
175210

176-
## Step 9: Final validation checklist
211+
## Step 10: Final validation checklist
177212

178213
- [ ] ZIP name matches `<appName>-v<version>.zip`
179214
- [ ] ZIP contains a single root folder `commerce-<appName>-app-v<version>/`
@@ -183,7 +218,7 @@ Valid domains: `tax`, `payment`, `shipping`, `gift-cards`, `ratings-and-reviews`
183218
- [ ] `sha256` in root manifest matches the actual ZIP hash
184219
- [ ] `catalog.json` included only for brand new apps
185220

186-
## Step 10: Clean up extracted directory
221+
## Step 11: Clean up extracted directory
187222

188223
After generating the ZIP, delete the extracted directory (it should NOT be committed):
189224

‎.cursor/skills/generate-commerce-app/SKILL.md‎

Lines changed: 44 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,42 @@ Gather from the user (or infer from context):
2828
| Publisher name | `Avalara` | Yes |
2929
| Publisher URL | `https://developer.avalara.com/` | Yes |
3030

31-
## Step 2: Verify directory structure
31+
## Step 2: Check version and determine strategy
32+
33+
**CRITICAL:** Before proceeding, check if this is a new app or an update to an existing app.
34+
35+
1. **Check for existing catalog.json:**
36+
```bash
37+
cat <domain>/<isv-name>/catalog.json
38+
```
39+
40+
2. **Determine versioning strategy:**
41+
42+
- **IF catalog.json does NOT exist:**
43+
- This is a brand new app
44+
- Proceed with the version from commerce-app.json
45+
- Skip to Step 3
46+
47+
- **IF catalog.json shows `"latest": { "version": "INIT" }` AND `"versions": []`:**
48+
- Version hasn't been published yet
49+
- **ASK USER:** "The current version `<version>` hasn't been published. Do you want to:"
50+
1. Replace `<version>` with your changes (recommended if no one has it)
51+
2. Bump to a new version (e.g., `<next-version>`) for better tracking
52+
- Wait for user choice before proceeding
53+
54+
- **IF the version from commerce-app.json EXISTS in catalog.json's `versions` array:**
55+
- **FORCE VERSION BUMP** - no option to replace
56+
- **STOP and tell the user:** "Version `<version>` already exists in catalog.json and cannot be replaced. Please bump to a new version."
57+
- **ASK USER:** "What version should this release be? (e.g., `<suggested-next-version>`)"
58+
- Use `/update-app-version` skill instead for proper version bumping
59+
- Do NOT proceed until user provides a new version number
60+
61+
3. **Version validation rules:**
62+
- If version exists in `catalog.json` versions → MUST bump version (no exceptions)
63+
- Always confirm version with user before generating ZIP
64+
- Never silently change version without explicit user approval
65+
66+
## Step 3: Verify directory structure
3267

3368
The extracted app directory must be named `commerce-<appName>-app-v<version>/` and contain:
3469

@@ -71,7 +106,7 @@ commerce-<appName>-app-v<version>/
71106

72107
Validate that every file referenced by the code actually exists and vice versa.
73108

74-
## Step 3: Update commerce-app.json
109+
## Step 4: Update commerce-app.json
75110

76111
This file provides package-level identity. Update it to match the current version:
77112

@@ -91,7 +126,7 @@ This file provides package-level identity. Update it to match the current versio
91126
}
92127
```
93128

94-
## Step 4: Delete old ZIP versions
129+
## Step 5: Delete old ZIP versions
95130

96131
**CRITICAL:** Before generating the new ZIP, delete any existing ZIP files for this app to avoid clutter:
97132

@@ -105,7 +140,7 @@ This ensures:
105140
- No confusion about which ZIP is current
106141
- Clean git status
107142

108-
## Step 5: Generate the ZIP
143+
## Step 6: Generate the ZIP
109144

110145
Run from the **parent directory** of the app folder so the root entry is `commerce-<appName>-app-v<version>/`:
111146

@@ -122,7 +157,7 @@ Verify the ZIP:
122157
- No `.DS_Store`, `__MACOSX`, or hidden files
123158
- No duplicate directory trees
124159

125-
## Step 6: Compute SHA256 hash
160+
## Step 7: Compute SHA256 hash
126161

127162
Generate the hash for the ZIP:
128163

@@ -132,7 +167,7 @@ shasum -a 256 <domain>/<isv-name>/<appName>-v<version>.zip
132167

133168
Copy the hex digest (the long string before the filename).
134169

135-
## Step 7: Update root manifest
170+
## Step 8: Update root manifest
136171

137172
**CRITICAL:** Update the root manifest at `commerce-apps-manifest/manifest.json`:
138173

@@ -156,7 +191,7 @@ Find the entry for your app in the appropriate domain array (`tax`, `shipping`,
156191
**For new apps:** Add a new entry to the appropriate domain array.
157192
**For updates:** Update the existing entry's `version`, `zip`, and `sha256` fields.
158193

159-
## Step 8: Handle catalog.json
194+
## Step 9: Handle catalog.json
160195

161196
- **Existing app**: Do not modify `catalog.json` — CI updates it on merge.
162197
- **Brand new app**: Create `catalog.json` next to the ZIP:
@@ -171,7 +206,7 @@ Find the entry for your app in the appropriate domain array (`tax`, `shipping`,
171206
}
172207
```
173208

174-
## Step 9: Final validation checklist
209+
## Step 10: Final validation checklist
175210

176211
- [ ] ZIP name matches `<appName>-v<version>.zip`
177212
- [ ] ZIP contains a single root folder `commerce-<appName>-app-v<version>/`
@@ -181,7 +216,7 @@ Find the entry for your app in the appropriate domain array (`tax`, `shipping`,
181216
- [ ] `sha256` in root manifest matches the actual ZIP hash
182217
- [ ] `catalog.json` included only for brand new apps
183218

184-
## Step 10: Clean up extracted directory
219+
## Step 11: Clean up extracted directory
185220

186221
After generating the ZIP, delete the extracted directory (it should NOT be committed):
187222

0 commit comments

Comments
 (0)