Skip to content

feat(skills): install skills through the skills package, per project or once per machine - #2241

Merged
clay-good merged 87 commits into
mainfrom
claude/global-skills-install
Nov 17, 2026
Merged

clay-good merged 87 commits into
mainfrom
claude/global-skills-install

Conversation

@clay-good

@clay-good clay-good commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Status: Ready to merge once CI is green. This is OpenSpec 2.1.0, step 4 of #2022. It includes #2256, which was merged into this branch.

Why

  • For people with many projects: in 2.0 every project carries its own copy of the skills, so each CLI upgrade means running openspec update in every repository.
  • For OpenSpec: it maintained its own installer for a job that skills, the package behind npx skills, already does.

What it does

Skills are installed by the skills package. They can live once on your machine, or in a project as before.

openspec init --tools claude                    # new repo: skills on your machine
openspec init --scope project --tools claude    # new repo: skills in the repo
openspec update                                 # brings whatever you have up to date

In a repo that already has its own skills, openspec update in a terminal asks once:

Where should OpenSpec keep this project’s skills?

❯ Keep in this project   Keep the skills in this repo.
  Switch to global       Share the skills across projects on this machine.
  • Keep saves skillsScope: project in openspec/config.yaml. Commit it and teammates are not asked.
  • Switch installs the skills on your machine, then removes the repo copies. Commit the removals. Each teammate then sets up their own tools once.

Nothing moves until someone chooses. An update without a terminal refreshes the skills where they are and asks nothing.

2.0 2.1
Skills for the whole machine Not possible One copy in ~/.agents/skills/, or the tool's own global folder
Skills in a project Written by OpenSpec Installed by the skills package
Moving a repo to global Not possible Offered inside openspec update
Skill text Differed by workflow profile The same for everyone
Where the text comes from Generated on your machine skills/ in this repository, at your CLI's release tag
openspec init --tools … in a new repo Skills in the repo Skills on the machine

Breaking change for setup scripts. The last row. To keep skills in the repo, use openspec init --scope project --tools <ids> or set OPENSPEC_SKILLS_SCOPE=project. The release notes lead with it.

How it works

  • Where the skills come from. The package fetches Fission-AI/OpenSpec at the tag of the running CLI and installs its skills/ folder. It is bundled into the standalone binary, so no Node is needed.
  • The tag. It uses v<version>. A release is published as @fission-ai/openspec@<version> and gains the short tag afterward, so until then the installer uses the release's own tag. Both name the same commit.
  • Git is required. Installing or refreshing skills needs Git and access to GitHub. A failed fetch is reported; there is no offline fallback.
  • An update equals a fresh install. Each built-in skill folder is replaced whole, so the result matches a new install with the same tools and profile. Edits and files added inside a built-in folder are removed. Separately named skills are kept.
  • One skill text for every profile. A published file can only be installed as it is if everyone gets the same text. In 53 places a skill used to read differently depending on which other workflows were installed. Each now says "use that skill if it is installed, otherwise do this". No workflow changed.
  • Which tools a repo uses is still recorded in .agents/skills/.openspec-target. Nothing else says which tools read .agents/skills/ directly.
  • Less code. The source loses more installer code than it gains: +1,338 / −1,693 lines under src/.

Where to look

Read What it does
src/core/skill-installer.ts The call into the skills package: source, tag, scope, tools
src/core/global-skills.ts Skills installed for the machine
src/core/shared/shared-skill-install.ts Skills installed in a project
src/core/update.ts The Keep or Switch question, and the refresh
src/core/init.ts Where a new repo's skills go, and moving a repo to global
src/core/project-skills-scope.ts The Keep choice in openspec/config.yaml
src/core/templates/workflows/ The 53 reworded hand-offs
.changeset/install-skills-globally.md The release notes users will read
docs-lab/help/upgrade-to-2-1.md The upgrade page for 2.1: what changes, the one question, the steps for each answer
docs-lab/help/upgrade-to-2.md, docs-lab/start/setup.md The 1.x to 2.0 guide and the setup guide

Proof it works

