Setting the skill. One moment.
Skills
Skill 8 of 17
Core conventions and patterns used in the Squad codebase
2 minutes · 334 words · 12 sections
Install
npx skills add microsoft/waza --skill squad-conventionsnpx skills add microsoft/wazaThe first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.
These conventions apply to all work on the Squad CLI tool (create-squad). Squad is a zero-dependency Node.js package that adds AI agent teams to any project. Understanding these patterns is essential before modifying any Squad source code.
Squad has zero runtime dependencies. Everything uses Node.js built-ins (fs, path, os, child_process). Do not add packages to dependencies in package.json. This is a hard constraint, not a preference.
Tests use node:test and node:assert/strict — no test frameworks. Run with npm test. Test files live in test/. The test command is node --test test/.
All user-facing errors use the fatal(msg) function which prints a red ✗ prefix and exits with code 1. Never throw unhandled exceptions or print raw stack traces. The global uncaughtException handler calls fatal() as a safety net.
Colors are defined as constants at the top of index.js: GREEN, RED, DIM, BOLD, RESET. Use these constants — do not inline ANSI escape codes.
.squad/ — Team state (user-owned, never overwritten by upgrades).squad/templates/ — Template files copied from templates/ (Squad-owned, overwritten on upgrade).github/agents/squad.agent.md — Coordinator prompt (Squad-owned, overwritten on upgrade)templates/ — Source templates shipped with the npm package.squad/skills/ — Team skills in SKILL.md format (user-owned).squad/decisions/inbox/ — Drop-box for parallel decision writesAlways use path.join() for file paths — never hardcode / or \ separators. Squad must work on Windows, macOS, and Linux. All tests must pass on all platforms.
The init flow uses a skip-if-exists pattern: if a file or directory already exists, skip it and report “already exists.” Never overwrite user state during init. The upgrade flow overwrites only Squad-owned files.
copyRecursive(src, target) handles both files and directories. It creates parent directories with { recursive: true } and uses fs.copyFileSync for files.
// Error handling
function fatal(msg) {
console.error(`${RED}✗${RESET} ${msg}`);
process.exit(1);
}
// File path construction (Windows-safe)
const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md');
// Skip-if-exists pattern
if (!fs.existsSync(ceremoniesDest)) {
fs.copyFileSync(ceremoniesSrc, ceremoniesDest);
console.log(`${GREEN}✓${RESET} .squad/ceremonies.md`);
} else {
console.log(`${DIM}ceremonies.md already exists — skipping${RESET}`);
}/ or \ directly. Always path.join().fatal(). Users see clean messages, not stack traces.GREEN, RED, DIM, BOLD, RESET)..copilot/skills/squad-conventions/SKILL.mdmain, last pushed 24 September 2026.SKILL.md, not by matching a directory convention. 6 distinct layouts observed: .copilot/skills/*/SKILL.md, .github/skills/*/SKILL.md, */skill.md, .squad/*/skill.md, skills/*/SKILL.md, */SKILL.md./microsoft/waza.md, and each skill at its own .md URL.