{"id":"2de7ed7e-bee4-47cd-b3d0-3dbbff939061","shortId":"x98U64","kind":"skill","title":"theme-update","tagline":"Safely update a Weaverse Pilot theme to the latest version — detects current version, fetches release diffs, plans changes category-by-category, preserves customizations, verifies build.","description":"# Theme Update — Weaverse Pilot\n\nSafely upgrade a Weaverse Pilot theme from its current version to a newer release. This skill walks through detection, planning, execution, and verification — never overwriting user customizations without explicit approval.\n\n## Source\n\n- Theme repo: https://github.com/Weaverse/pilot\n- Releases: https://github.com/Weaverse/pilot/releases\n- Package name: `@weaverse/pilot`\n- Versioning: `YYYY.M.D` (e.g., `2026.4.7`). Older: semver (`v8.1.0`)\n\n## Quick Check\n\n```bash\nnode skills/theme-update/scripts/check_pilot_updates.mjs\nnode skills/theme-update/scripts/check_pilot_updates.mjs --target v2026.4.7\n```\n\n---\n\n## Procedure\n\nFollow these phases in order. Do NOT skip steps.\n\n### Phase 1 — Detection\n\n1. Read `package.json` → get `version` field\n2. If `name` is not `@weaverse/pilot`, ask the user to confirm this is a Pilot-based project\n3. Fetch releases:\n\n```bash\ncurl -s \"https://api.github.com/repos/Weaverse/pilot/releases?per_page=50\"\n```\n\n4. Identify all releases between current version and latest (or user-specified target)\n5. Present to user:\n   - Current version\n   - Target version (latest unless specified)\n   - Number of intermediate releases\n   - Summary of key changes (features, fixes, breaking changes)\n\n**If already on latest → stop here and tell the user.**\n\n### Phase 2 — Branch\n\n```bash\ngit checkout -b update/v{CURRENT}-to-v{TARGET}\ngit push -u origin update/v{CURRENT}-to-v{TARGET}\n```\n\nAlways work on a branch. Never update on main directly.\n\n### Phase 3 — Plan\n\nFor each release in the update range (oldest to newest):\n\n1. **Fetch the diff** between consecutive versions:\n\n```bash\n# Full comparison URL\nhttps://api.github.com/repos/Weaverse/pilot/compare/v{OLD}...v{NEW}\n\n# Raw diff\nhttps://github.com/Weaverse/pilot/compare/v{OLD}...v{NEW}.diff\n```\n\n2. **Download the target version's source** (for reference files):\n\n```bash\ncurl -sL \"https://api.github.com/repos/Weaverse/pilot/tarball/v{TARGET}\" | tar xz\n```\n\n3. **Categorize every changed file** into three buckets:\n\n#### Auto-merge (safe to apply without asking)\n- `package.json` version bump, dependencies\n- Lock files (`package-lock.json`, `bun.lockb`, `pnpm-lock.yaml`)\n- `tsconfig.json`, `vite.config.ts`, `tailwind.config.ts` — ONLY if user hasn't customized them\n- New files that don't exist in user's project (additive only)\n- `.github/`, `CHANGELOG.md`, `LICENSE`\n\n#### Needs review (show diff, get approval)\n- `app/components/` — UI components user may have customized\n- `app/routes/` — route files user may have modified\n- `app/lib/` — utility modules\n- `app/root.tsx`, `app/entry.client.tsx`, `app/entry.server.tsx`\n- `app/styles/` — CSS/Tailwind changes\n- Any file where the user has local changes (`git diff` shows modifications from Pilot base)\n\n#### Skip (mention but don't touch)\n- Files the user deleted (they removed the feature intentionally)\n- Files in directories the user reorganized\n- `.env`, `.env.example` — never overwrite environment files\n\n4. **Present the plan** in a clear table:\n\n```\n## Update Plan: v2026.3.23 → v2026.4.7\n\n### Auto-merge (3 files)\n✅ package.json — version + dependency bumps\n✅ bun.lockb — lock file update\n✅ app/lib/utils.ts — new helper function added\n\n### Needs Review (5 files)\n⚠️  app/components/Header.tsx — Pilot added shopify-account web component\n    Your version: custom mega menu logic\n    Pilot change: replaced AccountButton with <shopify-account>\n    → Recommend: keep your mega menu, add shopify-account separately\n\n⚠️  app/routes/_index.tsx — performance improvements\n    Your version: added custom hero section\n    Pilot change: caching + skeleton loading\n    → Recommend: apply caching, keep your hero\n\n### New Files (2 files)\n➕ app/components/ScrollReveal.tsx — new scroll animation component\n➕ app/lib/reviews.ts — extracted reviews API\n\n### Skipped (1 file)\n⏭️  app/components/CombinedListings.tsx — you deleted this file\n```\n\n**Wait for user confirmation before proceeding.** Ask:\n> \"Review the plan above. Approve to continue, or tell me which files to handle differently.\"\n\n### Phase 4 — Execute\n\nApply changes in order, one release at a time if multi-version jump:\n\n#### 4a. Auto-merge files\n\n```bash\n# Copy new file from Pilot source\ncp /tmp/pilot-reference/{FILE_PATH} {FILE_PATH}\n\n# Or apply targeted patch\ngit apply --3way <patch-file>\n```\n\nAfter each auto-merge, verify with `git diff --stat`.\n\n#### 4b. Needs-review files\n\nFor each file:\n\n1. Show a **three-way comparison**:\n   - Pilot at user's version (baseline)\n   - Pilot at target version (their changes)\n   - User's current file (local modifications)\n\n2. Identify what the user changed vs what Pilot changed:\n   - User-only changes → preserve\n   - Pilot-only changes → apply\n   - Overlapping changes → flag conflict\n\n3. For conflicts, present options:\n   - Accept Pilot's version (lose user customization)\n   - Keep user's version (skip Pilot improvement)\n   - Manual merge (show both, let user edit)\n   - Smart merge (try to combine both — only if non-overlapping regions)\n\n4. Wait for user decision on each conflict before proceeding.\n\n#### 4c. Commit per release\n\n```bash\ngit add -A\ngit commit -m \"chore: update Pilot v{OLD} → v{NEW}\n\n- [list key changes applied]\n- [list files with manual merge decisions]\n\"\n```\n\nIf doing multi-version jump, repeat for each intermediate release.\n\n### Phase 5 — Verify\n\nAfter all changes applied:\n\n```bash\n# 1. Install dependencies\nbun install  # or npm install / pnpm install based on lockfile\n\n# 2. TypeScript check\nbun run typecheck\n\n# 3. Build check\nbun run build\n```\n\n**If build fails:**\n1. List the errors\n2. Analyze root cause (dependency mismatch? breaking change missed?)\n3. Propose fixes\n4. Apply fixes with user approval\n5. Re-run build\n\n**If build succeeds:**\n1. Run `bun run dev` briefly to check no runtime errors\n2. Summarize all changes made\n3. List any **manual follow-up steps**:\n   - New features that need configuration\n   - Breaking changes requiring code updates in customized files\n   - Deprecated patterns to migrate later\n\n### Phase 6 — Finalize\n\n1. Present final summary:\n\n```\n## Update Complete: v2026.3.23 → v2026.4.7\n\n✅ 12 files auto-merged\n✅ 5 files reviewed and merged\n✅ 2 new files added\n✅ Build passes\n✅ TypeCheck passes\n\n### New features available\n- Shopify Account Web Component (<shopify-account>)\n- Vite chunk splitting for better caching\n- ScrollReveal component for animations\n\n### Manual follow-up (optional)\n- Configure shopify-account in your Header if you want native sign-in\n- Review ScrollReveal component for use in custom sections\n\n### Rollback\ngit checkout main\ngit branch -D update/v2026.3.23-to-v2026.4.7\n```\n\n2. Ask user: \"Ready to merge into main?\"\n\n```bash\n# If approved\ngit checkout main\ngit merge update/v{CURRENT}-to-v{TARGET}\ngit push origin main\n```\n\n---\n\n## Safety Rules\n\n1. **Always branch first** — never update on main directly\n2. **Never overwrite without asking** — every file that could have user changes needs review\n3. **Commit per release** — easy to bisect if something breaks\n4. **Build must pass** — don't declare success until `typecheck` + `build` both pass\n5. **Offer rollback** — always tell user how to undo the whole update\n6. **Respect user deletions** — if they removed a file, don't re-add it without asking\n\n## Common Pitfalls\n\n- **Version format**: package.json has no `v` prefix (`2026.4.7`), GitHub tags have `v` prefix (`v2026.4.7`). Always normalize.\n- **Lock files**: After updating `package.json`, MUST run the correct package manager (check which lockfile exists)\n- **Custom components**: User components not in original Pilot are always preserved — never delete or move them\n- **Route structure**: If user reorganized routes, don't force Pilot's structure — apply route logic changes to user's structure instead\n- **CSS conflicts**: Pilot may change Tailwind classes or base styles — these need careful merge to avoid breaking user styling","tags":["theme","update","shopify","hydrogen","skills","weaverse","agent-skills","agentic-commerce","shopify-hydrogen","shopify-hydrogen-skills","weaverse-hydrogen"],"capabilities":["skill","source-weaverse","skill-theme-update","topic-agent-skills","topic-agentic-commerce","topic-shopify-hydrogen","topic-shopify-hydrogen-skills","topic-weaverse-hydrogen"],"categories":["shopify-hydrogen-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Weaverse/shopify-hydrogen-skills/theme-update","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Weaverse/shopify-hydrogen-skills","source_repo":"https://github.com/Weaverse/shopify-hydrogen-skills","install_from":"skills.sh"}},"qualityScore":"0.466","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 33 github stars · SKILL.md body (7,916 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-01T12:57:21.015Z","embedding":null,"createdAt":"2026-04-18T22:21:48.014Z","updatedAt":"2026-05-01T12:57:21.015Z","lastSeenAt":"2026-05-01T12:57:21.015Z","tsv":"'-3':565 '/repos/weaverse/pilot/compare/v':245 '/repos/weaverse/pilot/releases?per_page=50':138 '/repos/weaverse/pilot/tarball/v':273 '/tmp/pilot-reference':554 '/weaverse/pilot':69 '/weaverse/pilot/compare/v':253 '/weaverse/pilot/releases':73 '1':104,106,232,495,585,729,757,787,832,938 '12':840 '2':112,187,258,483,610,742,761,798,850,910,947 '2026.4.7':80,1022 '3':130,220,277,413,634,748,770,803,961 '4':139,398,525,672,773,971 '4a':541 '4b':577 '4c':682 '5':153,430,722,779,845,984 '6':830,996 'accept':639 'account':437,459,862,883 'accountbutton':449 'ad':427,434,466,853 'add':456,688,1009 'addit':322 'alreadi':177 'alway':209,939,987,1029,1055 'analyz':762 'anim':488,874 'api':493 'api.github.com':137,244,272 'api.github.com/repos/weaverse/pilot/compare/v':243 'api.github.com/repos/weaverse/pilot/releases?per_page=50':136 'api.github.com/repos/weaverse/pilot/tarball/v':271 'app/components':333 'app/components/combinedlistings.tsx':497 'app/components/header.tsx':432 'app/components/scrollreveal.tsx':485 'app/entry.client.tsx':351 'app/entry.server.tsx':352 'app/lib':347 'app/lib/reviews.ts':490 'app/lib/utils.ts':423 'app/root.tsx':350 'app/routes':340 'app/routes/_index.tsx':461 'app/styles':353 'appli':290,476,527,560,564,629,703,727,774,1074 'approv':63,332,513,778,920 'ask':118,292,508,911,951,1012 'auto':286,411,543,570,843 'auto-merg':285,410,542,569,842 'avail':860 'avoid':1098 'b':192 'base':128,370,739,1091 'baselin':597 'bash':86,133,189,239,268,546,686,728,918 'better':869 'bisect':967 'branch':188,213,907,940 'break':174,767,816,970,1099 'briefli':792 'bucket':284 'build':29,749,753,755,783,785,854,972,981 'bump':295,418 'bun':732,745,751,789 'bun.lockb':300,419 'cach':472,477,870 'care':1095 'categor':278 'categori':23,25 'category-by-categori':22 'caus':764 'chang':21,171,175,280,355,363,447,471,528,603,615,619,623,628,631,702,726,768,801,817,958,1077,1087 'changelog.md':325 'check':85,744,750,794,1042 'checkout':191,904,922 'chore':693 'chunk':866 'class':1089 'clear':404 'code':819 'combin':664 'commit':683,691,962 'common':1013 'comparison':241,591 'complet':837 'compon':335,439,489,864,872,896,1047,1049 'configur':815,880 'confirm':122,505 'conflict':633,636,679,1084 'consecut':237 'continu':515 'copi':547 'correct':1039 'could':955 'cp':553 'css':1083 'css/tailwind':354 'curl':134,269 'current':15,42,144,157,194,204,606,927 'custom':27,60,310,339,442,467,645,822,900,1046 'd':908 'decis':676,709 'declar':977 'delet':380,499,999,1058 'depend':296,417,731,765 'deprec':824 'detect':14,52,105 'dev':791 'diff':19,235,250,257,330,365,575 'differ':523 'direct':218,946 'directori':388 'download':259 'e.g':79 'easi':965 'edit':659 'env':392 'env.example':393 'environ':396 'error':760,797 'everi':279,952 'execut':54,526 'exist':317,1045 'explicit':62 'extract':491 'fail':756 'featur':172,384,812,859 'fetch':17,131,233 'field':111 'file':267,281,298,313,342,357,377,386,397,414,421,431,482,484,496,501,520,545,549,555,557,581,584,607,705,823,841,846,852,953,1004,1032 'final':831,834 'first':941 'fix':173,772,775 'flag':632 'follow':94,808,877 'follow-up':807,876 'forc':1070 'format':1016 'full':240 'function':426 'get':109,331 'git':190,199,364,563,574,687,690,903,906,921,924,932 'github':324,1023 'github.com':68,72,252 'github.com/weaverse/pilot':67 'github.com/weaverse/pilot/compare/v':251 'github.com/weaverse/pilot/releases':71 'handl':522 'hasn':308 'header':886 'helper':425 'hero':468,480 'identifi':140,611 'improv':463,652 'instal':730,733,736,738 'instead':1082 'intent':385 'intermedi':166,719 'jump':540,715 'keep':452,478,646 'key':170,701 'later':828 'latest':12,147,161,179 'let':657 'licens':326 'list':700,704,758,804 'load':474 'local':362,608 'lock':297,420,1031 'lockfil':741,1044 'logic':445,1076 'lose':643 'm':692 'made':802 'main':217,905,917,923,935,945 'manag':1041 'manual':653,707,806,875 'may':337,344,1086 'mega':443,454 'mention':372 'menu':444,455 'merg':287,412,544,571,654,661,708,844,849,915,925,1096 'migrat':827 'mismatch':766 'miss':769 'modif':367,609 'modifi':346 'modul':349 'move':1060 'multi':538,713 'multi-vers':537,712 'must':973,1036 'name':75,114 'nativ':890 'need':327,428,579,814,959,1094 'needs-review':578 'never':57,214,394,942,948,1057 'new':248,256,312,424,481,486,548,699,811,851,858 'newer':46 'newest':231 'node':87,89 'non':669 'non-overlap':668 'normal':1030 'npm':735 'number':164 'offer':985 'old':246,254,697 'older':81 'oldest':229 'one':531 'option':638,879 'order':98,530 'origin':202,934,1052 'overlap':630,670 'overwrit':58,395,949 'packag':74,1040 'package-lock.json':299 'package.json':108,293,415,1017,1035 'pass':855,857,974,983 'patch':562 'path':556,558 'pattern':825 'per':684,963 'perform':462 'phase':96,103,186,219,524,721,829 'pilot':8,33,38,127,369,433,446,470,551,592,598,618,626,640,651,695,1053,1071,1085 'pilot-bas':126 'pilot-on':625 'pitfal':1014 'plan':20,53,221,401,407,511 'pnpm':737 'pnpm-lock.yaml':301 'prefix':1021,1027 'present':154,399,637,833 'preserv':26,624,1056 'procedur':93 'proceed':507,681 'project':129,321 'propos':771 'push':200,933 'quick':84 'rang':228 'raw':249 're':781,1008 're-add':1007 're-run':780 'read':107 'readi':913 'recommend':451,475 'refer':266 'region':671 'releas':18,47,70,132,142,167,224,532,685,720,964 'remov':382,1002 'reorgan':391,1066 'repeat':716 'replac':448 'repo':66 'requir':818 'respect':997 'review':328,429,492,509,580,847,894,960 'rollback':902,986 'root':763 'rout':341,1062,1067,1075 'rule':937 'run':746,752,782,788,790,1037 'runtim':796 'safe':4,34,288 'safeti':936 'scroll':487 'scrollrev':871,895 'section':469,901 'semver':82 'separ':460 'shopifi':436,458,861,882 'shopify-account':435,457,881 'show':329,366,586,655 'sign':892 'sign-in':891 'skeleton':473 'skill':49 'skill-theme-update' 'skills/theme-update/scripts/check_pilot_updates.mjs':88,90 'skip':101,371,494,650 'sl':270 'smart':660 'someth':969 'sourc':64,264,552 'source-weaverse' 'specifi':151,163 'split':867 'stat':576 'step':102,810 'stop':180 'structur':1063,1073,1081 'style':1092,1101 'succeed':786 'success':978 'summar':799 'summari':168,835 'tabl':405 'tag':1024 'tailwind':1088 'tailwind.config.ts':304 'tar':275 'target':91,152,159,198,208,261,274,561,600,931 'tell':183,517,988 'theme':2,9,30,39,65 'theme-upd':1 'three':283,589 'three-way':588 'time':535 'to-v':195,205,928 'topic-agent-skills' 'topic-agentic-commerce' 'topic-shopify-hydrogen' 'topic-shopify-hydrogen-skills' 'topic-weaverse-hydrogen' 'touch':376 'tri':662 'tsconfig.json':302 'typecheck':747,856,980 'typescript':743 'u':201 'ui':334 'undo':992 'unless':162 'updat':3,5,31,215,227,406,422,694,820,836,943,995,1034 'update/v':193,203,926 'update/v2026.3.23-to-v2026.4.7':909 'upgrad':35 'url':242 'use':898 'user':59,120,150,156,185,307,319,336,343,360,379,390,504,594,604,614,621,644,647,658,675,777,912,957,989,998,1048,1065,1079,1100 'user-on':620 'user-specifi':149 'util':348 'v':197,207,247,255,696,698,930,1020,1026 'v2026.3.23':408,838 'v2026.4.7':92,409,839,1028 'v8.1.0':83 'verif':56 'verifi':28,572,723 'version':13,16,43,77,110,145,158,160,238,262,294,416,441,465,539,596,601,642,649,714,1015 'vite':865 'vite.config.ts':303 'vs':616 'wait':502,673 'walk':50 'want':889 'way':566,590 'weavers':7,32,37 'weaverse/pilot':76,117 'web':438,863 'whole':994 'without':61,291,950,1011 'work':210 'xz':276 'yyyy.m.d':78","prices":[{"id":"7d309546-b407-4b07-ad49-b2971f613386","listingId":"2de7ed7e-bee4-47cd-b3d0-3dbbff939061","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Weaverse","category":"shopify-hydrogen-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:21:48.014Z"}],"sources":[{"listingId":"2de7ed7e-bee4-47cd-b3d0-3dbbff939061","source":"github","sourceId":"Weaverse/shopify-hydrogen-skills/theme-update","sourceUrl":"https://github.com/Weaverse/shopify-hydrogen-skills/tree/main/skills/theme-update","isPrimary":false,"firstSeenAt":"2026-04-18T22:21:48.014Z","lastSeenAt":"2026-05-01T12:57:21.015Z"}],"details":{"listingId":"2de7ed7e-bee4-47cd-b3d0-3dbbff939061","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Weaverse","slug":"theme-update","github":{"repo":"Weaverse/shopify-hydrogen-skills","stars":33,"topics":["agent-skills","agentic-commerce","shopify-hydrogen","shopify-hydrogen-skills","weaverse-hydrogen"],"license":null,"html_url":"https://github.com/Weaverse/shopify-hydrogen-skills","pushed_at":"2026-04-24T10:12:43Z","description":"Dedicated agent skills for building, upgrading, and maintaining Shopify Hydrogen storefronts — works with Claude, Cursor, Copilot, and more.","skill_md_sha":"274de5171d5da200423a6f72f43ac162e4ad9a9f","skill_md_path":"skills/theme-update/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Weaverse/shopify-hydrogen-skills/tree/main/skills/theme-update"},"layout":"multi","source":"github","category":"shopify-hydrogen-skills","frontmatter":{"name":"theme-update","description":"Safely update a Weaverse Pilot theme to the latest version — detects current version, fetches release diffs, plans changes category-by-category, preserves customizations, verifies build."},"skills_sh_url":"https://skills.sh/Weaverse/shopify-hydrogen-skills/theme-update"},"updatedAt":"2026-05-01T12:57:21.015Z"}}