Check Result
Every release 0.12 to 2.0 × every profile × LF/CRLF, upgraded with this build 326 of 338 end up exactly like a fresh install. The other 12 are 2.0 projects set up for every tool; they keep their existing links for tools the package doesn't know, as intended
Upgrades from real npm releases 19 of 19
Existing users from seven releases (0.23 to 2.0), with their own files in place Every upgrade exits 0, user files are byte-identical, and a second update changes nothing
Skills installed by 2.0 and 1.17, calling the new CLI All 12 workflow skills: every command and flag they use still exists, with the fields they expect
JSON output of 12 commands, 2.0.0 compared with this build Identical apart from durations and install paths
Full suite, lint, openspec validate install-skills-globally --strict Pass
Install tests against the standalone binary Pass
The state right after a release, with only the release's own tag Project install, update and global install all work
The release notes and guides, followed step by step against the build Corrected where wrong or silent; nothing a user following them breaks

The only CLI surface this changes is openspec init, which gains --scope. No other command, flag or JSON output is touched.

Not tested by hand: Windows, which CI covers, and the Keep or Switch question at a real terminal, which is covered by tests that answer it. A global install from GitHub can't be run end to end until the v2.1.0 tag exists, so that path was tested through real Git against a local copy of the release.

Notes

  • The skills package is pinned to 1.8.1. That is the version this was built and tested on. 1.9.0 was published the day this merged, and a caret range would have given npm users a version nothing here had run against.
  • Tools the package doesn't know (EasyCode, Oh My Pi, DeepSeek Harness, AtomCode and others) get the skills in .agents/skills/ only. A tool that reads only its own folder needs one link, which the guide shows. Links 2.0 made are left in place.
  • A teammate still on 2.0 can keep working in a repo that kept its skills. Each update restores the text from that CLI's own version, so upgrade the team before switching a repo to global.
  • Maintainer skills. npx skills add Fission-AI/OpenSpec used to also install four skills meant for working on OpenSpec itself. They are now hidden from it.
  • Later releases: the router skill with its references. docs(openspec): refine global install scope proposal #1641, the earlier design, is replaced by this change.

🤖 Generated with Claude Code

clay-good and others added 14 commits November 12, 2026 07:38
Step 4 of #2022. Replaces the pre-2.0 add-global-install-scope change,
which still installed command files and added an installScope setting.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each tool's home skills folder matches the skills CLI 1.8.1 table, with
its environment overrides. The shared installer takes a layout; the
project layout is the default, so project installs are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
runGlobalSkills writes the global profile's skills to ~/.agents/skills
and links them into each tool's home skills folder, the layout npx
skills add -g uses. It reuses the 2.0 installer with a home layout, so
edited skills and npx copies are kept and nothing is written through a
link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
openspec init --global --tools <ids> installs the skills for this
machine; openspec update --global refreshes them, with --dry-run and
--json. Neither reads or writes the current folder, and project-only
options are refused with --global.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When a project has its own skills and this machine's global install
covers its tools, interactive update asks once. Yes removes the
project's unedited OpenSpec skills and links, keeps edited ones, and
saves skills: global in openspec/config.yaml; no saves skills: project.
Non-interactive runs only suggest --use-global-skills. With
skills: global, init and update write no project skills and tell a
person without the global install what to run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Proved with the real skills CLI 1.8.1: after npx skills add -g wrote
over OpenSpec's global copies, update --global wrote them back and
called them the user's edits, so the two would trade the folders.
Skills in the skills CLI's lock file are now kept, and the output names
the command that hands them back to OpenSpec.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Setup gains the --global install and the per-project switch; supported
tools lists where each tool's skills go for a machine; the CLI and
config.yaml references cover --global, --use-global-skills and
skills: global. Minor changeset.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Checked with the released 2.0.0: update reports no configured tools and
writes nothing; only init writes the project skills back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A regression check against 2.0.0 found two differences for people who
never use --global: a home folder set up with a project init looked like
a global install, so update offered a switch nobody asked for; and
reading skills: through the full config parser repeated a broken
config.yaml's warnings on every update. A --global install now writes
~/.agents/skills/.openspec-global (removed with it, and init --global
refuses a home set up as a project), and skills: is read on its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An adversarial review found:
- a relative or ~ CLAUDE_CONFIG_DIR (or XDG_CONFIG_HOME, HERMES_HOME,
  GROK_HOME, VIBE_HOME) made --global write into the current folder;
  ~/ is now expanded and anything still relative ignored
