[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DN022W9AB9Z2FKVKCVE8DB":3,"skill-same:01M7DN022W9AB9Z2FKVKCVE8DB":45},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":20,"frontMatter":21,"refName":22,"commitSha":23,"skillDirectory":24,"forksCount":25,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":28,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M7DN022W9AB9Z2FKVKCVE8DB","squad-version-check",null,"zuwasi\u002Fwazatator","zuwasi","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F190716959?v=4","01M7DMZ8MRBNDR8VVP3M1JDTDF","Daniel Liezrowice","01M7DMZ8NVFGJP9Z8BXF127YR0",2,"MIT","https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator\u002Fblob\u002Fmain\u002F.copilot\u002Fskills\u002Fsquad-version-check\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"# SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics\n\n**Confidence:** medium\n**Discovered by:** Data\n**Date:** 2026-05-26\n**Validated in:** Issue #1173 recon (bradygaster\u002Fsquad)\n\n---\n\n## What This Skill Covers\n\nReusable knowledge about how `@bradygaster\u002Fsquad-cli` stamps its version into `squad.agent.md`, how `squad upgrade` works, what it preserves vs. overwrites, and how to probe the npm registry for the latest version from a coordinator prompt.\n\n---\n\n## Package & Registry Facts\n\n- **Package name:** `@bradygaster\u002Fsquad-cli`\n- **Registry:** npm (public)\n- **CLI binary:** `squad` (registered via `package.json#bin.squad`)\n- **Node version requirement:** Node ≥22.5.0 (ESM-only codebase)\n\n---\n\n## Version Stamping Mechanism\n\n**Source file:** `dist\u002Fcli\u002Fcore\u002Fversion.js`\n\nThree functions:\n\n### `getPackageVersion()`\nWalks up from the compiled JS file to find `package.json`. Returns `pkg.version`. Works from both `dist\u002Fcli\u002Fcore\u002Fversion.js` and a bundled root `cli.js`. Returns `'0.0.0'` as fallback if not found.\n\n### `stampVersion(filePath, version)`\nMutates `squad.agent.md` in three places:\n1. HTML comment: `\u003C!-- version: {version} -->` (must be on the line immediately after frontmatter `---`)\n2. Identity line: `- **Version:** {version}`\n3. Greeting instruction: backtick-quoted `` `Squad v{version}` ``\n\n**Called by:** both `init` and `upgrade` — after copying the template to the destination.\n\n### `readInstalledVersion(filePath)`\nReads the stamped version back from `squad.agent.md`:\n1. First tries HTML comment format: `\u002F\u003C!-- version: ([0-9.]+(?:-[a-z]+(?:\\.\\d+)?)?) -->\u002F`\n2. Falls back to old frontmatter format: `\u002F^version:\\s*\"([^\"]+)\"\u002Fm`\n3. Returns `'0.0.0'` on any error\n\n---\n\n## `squad upgrade` Behavior\n\n**Source file:** `dist\u002Fcli\u002Fcore\u002Fupgrade.js`\n\n### What gets overwritten:\n- `squad.agent.md` — full overwrite from template, then `stampVersion()`\n- Files with `overwriteOnUpgrade: true` in `TEMPLATE_MANIFEST`: casting JSON files, template .md files, `copilot-instructions.md` (if @copilot enabled)\n- GitHub Actions workflows — from `templates\u002Fworkflows\u002F`; non-npm projects get type-aware stubs\n- Runs `runMigrations()` after file copy\n\n### What is PRESERVED:\n- `team.md`, `routing.md`, `decisions.md`, `ceremonies.md` (user-owned)\n- `agents\u002F*\u002Fhistory.md` (individual agent memory)\n- `.squad\u002Fconfig.json` — **never touched**; `stateBackend` survives intact\n- User-added files not in TEMPLATE_MANIFEST\n\n### Self-upgrade path (`selfUpgradeCli()`):\nDetects npm\u002Fpnpm\u002Fyarn via `npm_execpath` and `npm_config_user_agent`. Runs:\n- npm: `npm install -g @bradygaster\u002Fsquad-cli@latest`\n- pnpm: `pnpm add -g @bradygaster\u002Fsquad-cli@latest`\n- yarn: `yarn global add @bradygaster\u002Fsquad-cli@latest`\nUse `@insider` tag for insider builds.\n\n### `compareSemver(a, b)` utility (in upgrade.js):\nReturns -1\u002F0\u002F1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., `0.9.5-insider.1` \u003C `0.9.5`). Can be ported directly if needed in prompt logic.\n\n---\n\n## `.squad\u002Fconfig.json` — What It Holds\n\n```json\n{\n  \"version\": 1,\n  \"stateBackend\": \"worktree\"\n}\n```\n\nOther optional fields added by the coordinator at runtime:\n- `defaultModel` — global model override for all agent spawns\n- `agentModelOverrides.{agentName}` — per-agent model override\n\nThe file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences).\n\n---\n\n## Version-Check Probe (npm Registry)\n\nUse this one-liner from inside a coordinator prompt to fetch dist-tags:\n\n```\nnpm view @bradygaster\u002Fsquad-cli dist-tags --json\n```\n\n- Timeout: **5 seconds.** If no response within 5 seconds, abandon and show normal greeting.\n- On success: extract `dist-tags[channel]` (e.g., `dist-tags[\"insider\"]`).\n- On any error (network failure, registry unreachable, parse error): show normal greeting.\n\n---\n\n## Upstream OS-Specific Cache\n\nThe CLI (`self-update.ts`) writes `latest` version info to an OS-specific path with a 24h TTL.\n\n**One-liner to read the upstream cache:**\n```\nnode -e \"const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age\u003C86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}\"\n```\n\nOutput semantics:\n- Valid JSON `{\"latestVersion\":\"X.Y.Z\",\"checkedAt\":N}` → cache hit; use `latestVersion`\n- `STALE` → cache expired (older than 24h); treat as no data\n- `MISS` → cache missing or corrupt; treat as no data\n\n**OS-specific cache path:**\n- Windows: `%APPDATA%\\squad-cli\\update-check.json`\n- Linux: `~\u002F.config\u002Fsquad-cli\u002Fupdate-check.json`\n- macOS: `~\u002FLibrary\u002FApplication Support\u002Fsquad-cli\u002Fupdate-check.json`\n\n---\n\n## Repo-Local Cache Convention: `.squad\u002F.cache\u002Fversion-check.json`\n\nUsed by coordinator for `insider`\u002F`preview` channels (the upstream cache only stores `latest`).\n\n**Schema:**\n```json\n{\n  \"checkedAt\": \"2026-05-26T14:13:28.492Z\",\n  \"currentVersion\": \"0.9.6-insider.2\",\n  \"channel\": \"insider\",\n  \"channelVersion\": \"0.9.7-insider.1\"\n}\n```\n\n**TTL:** 24 hours from `checkedAt`.\n**Gitignore:** `.squad\u002F.cache\u002F` is listed in `.gitignore` — cache files are never committed.\n\n---\n\n## Key File Paths (installed CLI)\n\n| Purpose | Path |\n|---|---|\n| Version utilities | `dist\u002Fcli\u002Fcore\u002Fversion.js` |\n| Upgrade logic | `dist\u002Fcli\u002Fcore\u002Fupgrade.js` |\n| Init logic | `dist\u002Fcli\u002Fcore\u002Finit.js` |\n| Template manifest | `dist\u002Fcli\u002Fcore\u002Ftemplates.js` |\n| Copilot install helper | `dist\u002Fcli\u002Fcopilot-install.js` |\n| squad.agent.md template | `templates\u002Fsquad.agent.md.template` |\n| Session init reference | `templates\u002Fsession-init-reference.md` |\n| All templates | `templates\u002F` |\n",{},"main","862e4c1e1a261338b0e5991ba0795cfe7495aafa",".copilot\u002Fskills\u002Fsquad-version-check",1,"https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator","https:\u002F\u002Fgithub.com\u002Fzuwasi","https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fliezrowice\u002F","It is all started like that:\r\nhttps:\u002F\u002Fzuwasi.github.io\u002FPublic-html-pages\u002Fearly-dos-html\u002F","2026-10-05 02:10:56",{"source":7,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add zuwasi\u002Fwazatator --skill squad-version-check",{"tool":37,"command":38},"bunx","bunx skills add zuwasi\u002Fwazatator --skill squad-version-check",{"tool":40,"command":41},"pnpm","pnpm dlx skills add zuwasi\u002Fwazatator --skill squad-version-check","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator\u002Fblob\u002Fmain\u002F.copilot\u002Fskills\u002Fsquad-version-check\u002FSKILL.md",true,[],[46,53,60,67,74,80],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":18},"01M7DN23WD0BPHCQ7TN299NX9X","waza-runner","Run evaluations on Agent Skills to measure their effectiveness. \nUSE FOR: \"run skill evals\", \"evaluate my skill\", \"test skill quality\", \n\"check skill triggers\", \"skill compliance check\", \"measure skill performance\",\n\"run evals on [skill-name]\", \"grade skill execution\".\nDO NOT USE FOR: writing skills (use skill-authoring), improving frontmatter \n(use sensei), or general testing unrelated to skills.","https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator\u002Fblob\u002Fmain\u002Fwaza-runner\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":18},"01M7DN1WVDHG5TX61GFA2XSDMT","waza","**WORKFLOW SKILL** - Evaluate AI agent skills using structured benchmarks with YAML specs, fixture isolation, and pluggable validators. USE FOR: run waza, waza help, run eval, run benchmark, evaluate skill, test agent, generate eval suite, init eval, compare results, score agent, agent evaluation, skill testing, cross-model comparison. DO NOT USE FOR: improving skill frontmatter (use waza dev), creating new skills from scratch (use skill-creator), token counting or budget checks (use waza tokens). INVOKES: Copilot SDK executor, mock engine, code\u002Fregex validators. FOR SINGLE OPERATIONS: use waza run directly for a single benchmark.","https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator\u002Fblob\u002Fmain\u002Fskills\u002Fwaza\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":18},"01M7DN1QRAVT3B45MBAFKQ1R5T","waza-interactive","Interactive workflow partner for creating, testing, and improving AI agent skills with waza. USE FOR: run my evals, check my skill, compare models, create eval suite, debug failing tests, is my skill ready, ship readiness, interpret results, improve score. DO NOT USE FOR: general coding, non-skill work, writing skill content (use skill-authoring), improving frontmatter only (use sensei).","https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator\u002Fblob\u002Fmain\u002Fskills\u002Fwaza-interactive\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":18},"01M7DN1N3VF86B09G7PTCGXTMM","code-explainer","Explains code snippets in plain English, breaking down what the code does step by step. Perfect for learning, code reviews, or documentation.","https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator\u002Fblob\u002Fmain\u002Fskills\u002Fcode-explainer\u002FSKILL.md",[],[],{"skillNo":75,"name":69,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M7DN1EDND8Q8XNRCFRKQ6P08","**UTILITY SKILL** - Explain code snippets, functions, and algorithms in plain language.\nUSE FOR: explain code, what does this code do, break down this function,\nhelp me understand this, walk through this algorithm, clarify this logic,\nexplain this snippet, describe what happens here.\nDO NOT USE FOR: writing new code (use code generation), fixing bugs (use debugging),\nrefactoring (use refactoring skills), code review with action items.\nINVOKES: file reading tools to access code, language detection for tailored explanations.\nFOR SINGLE OPERATIONS: If the user just needs to see file contents, use file reading tools directly.","https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator\u002Fblob\u002Fmain\u002Fexamples\u002Fcode-explainer\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M7DN1BBSY9B0GYFNX8XQXSD7","profile-test-skill","**PROFILE TEST** - A skill for testing the profile command.\nUSE FOR: testing profile analysis, verifying structural metrics.\nDO NOT USE FOR: production use.","https:\u002F\u002Fgithub.com\u002Fzuwasi\u002Fwazatator\u002Fblob\u002Fmain\u002Fcmd\u002Fwaza\u002Ftokens\u002Ftestdata\u002Fprofile\u002FSKILL.md",[],[]]