{"id":"a4e04b35-70ce-4cda-baa5-a28c497bc47b","shortId":"LgEfJV","kind":"skill","title":"speckit-updater","tagline":"SpecKit Safe Update","description":"# SpecKit Safe Update\n\nThis skill provides safe update capabilities for GitHub SpecKit installations, preserving customizations while applying template updates.\n\n**Installation**: Available via plugin (`/plugin marketplace add NotMyself/claude-plugins` then `/plugin install speckit-updater`) or manual Git clone. See README.md for details.\n\n## When to Use\n- You need to update or install SpecKit templates while preserving project customizations.\n- You want a safe approval flow around update, rollback, or version-specific SpecKit operations.\n- The task is to operate the SpecKit updater conversationally instead of running raw commands blindly.\n\n## What to do when this skill is invoked\n\nWhen the user invokes `/speckit-updater`, you should:\n\n1. **Run the update orchestrator script** without any flags (conversational mode):\n   ```powershell\n   pwsh -NoProfile -Command \"& 'C:\\Users\\bobby\\.claude\\skills\\speckit-updater\\scripts\\update-wrapper.ps1'\"\n   ```\n\n2. **Parse the output** for markers:\n   - **`[PROMPT_FOR_APPROVAL]`** - Update scenario (existing SpecKit installation)\n   - **`[PROMPT_FOR_INSTALL]`** - Fresh installation scenario (no .specify/ directory)\n\n3. **For Updates** (`[PROMPT_FOR_APPROVAL]` marker found):\n   - **Present the Markdown summary** showing:\n     - Current version vs. available version\n     - Files to update/add/remove\n     - Conflicts detected (if any)\n     - Files preserved (customized)\n     - Backup location\n     - Custom commands\n   - **Ask the user for approval** to proceed with the update\n   - **If approved**, re-run with `-Proceed` flag\n   - **If declined**, inform the user the update was cancelled\n\n4. **For Fresh Installations** (`[PROMPT_FOR_INSTALL]` marker found):\n   - **Present a natural installation offer** to the user, such as:\n     - \"SpecKit is not currently installed in this project. Would you like me to install it?\"\n     - \"I can install the latest SpecKit templates for you. This will create the .specify/ directory structure and download the templates from GitHub.\"\n   - **Do NOT mention the `-Proceed` flag** to the user (this is an implementation detail)\n   - **If user approves** (says \"yes\", \"proceed\", \"install it\", etc.), re-run with `-Proceed` flag\n   - **If user declines**, inform them the installation was cancelled\n\n5. **Execute approved action** by re-running with `-Proceed` flag:\n   ```powershell\n   pwsh -NoProfile -Command \"& 'C:\\Users\\bobby\\.claude\\skills\\speckit-updater\\scripts\\update-wrapper.ps1' -Proceed\"\n   ```\n\n**Special cases:**\n- If user requests `-CheckOnly`: run with that flag and show the report\n- If user requests `-Rollback`: run with that flag and confirm restoration\n- If user requests specific `-Version`: include that parameter\n\n## Commands\n\n### /speckit-updater\n\nUpdates SpecKit templates, commands, and scripts while preserving customizations.\n\n**Usage:**\n- `/speckit-updater` - Interactive update/install with conversational approval workflow (recommended for Claude Code)\n- `/speckit-updater -Proceed` - Proceed with update/install after approval (used by Claude after user confirms)\n- `/speckit-updater -CheckOnly` - Check for updates without applying\n- `/speckit-updater -Version v0.0.72` - Update to specific version\n- `/speckit-updater -Force` - Force overwrite SpecKit files (preserves custom commands)\n- `/speckit-updater -Rollback` - Restore from previous backup\n- `/speckit-updater -Auto` - DEPRECATED: Use conversational workflow instead (shows warning, maps to -Proceed)\n\n**Fresh Installation (No .specify/ directory):**\n- First invocation shows installation offer with `[PROMPT_FOR_INSTALL]` marker\n- Claude Code presents natural question to user (e.g., \"Would you like me to install SpecKit?\")\n- User approves via conversational response (e.g., \"yes\", \"proceed\", \"install it\")\n- Claude re-invokes with `-Proceed` flag automatically (implementation detail hidden from user)\n- Script creates `.specify/` structure, downloads templates, creates manifest\n- Exit code 0 throughout (awaiting approval is not an error)\n- Consistent with update flow: both use conversational approval workflow\n\n**Process:**\n1. Validates prerequisites (Git installed, clean Git state, write permissions)\n2. Loads or creates manifest (.specify/manifest.json)\n3. Fetches target version from GitHub Releases API\n4. Compares file hashes to identify customizations\n5. Creates timestamped backup\n6. Applies selective updates preserving customized files\n7. Opens VSCode merge editor for conflicts (Flow A: one at a time)\n8. Automatically invokes /speckit.constitution for constitution updates\n9. Updates manifest with new version\n10. Manages backup retention (keeps last 5)\n\n**When you invoke this command, I will:**\n1. Execute the update-orchestrator.ps1 script\n2. Parse output for markers (`[PROMPT_FOR_APPROVAL]` for updates, `[PROMPT_FOR_INSTALL]` for fresh installations)\n3. **For updates**: Present Markdown summary of proposed changes\n4. **For installations**: Ask naturally if you want to install SpecKit (without mentioning `-Proceed` flag)\n5. Wait for your approval via chat conversation\n6. After approval: automatically re-invoke with `-Proceed` flag to execute\n7. Guide you through conflict resolution one file at a time (updates only)\n8. Open VSCode diff/merge tools as needed (updates only)\n9. Report results with detailed summary\n\n**Conversational Workflow:** The skill uses a two-step approval process:\n- **Step 1**: Outputs summary → script exits → waits for approval\n- **Step 2**: After approval, Claude re-invokes with `-Proceed` → applies updates\n\n**Requirements:**\n- Git installed and in PATH\n- Internet connection for fetching updates from GitHub\n- Write permissions to .specify/ and .claude/ directories\n- Clean or staged Git working directory\n\n**The script is located at:** `{skill_path}/scripts/update-wrapper.ps1` (entry point) and `{skill_path}/scripts/update-orchestrator.ps1` (main logic)\n\n**Entry point command:**\n```powershell\npwsh -NoProfile -Command \"& '{skill_path}/scripts/update-wrapper.ps1' [parameters]\"\n```\n\n**Note:** Both PowerShell-style (`-CheckOnly`) and Linux-style (`--check-only`) flags are supported via the wrapper script.\n\n## Features\n\n- **Customization Preservation**: Automatically detects and preserves user customizations using normalized file hashing\n- **Intelligent Conflict Resolution**: Guides through conflicts one-at-a-time with 4 options: merge editor, keep mine, use new, skip\n- **Version Tracking**: Maintains `.specify/manifest.json` with file hashes, version info, and backup history\n- **Automatic Backups**: Creates timestamped backups in `.specify/backups/` with automatic retention management\n- **Fail-Fast with Rollback**: Automatically rolls back on any error, restoring pre-update state\n- **Dry-Run Mode**: `--check-only` shows exactly what would change without applying updates\n- **Constitution Integration**: Notifies when constitution template has updates (run `/speckit.constitution`)\n- **Custom Command Safety**: User-created commands never overwritten, even with `--force`\n\n## Architecture\n\n### Modules\n- **HashUtils**: Normalized hashing (handles line endings, trailing whitespace, BOM)\n- **VSCodeIntegration**: Context detection, Quick Pick, diff/merge editor integration\n- **GitHubApiClient**: GitHub Releases API interaction (unauthenticated, 60 req/hour)\n- **ManifestManager**: Manifest CRUD operations with caching\n- **BackupManager**: Backup creation, restoration, and retention management\n- **ConflictDetector**: File state analysis and conflict detection\n\n### Workflow\n1. Prerequisites validation (critical checks must pass, warnings allow continuation)\n2. Manifest loading/creation (safe default: assume all files customized if no manifest)\n3. GitHub API query for target version\n4. File state analysis (6 actions: add/remove/merge/preserve/update/skip)\n5. User confirmation with change preview\n6. Backup creation (timestamped, excludes backups directory)\n7. Selective file updates (fail-fast with automatic rollback)\n8. Conflict resolution (Flow A: one-at-a-time, VSCode merge editor)\n9. Manifest update (version, file hashes, customization flags)\n10. Backup cleanup (keep 5 most recent, requires confirmation)\n11. Detailed summary display\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | General error |\n| 2 | Prerequisites not met |\n| 3 | Network/API error |\n| 4 | Git error |\n| 5 | User cancelled |\n| 6 | Rollback required (automatic) |\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.","tags":["speckit","updater","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows"],"capabilities":["skill","source-sickn33","skill-speckit-updater","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/speckit-updater","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34515 github stars · SKILL.md body (8,756 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-04-22T12:51:49.025Z","embedding":null,"createdAt":"2026-04-18T21:45:17.271Z","updatedAt":"2026-04-22T12:51:49.025Z","lastSeenAt":"2026-04-22T12:51:49.025Z","tsv":"'/plugin':30,35 '/scripts/update-orchestrator.ps1':781 '/scripts/update-wrapper.ps1':775,793 '/speckit-updater':105,375,386,397,410,417,424,433,439 '/speckit.constitution':590,912 '0':514,1070 '1':108,532,614,722,973,1072 '10':600,1053 '11':1062 '2':136,542,622,731,983,1075 '3':159,548,638,995,1079 '4':218,556,647,840,1002,1082 '5':312,563,606,662,1009,1057,1085 '6':567,670,1006,1015,1088 '60':950 '7':574,682,1022 '8':587,695,1032 '9':594,704,1045 'action':315,1007 'add':32 'add/remove/merge/preserve/update/skip':1008 'allow':981 'analysi':968,1005 'api':555,947,997 'appli':23,416,568,740,901 'approv':67,144,164,195,202,290,314,391,403,482,517,529,629,666,672,719,729,733 'architectur':925 'around':69 'ask':191,650,1125 'assum':988 'auto':440 'automat':498,588,673,818,861,869,877,1030,1091 'avail':27,175 'await':516 'back':879 'backup':187,438,566,602,859,862,865,959,1016,1020,1054 'backupmanag':958 'blind':92 'bobbi':125,329 'bom':935 'boundari':1133 'c':123,327 'cach':957 'cancel':217,311,1087 'capabl':15 'case':342 'chang':646,899,1013 'chat':668 'check':412,806,893,977 'check-on':805,892 'checkon':346,411,800 'clarif':1127 'claud':126,330,395,406,466,491,734,760 'clean':537,762 'cleanup':1055 'clear':1100 'clone':43 'code':396,467,513,1067,1068 'command':91,122,190,326,374,379,432,611,786,790,914,919 'compar':557 'confirm':364,409,1011,1061 'conflict':180,580,686,829,833,970,1033 'conflictdetector':965 'connect':749 'consist':522 'constitut':592,903,907 'context':937 'continu':982 'convers':86,117,390,443,484,528,669,710 'creat':263,505,510,545,564,863,918 'creation':960,1017 'criteria':1136 'critic':976 'crud':954 'current':172,240 'custom':21,62,186,189,384,431,562,572,816,823,913,991,1051 'declin':210,305 'default':987 'deprec':441 'describ':1104 'detail':47,287,500,708,1063 'detect':181,819,938,971 'diff/merge':698,941 'directori':158,266,455,761,767,1021 'display':1065 'download':269,508 'dri':889 'dry-run':888 'e.g':473,486 'editor':578,843,942,1044 'end':932 'entri':776,784 'environ':1116 'environment-specif':1115 'error':521,882,1074,1081,1084 'etc':296 'even':922 'exact':896 'exclud':1019 'execut':313,615,681 'exist':147 'exit':512,726,1066 'expert':1121 'fail':873,1027 'fail-fast':872,1026 'fast':874,1028 'featur':815 'fetch':549,751 'file':177,184,429,558,573,689,826,854,966,990,1003,1024,1049 'first':456 'flag':116,208,279,302,322,350,362,497,661,679,808,1052 'flow':68,525,581,1035 'forc':425,426,924 'found':166,226 'fresh':153,220,451,636 'general':1073 'git':42,535,538,743,765,1083 'github':17,273,553,754,945,996 'githubapicli':944 'guid':683,831 'handl':930 'hash':559,827,855,929,1050 'hashutil':927 'hidden':501 'histori':860 'identifi':561 'implement':286,499 'includ':371 'info':857 'inform':211,306 'input':1130 'instal':19,26,36,56,149,152,154,221,224,230,241,250,254,294,309,452,459,464,479,489,536,634,637,649,656,744 'instead':87,445 'integr':904,943 'intellig':828 'interact':387,948 'internet':748 'invoc':457 'invok':100,104,494,589,609,676,737 'keep':604,844,1056 'last':605 'latest':256 'like':247,476 'limit':1092 'line':931 'linux':803 'linux-styl':802 'load':543 'loading/creation':985 'locat':188,771 'logic':783 'main':782 'maintain':851 'manag':601,871,964 'manifest':511,546,596,953,984,994,1046 'manifestmanag':952 'manual':41 'map':448 'markdown':169,642 'marker':141,165,225,465,626 'marketplac':31 'match':1101 'mean':1069 'mention':276,659 'merg':577,842,1043 'met':1078 'mine':845 'miss':1138 'mode':118,891 'modul':926 'must':978 'natur':229,469,651 'need':52,701 'network/api':1080 'never':920 'new':598,847 'noprofil':121,325,789 'normal':825,928 'note':795 'notifi':905 'notmyself/claude-plugins':33 'offer':231,460 'one':583,688,835,1038 'one-at-a-tim':834,1037 'open':575,696 'oper':77,82,955 'option':841 'orchestr':112,619 'output':139,624,723,1110 'overwrit':427 'overwritten':921 'paramet':373,794 'pars':137,623 'pass':979 'path':747,774,780,792 'permiss':541,756,1131 'pick':940 'plugin':29 'point':777,785 'powershel':119,323,787,798 'powershell-styl':797 'pre':885 'pre-upd':884 'prerequisit':534,974,1076 'present':167,227,468,641 'preserv':20,60,185,383,430,571,817,821 'preview':1014 'previous':437 'proceed':197,207,278,293,301,321,340,398,399,450,488,496,660,678,739 'process':531,720 'project':61,244 'prompt':142,150,162,222,462,627,632 'propos':645 'provid':12 'ps1':135,339,620 'pwsh':120,324,788 'queri':998 'question':470 'quick':939 'raw':90 're':204,298,318,493,675,736 're-invok':492,674,735 're-run':203,297,317 'readme.md':45 'recent':1059 'recommend':393 'releas':554,946 'report':354,705 'req/hour':951 'request':345,357,368 'requir':742,1060,1090,1129 'resolut':687,830,1034 'respons':485 'restor':365,435,883,961 'result':706 'retent':603,870,963 'review':1122 'roll':878 'rollback':71,358,434,876,1031,1089 'run':89,109,205,299,319,347,359,890,911 'safe':5,8,13,66,986 'safeti':915,1132 'say':291 'scenario':146,155 'scope':1103 'script':113,131,335,381,504,621,725,769,814 'see':44 'select':569,1023 'show':171,352,446,458,895 'skill':11,98,127,331,713,773,779,791,1095 'skill-speckit-updater' 'skip':848 'source-sickn33' 'special':341 'specif':75,369,422,1117 'specifi':157,265,454,506,758 'specify/backups':867 'specify/manifest.json':547,852 'speckit':2,4,7,18,38,57,76,84,129,148,237,257,333,377,428,480,657 'speckit-updat':1,37,128,332 'stage':764 'state':539,887,967,1004 'step':718,721,730 'stop':1123 'structur':267,507 'style':799,804 'substitut':1113 'success':1071,1135 'summari':170,643,709,724,1064 'support':810 'target':550,1000 'task':79,1099 'templat':24,58,258,271,378,509,908 'test':1119 'throughout':515 'time':586,692,838,1041 'timestamp':565,864,1018 'tool':699 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'track':850 'trail':933 'treat':1108 'two':717 'two-step':716 'unauthent':949 'updat':3,6,9,14,25,39,54,70,85,111,130,133,145,161,200,215,334,337,376,414,420,524,570,593,595,618,631,640,693,702,741,752,886,902,910,1025,1047 'update-orchestr':617 'update-wrapp':132,336 'update/add/remove':179 'update/install':388,401 'usag':385 'use':50,404,442,527,714,824,846,1093 'user':103,124,193,213,234,282,289,304,328,344,356,367,408,472,481,503,822,917,1010,1086 'user-cr':916 'v0.0.72':419 'valid':533,975,1118 'version':74,173,176,370,418,423,551,599,849,856,1001,1048 'version-specif':73 'via':28,483,667,811 'vs':174 'vscode':576,697,1042 'vscodeintegr':936 'wait':663,727 'want':64,654 'warn':447,980 'whitespac':934 'without':114,415,658,900 'work':766 'workflow':392,444,530,711,972 'would':245,474,898 'wrapper':134,338,813 'write':540,755 'yes':292,487","prices":[{"id":"145714bc-fecb-442b-b30e-fae1977e2459","listingId":"a4e04b35-70ce-4cda-baa5-a28c497bc47b","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:45:17.271Z"}],"sources":[{"listingId":"a4e04b35-70ce-4cda-baa5-a28c497bc47b","source":"github","sourceId":"sickn33/antigravity-awesome-skills/speckit-updater","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/speckit-updater","isPrimary":false,"firstSeenAt":"2026-04-18T21:45:17.271Z","lastSeenAt":"2026-04-22T12:51:49.025Z"}],"details":{"listingId":"a4e04b35-70ce-4cda-baa5-a28c497bc47b","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"speckit-updater","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34515,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-22T06:40:00Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"1a5511bb63b398a265bf1e9647d7c3166d5279c7","skill_md_path":"skills/speckit-updater/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/speckit-updater"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"speckit-updater","description":"SpecKit Safe Update"},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/speckit-updater"},"updatedAt":"2026-04-22T12:51:49.025Z"}}