- an edited global skill was replaced with no copy (home has no git);
  it is now saved as SKILL.md.bak first, and the dry run says so and
  lists tools the real run would fail on
- naming only tools with no home folder removed the whole install
- a skill npx skills recorded but installed elsewhere froze OpenSpec's
  own copy; it is kept only while the text there isn't OpenSpec's
- switching a 1.x project left its command files and undercounted
- a config.yaml that can't be edited still removed the skills
- a switched project lost the record of its tools, so teammates got
  --tools <ids> and skills: project couldn't bring the skills back

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keeping the tool list as plain lines made OpenSpec 2.0's update see the
tools and write the project's skills back, so a teammate on 2.0 could
undo a switch by running update and committing. The record is now
global <tool> lines, which 2.0 doesn't read as tools; 2.1 uses them to
name the exact --tools and restores them as plain lines when the
project goes back to skills: project. Docs cover the .bak copy and the
way back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ith no home folder

A second review found:
- switching a project whose .agents links elsewhere deleted and wrote
  in the linked folder; the shared folder is now bounded before any
  write or removal, and the switch is refused there
- skills: global was saved through a config.yaml link; refused now
- --tools none removed the global records through a ~/.agents link
- a tool with no machine-wide folder looped between update telling
  people to run init --global and init --global refusing it; the switch
  isn't offered for such a project, and a switched one is told how to
  go back
- a project init in a home folder holding the global install merged
  the two lists; refused now
- the backup message named SKILL.md.bak when the copy was .bak1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A third review found that a project in the home folder could take the
global install for its own copy: update offered a switch and then
removed the global skills. update and init now refuse a project in a
home holding the global install, and --global refuses a home that is a
project. Also: a tool folder under home that links to a dotfiles repo is
refused like ~/.agents is, with a message saying why; update --global
reports a linked ~/.agents instead of 'Nothing is set up'; and a
--use-global-skills run that doesn't switch exits 1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the way out

A final review found: a repository cloned to ~/openspec with specs/ or
changes/ blocked --global (only openspec/config.yaml or project.md now
count); a home that later became a project stopped update --global and
neither message named the fix (refresh keeps working, and both messages
name openspec init --global --tools none); and a home reached through a
link let a dotfiles-linked tool folder through (paths are compared as
real paths). The refusal names the folder that is the link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review
Walkthrough

The PR adds global and project skill installation, scope selection for init, global refresh for update, and shared skill text generation. It also updates documentation, tests, and release support for these changes.

Changes: Global and Project Skill Installation

