feat(init): sync installed skills with the manifest

[domitriusclark]

Summary

EX-3055. Stacked on #8555, so review that first.

#8555 makes netlify init install the Netlify skills and refresh outdated copies, but it leaves copies under deprecated or prior names in place and gives the user no way to put an edited skill back to the shipped release. This PR adds the rest of the sync: re-running init deletes an unedited deprecated skill, migrates an unedited copy under a prior name to its current name, and cleans up what an interrupted run left behind. Anything the user edited is kept and listed, and --reset-context replaces, migrates or deletes it.

This is the first path that deletes directories in a user's repo. A directory is removed only when its tree hash matches a release we shipped, re-hashed right before the rm, or under --reset-context when it sits at a manifest name. Nothing else is touched: unknown directories, symlinks, and a directory that differs from a skill name only by case on macOS are all left alone, with or without the flag.

Changes

• src/utils/init/agent-skills.ts: syncSkills takes reset. New rules per directory:
  • deprecated, unedited: removed. Edited: kept and reported, removed with --reset-context.
  • prior name, unedited: the current name is installed if absent and the old directory removed. If either copy is edited, both stay until --reset-context.
  • modified: kept, replaced with --reset-context. A symlink or file at the skill's own name is replaced too; only the link is removed, never its target.
  • leftovers: .netlify-skill-<name>-* staging directories older than ten minutes and <name>.old-* backups that hash to a shipped release are removed when <name> is in the manifest. Younger staging directories belong to a run that may still be writing them.
• Guards: before any forced replace, every entry in the skills directory is checked by inode against the target name, so a case twin (Netlify-Deploy next to netlify-deploy) is never renamed away. The assembled staging tree must hash to the manifest tree_hash before it is swapped in. A directory without SKILL.md under a prior or deprecated name is ignored.
• Output: the summary line counts reset, renamed and removed alongside added and updated. Kept copies are listed, with a --reset-context hint only when reset would act on one of them. A directory that fails part way (SkillsSyncInterrupted) still prints what it finished before the warning.
• src/commands/init/index.ts, init.ts: the --reset-context flag, passed through InitExtraOptions; resetContext is added to the analytics payload and the sites_agentSkillsSetup event. dev and watch are unchanged.
• docs/commands/init.md: the new flag.

Testing

• tests/unit/utils/init/agent-skills.test.ts (46 tests, fetch stubbed): deprecated removed by exact and by prior name, edited deprecated kept then removed on reset; prior name migrated, removed as superseded, kept when either copy is edited, two prior names in one run; modified kept then reset, symlink reset without touching its target; leftover cleanup incl. a fresh staging directory left alone and an edited backup kept; staged tree-hash mismatch refused; case twin with and without SKILL.md never replaced (asserts branch on whether the tmp filesystem is case-insensitive); partial result carried on failure; summary and hint lines.
• tests/integration/commands/init/init.test.ts: the mock skills host now takes a manifest spec; shared init helpers hoisted. New test runs init against a stale, an edited and a deprecated copy (1 updated, 1 removed, 1 kept), then init --reset-context (1 reset). 9 tests pass.
• npm run typecheck, npm run lint and npm run format:check are clean.

Known gaps

• The live manifest has no deprecated or renamed skill yet, so those paths are exercised by tests only.
• Tests ran on macOS (case-insensitive APFS). The case-sensitive branches are inferred until CI runs on Linux.
• Two netlify init runs in the same repo at once are not serialized. The age guard and the staged hash check turn that race into a failed install rather than a corrupt one; the next run completes it.
• Windows executable-bit hashing, as in feat(init): install Netlify agent skills by default #8555.

---

• Open a bug/issue before writing your code 🧑‍💻 (tracked in Linear as EX-3055)
• Read the contribution guidelines 📖
• Update or add tests (if any source code was changed or added) 🧪
• Update or add documentation (if features were changed or added) 📝
• Make sure the status checks below are successful ✅

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: ad8fb0b8-aaaa-4b1e-9dee-21beac2e0ff1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/netlify-cli@8556

commit: a623e2c