Repository navigation
feat(skills): install skills through the skills package, per project or once per machine - #2241
Conversation
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>
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Walkthrough
Merge Risk:
|
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>
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>
…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>
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>
Deploying openspec-docs with
|
| 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 |
… 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
left a comment
There was a problem hiding this comment.
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 --jsonnever 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
--toolsselection 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.
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>
fixed, requesting re-review.
alfred-openspec
left a comment
There was a problem hiding this comment.
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.mdas 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.
…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>
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
openspec updatein every repository.skills, the package behindnpx skills, already does.What it does
Skills are installed by the
skillspackage. They can live once on your machine, or in a project as before.In a repo that already has its own skills,
openspec updatein a terminal asks once:skillsScope: projectinopenspec/config.yaml. Commit it and teammates are not asked.Nothing moves until someone chooses. An update without a terminal refreshes the skills where they are and asks nothing.
~/.agents/skills/, or the tool's own global folderskillspackageopenspec updateskills/in this repository, at your CLI's release tagopenspec init --tools …in a new repoBreaking change for setup scripts. The last row. To keep skills in the repo, use
openspec init --scope project --tools <ids>or setOPENSPEC_SKILLS_SCOPE=project. The release notes lead with it.How it works
Fission-AI/OpenSpecat the tag of the running CLI and installs itsskills/folder. It is bundled into the standalone binary, so no Node is needed.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..agents/skills/.openspec-target. Nothing else says which tools read.agents/skills/directly.src/.Where to look
src/core/skill-installer.tsskillspackage: source, tag, scope, toolssrc/core/global-skills.tssrc/core/shared/shared-skill-install.tssrc/core/update.tssrc/core/init.tssrc/core/project-skills-scope.tsopenspec/config.yamlsrc/core/templates/workflows/.changeset/install-skills-globally.mddocs-lab/help/upgrade-to-2-1.mddocs-lab/help/upgrade-to-2.md,docs-lab/start/setup.mdProof it works
openspec validate install-skills-globally --strictThe 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.0tag exists, so that path was tested through real Git against a local copy of the release.Notes
skillspackage 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..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.npx skills add Fission-AI/OpenSpecused to also install four skills meant for working on OpenSpec itself. They are now hidden from it.🤖 Generated with Claude Code