Layer / File(s) Summary
Shared workflow text
src/core/shared/*, src/core/templates/*, skills/*/SKILL.md, scripts/*, test/core/templates/*, test/core/shared/*, test/utils/*
Workflow templates now use fixed handoffs with installed-skill conditions and fallback paths. Optional workflow resolution was removed. Shared skill generation strips volatile version frontmatter.
Skill installation engine
package.json, src/core/global-skills.ts, src/core/shared/shared-skill-install.ts, src/core/shared/tool-detection.ts, src/core/shared/own-skill-texts.ts, src/core/shared/released-generated-fingerprints.ts, test/core/global-skills.test.ts, test/core/project-skills-vercel.test.ts, test/core/update.test.ts, test/core/warp.test.ts
The skills package manages project and global skills, including lock-file updates, ownership checks, fetch fallbacks, links, and profile-based removal. Tests cover installation, updates, lock handling, and published skill text.

Init Scope and Update Flow

Layer / File(s) Summary
Init scope and migration
src/cli/index.ts, src/core/completions/command-registry.ts, src/core/config-schema.ts, src/core/global-config.ts, src/core/completion-tip.ts, src/core/init.ts, test/core/init.test.ts, test/core/global-skills.test.ts
openspec init accepts `--scope global
Global refresh and reporting
src/core/update.ts, src/core/update-plan.ts, test/core/global-skills.test.ts, test/core/update.test.ts, test/cli-e2e/upgrade-from-releases.test.ts
openspec update refreshes global skills when installed, including outside a project. Dry runs record planned global refreshes and failures.

Documentation and Release Support

Layer / File(s) Summary
Docs, specifications, and release support
docs-lab/*, openspec/changes/*, .changeset/*, flake.nix, package.json, scripts/*, vitest.config.ts, test/cli-e2e/upgrade-from-releases.test.ts
Documentation and change records describe scope selection, migration, lock files, and fallback behavior. The Nix dependency hash, test environment, and release fingerprint tooling were also updated.

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Merge Risk: Low · previous review 407d4

No data-loss or security issue remains in the reviewed summaries. Before merging, fix the notice when global installation partly fails and correct the documentation about the saved scope default and the update refusal outside a project.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title "feat(skills): install skills through the skills package, per project or once per machine" matches the main change. The PR adds machine-wide skill installation through the skills package nex…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title "feat(skills): install skills through the skills package, per project or once per machine" matches the main change. The PR adds machine-wide skill installation through the skills package next to project-level installs, and the title names both scopes. The title is specific and short. It uses a conventional commit prefix, which is acceptable.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

clay-good and others added 10 commits November 12, 2026 08:46
A parity check against the real skills CLI 1.8.1 found:
- Crush followed XDG_CONFIG_HOME, but the skills CLI always uses
  ~/.config/crush, so npx skills remove left OpenSpec's link dangling
- Devin Desktop borrowed the folder of the skills CLI's Devin for
  Terminal; where Devin Desktop reads machine-wide skills isn't known,
  so it is now set up per project like other unknown tools
- a skills CLI lock older than its format version 3 still counted,
  though the skills CLI ignores it
- a copy npx skills writes into a tool's folder (its copy mode) was
  reported as the user's own changes; it is now named as npx's
- MiniMax Code got a refusal that read like an unsupported tool

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… strand a tool

Hostile-condition and past-failure reviews found:
- killing the first init --global left a list without the marker, and
  every later run was refused with a false message; the marker is now
  written before anything else
- a --tools none that failed for one tool dropped the record and left
  that tool's links dangling with nothing to clean them up; such tools
  stay on record until a removal finishes
- an interrupted project switch could lose the project's tool record;
  it is written before anything is removed and again after, and the
  installer no longer touches it during a switch
- a switch that couldn't remove some links reported success; it now says
  so and exits 1, and the next update finishes
- a profile with no workflows, or an unreadable global config, made
  --global remove the machine's skills while reporting success; both are
  refused now, changing nothing
- two --global runs at once could take each other's writes for edits;
  a lock (taken over after 10 minutes) allows one at a time
- init in a switched project set up a tool that can't use machine-wide
  skills with none at all; refused now
- init in a switched project without the global skills said they were
  there and showed a skill to run; it now names the command to install
- Ctrl-C at the switch question says nothing was changed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tched projects

A fresh-eyes code review found:
- in a switched project that also has a tool keeping its own skills
  (MiniMax Code), update dropped the switched tools from its list, so it
  removed GitHub Copilot's cloud files and called Copilot a new tool;
  Copilot sync, new-tool detection and profile notes now see every tool,
  including those recorded as global <tool>
- a dropped tool whose links couldn't be removed lost its record; links
  left by a failed removal are now recorded as unlink <tool>, retried on
  the next run, and never set up again (update --global used to
  reinstall the tools of a half-finished --tools none)
- --tools none after an interrupted first install left OpenSpec's skills
  behind; it now clears them by their text
- a skills: global project with no shared-folder tools got an empty
  record and a false success line
- a skill kept during a switch wasn't recorded, so the warning repeated
  and switching back overwrote the edit; kept skills are recorded now
- a refused --use-global-skills on a project switched back lost its
  tool record; the record is restored first
- Ctrl-C at the switch question now says only that the project wasn't
  switched

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ble folders

A crash-and-lock review (kill sweeps across init --global, update
--global, --tools none and the project switch) found:
- a --tools none killed after the skills but before the links left
  dangling links and no record; a removal now keeps the tool list until
  every link is gone
- an install killed before its tool list was written was reported as
  'Nothing is set up'; update --global now says the install didn't
  finish and exits 1
- a read-only ~/.agents was reported as another run in progress, and a
  file where ~/.agents goes showed a raw error; both now say the folder
  can't be written, and removing when nothing is installed takes no lock
- an empty SKILL.md left by a cut-short write was called the user's edit
  and backed up; it isn't now
- in a switched project, a tool that reads ~/.agents/skills itself
  (Cursor, Codex) counts as covered by the global install

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…shrink a switched project

A kill-on-write review found:
- killing init --global while it dropped a tool left that tool's links
  with no record (the new list was written before the links went), and
  a later --tools none claimed success over dangling links; pending
  removals are now written into the list first and cleared once done
- after a killed --tools none, update --global put the whole install
  back; a removal now turns the list into unlink records before
  touching anything, so the next run continues it
- a removal with the marker but no list cleared the skills and left
  every link; links pointing at OpenSpec's shared copy are now found in
  each tool's home folder and removed
- an empty SKILL.md was kept as the user's during a removal
- --tools none with nothing installed deleted an empty ~/.agents
- a project switched to a global install with fewer workflows than it
  had (an older profile there) quietly lost those skills; the switch is
  now refused, naming update --global

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…achable records

A review of the last fixes found:
- the cleanup for a removal with the marker but no list went through
  every tool's home folder: it failed on tools never set up (with a
  false message and nothing on record to retry) and removed real
  folders, not just links. That state can't come from a killed run (the
  list is always written before any link), so the cleanup now only
  clears OpenSpec's skills by their text and touches no tool folder
- a pending unlink whose tool folder now links outside home could never
  clear; such a folder holds nothing OpenSpec can reach, so the record
  is dropped and the output says it was left alone
- a refused run deleted an empty ~/.agents the user already had; only
  folders the run created are tidied
- a retry that only finished removing links said 'Removed OpenSpec's
  skills' again; it now says it finished the removal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he profile

A kill-at-every-write sweep (295 kill points) found:
- a write of ~/.agents/skills/.openspec-target cut short lost the
  pending unlink records with it; every file the global install writes,
  and the project switch's record and config.yaml, are now written to a
  temporary file and renamed into place, so they are whole or untouched
- the check that refuses a switch which would take skills away compared
  against the skills on disk, so a skill the profile had dropped blocked
  a valid switch; it now compares the global install with the profile

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…vals quiet about npx

A final kill-at-every-write sweep (355 kill points) found that a kill
between an atomic write's temporary file and its rename left that file
behind, so a later removal couldn't tidy the folder; the global install
now clears them under its lock, and the project switch clears its own
two. A removal retry no longer prints the npx skills hand-back advice.
The design records how interrupted and failing runs are handled (D7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replace the custom global installer with Vercel's skills package, called
through its API. OpenSpec still writes the skill text, into its data
folder, and the package places it in ~/.agents/skills with each tool's
link and its own lock file.

- openspec init --scope global|project replaces --global
- plain openspec init uses the global skills once they exist, and asks
  once at a terminal otherwise; scripted runs stay in the project
- plain openspec update refreshes the global skills from any folder
- openspec init --scope global in a project with its own skills removes
  them, and stops first if one was edited
- project installs are unchanged and still use 2.0's installer

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@clay-good clay-good changed the title feat(skills): install skills once per machine with --global feat(skills): install skills once per machine through the skills package Nov 12, 2026
clay-good and others added 3 commits November 12, 2026 15:23
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- skip a same-named skill OpenSpec didn't install, and say so
- when moving a project, remove its skills only after the global install
  succeeds, and remove the command files 1.x wrote as well
- never treat the home folder as a project with its own skills
- save the global choice so an empty profile doesn't flip the machine back
- refresh the global skills even when the project update fails
- leave MiniMax Code to its project install, which already uses the home folder

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The skills in skills/ wrote references as /openspec-propose. The CLI
installs openspec-propose, because not every tool uses a slash. Generate
both with the same transform, so the published skills match what the CLI
installs when every workflow is selected.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
SanHsien added a commit to SanHsien/OpenSpec that referenced this pull request Nov 12, 2026
…ode change

Record adopt/skip/defer verdicts for the upstream commits, PRs and issues
that turned --strict red on 2026-11-13, then advance the baseline.
Upstream Fission-AI#2223 (feat(skills)!, 143 files) is deferred because it changes
where skills install; Fission-AI#2241 follows it. The rest are skipped: upstream CI
and release bot changes, a test for a file this fork does not have, and
community showcase entries.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
clay-good and others added 7 commits November 16, 2026 13:43
A release is published under @fission-ai/openspec@<version>, and
v<version> is added by hand afterward. With only the short tag tried, a
freshly published CLI failed init and update for everyone until that
second tag existed. The installer now falls back to the release's own
tag, which names the same commit. When neither exists it still reports
the missing v<version>.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…g.yaml

The choice to keep a project's skills in the repo was a header line in
.agents/skills/.openspec-target. It now sits with the project's other
settings, where a team reviews and commits it, and the target file goes
back to a plain list of tools. That list stays: nothing else in a repo
says which tools read .agents/skills directly, and without it update
forgets Codex and Cursor.

The save edits one key and keeps the rest of the file as written. A
config that can't be edited is left alone and update asks again.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…nstalls

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…stalls

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ills

The move removed the repo's skills and left the config saying they are
kept there.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ere wrong or silent

Checked by following the release notes and guides against the build.

- update replaces each built-in skill folder whole, edits and added
  files included, with no message; point to --dry-run
- after a switch to global, a teammate answers Yes in a terminal, or
  runs openspec init --tools in a script
- the upgrade guide opens with what is new in 2.1: the scripted default,
  the Git requirement, the one question in existing repos
- no question appears without a terminal or with --force
- a --scope project repo is still asked once
- init --scope global in a repo with skills removes them without asking
- what a Failed to clone error means, the home-folder form of linking
  another tool, and the Updating section for global skills
- the CLI reference no longer lists an edited-skills note the build
  does not produce

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…install

Takes main's lockfile and adds this change's one dependency. Pins the
skills package to 1.8.1, the version this was built and tested against:
1.9.0 was published today, and a caret range would hand npm users a
version nothing here has run on.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Deploying openspec-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 6a87ac9
Status: ✅  Deploy successful!
Preview URL: https://a91cf5ea.openspec-docs.pages.dev
Branch Preview URL: https://claude-global-skills-install.openspec-docs.pages.dev

View logs

clay-good and others added 2 commits November 16, 2026 15:09
… say what a teammate does after a switch

The message after moving a repo to global said teammates run openspec
update once. They answer Yes to a question that defaults to No, or run
openspec init --tools in a script, as the guides now say.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… the machine

The store-only example says its files are written in the code repo, so
it asks for --scope project. Refreshed is what a project install prints.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@alfred-openspec alfred-openspec left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed eb626e3, including the rewritten installer, scope selection/migration, workflow handoffs, and their canonical docs. The earlier technical clearance at b22b7c1 does not cover this rewrite.

Three reproduced runtime issues block approval:

  • Repairing a missing tool link deletes a file in the canonical skill folder that update --dry-run --json never lists.
  • Global removal can report success while an excluded skill remains readable in a tool's folder.
  • The implicit scope default is decided before interactive tool selection, so selecting a project-only tool fails although the same --tools selection succeeds.

The canonical skills reference also still describes the removed profile-dependent handoffs. Details and reproductions are inline.

Fresh checks: frozen-lock dependency install, build, lint, type-check, strict change validation, and 1,057 focused tests passed across 53 files. This was not a local full-suite or Windows run. On the final CI read, no checks had failed; Windows tests and darwin-x64 verification were still running. Workflow text/parity checks do not establish actual model compliance.

Direction: 4/5. Shared installs address repeated project maintenance, and the package boundary removes substantial custom installer code. Execution: 3/5. Broad passing coverage, but the preview and removal results do not reliably describe filesystem outcomes, and the interactive fallback has a gap.

Separately, the changed docs-lab/ pages still need @TabishB's final review before approval. No merge performed.

Comment thread src/core/shared/shared-skill-install.ts Resolved
Comment thread src/core/global-skills.ts Resolved
Comment thread src/core/init.ts Resolved
Comment thread src/core/shared/skill-generation.ts Resolved
clay-good and others added 5 commits November 16, 2026 16:06
Repairing one destination of a skill reinstalls it into all of them, and
each folder is replaced whole. The preview listed only the destination
that needed work, so a file kept beside a skill in the shared folder was
deleted by an update whose dry run never mentioned it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The skills package can fail to remove a tool's copy without reporting
it, so an update said the skills were removed while one stayed readable
in the tool's folder. The folders are now checked after the removal.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The default was decided before the tool picker ran, so picking a tool
that needs project scope failed, though the same tool passed with
--tools worked. An explicit --scope global still refuses it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Every skill reads the same whatever the profile, so a hand-off checks at
run time or follows the CLI's recovery step. The reference still said
lines naming a missing skill are left out.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…dry run

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@clay-good
clay-good dismissed alfred-openspec’s stale review November 16, 2026 22:41

fixed, requesting re-review.

@alfred-openspec alfred-openspec left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed fd07472, covering the seven-file fix delta from eb626e3 and reusing the unchanged parts of the earlier review. All four findings are resolved; I found no remaining technical blocker in this follow-up.

I reran the saved cases against a fresh build in throwaway homes:

  • Repairing the missing Claude link now lists notes.md as a deletion in dry-run, matching the real update.
  • A non-writable global skill copy now makes update fail with its path instead of claiming success; retry succeeds after restoring permissions.
  • Eve-only and mixed Claude/Eve picker selections now install project skills. Explicit global scope still refuses Eve. These exercised the built execution path with the interactive check and picker result substituted, not a real terminal session; the regression tests also verify the picker runs once.
  • The canonical skills reference now matches the profile-independent handoffs.

Fresh validation: frozen-lock install, build, lint, type-check, strict change validation, and 427 focused tests passed across 8 files. Hosted CI is green, including Windows tests and all binary verifications. This was not a new local full-suite or Windows run.

Direction: 4/5, unchanged. Execution: 4/5: the original failures are fixed and covered, with the stated platform and interactive-test limits.

Technical review is clear, but approval still awaits @TabishB's required final review of the changed docs-lab/ pages. No merge performed.

Comment thread docs-lab/start/setup.md Resolved
clay-good and others added 5 commits November 16, 2026 17:38
…re skills live

Upgrade to 2.1 gets a page of its own: what is changing, the one
question update asks, and the steps for each answer. The release notes
use the same steps. The 2.0 guide goes back to being about 1.x.

Skills are "installed globally" or kept "in your project repo"
throughout, in place of "projects share the skills" and "in Git". The
prompt's second choice says the same.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Two fragments stood where sentences should be: "finish the remaining
planning artifacts from the change. start implementation from the
tasks".

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…race

A machine without Git got "Failed to clone … spawn git ENOENT" followed
by a stack trace. It now reads that Git is needed and is not on PATH.
Covers the wording of Node and of the standalone binary.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The site's search index names each section of a page <url>-<n>, so the
slug upgrade-to-2-1 collided with the first section of upgrade-to-2 and
the build failed. The page is now at /docs/upgrade-2-1.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ening

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@clay-good
clay-good added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit ee9038a Nov 17, 2026
34 checks passed
@clay-good
clay-good deleted the claude/global-skills-install branch November 17, 2026 00:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants