PARAS MADAN
All writing

Latest in AI

OpenSpec 2.1 Global Skills: What to Check Before Switching

OpenSpec 2.1 changes where coding-agent skills live. Check developer machines, fresh clones and hosted agents before moving a team's repository to global skills.

A coding agent working on your laptop and a hosted agent opening the same repository do not necessarily see the same files. That distinction matters for OpenSpec 2.1, which introduces global skill installation.

The November 17 release lets supported coding agents share one installation across projects on a machine. OpenSpec's workflows themselves have not changed. The change is where the instructions live and how a team distributes them.

For a solo developer, that can simplify setup. For a team, it creates a migration decision: should the skills travel with the repository, or should each execution environment install them separately? I would answer that before treating the update as routine maintenance.

Decide who needs to read the skills

The official 2.1 upgrade guide recommends keeping skills in the project when GitHub's hosted Copilot agent reads them from the repository. Choosing the project option preserves those files; committing openspec/config.yaml records the choice for teammates.

Switching to global installs skills on the local machine and removes the repository copies. The guide says to upgrade everyone's CLI before switching, since older versions only understand project skills. Commit the removals, then have teammates pull and run openspec update to complete their local setup.

My practical rule would be to choose the location that every required agent can reliably access, not the one that produces the cleanest-looking repository. Fewer checked-in files are not a useful improvement if a remote worker loses the instructions it needs.

Inspect three environments before migrating

I would use a small rollout checklist covering three places: an existing developer machine, a clean checkout, and the hosted agent environment. This is a proposed validation process, not a claim that I tested the release.

On the existing machine, first establish what currently works. Ask the coding agent to identify the OpenSpec skills available to it and confirm the expected workflow is accessible. Keep a record of any team-specific additions so the comparison after migration is meaningful.

For the clean checkout, use a colleague's freshly prepared environment or an isolated test environment without the original developer's global installation. Follow the setup instructions a new teammate would receive. The question is whether those instructions recreate the intended behavior, rather than whether a seasoned developer's machine already has enough incidental state to make it work.

Finally, inspect the hosted agent path separately. A successful local test does not show that a remote session has the same installation. If that agent depends on committed skill files, keep the project scope unless you have another verified way to provide them.

Update scripts as well as people

In a new repository, openspec init --tools <ids> now defaults to global installation. Scripts that need repository-local skills should explicitly use --scope project. Existing projects receive a location choice during interactive update; unattended updates refresh the current location rather than asking that question.

Review onboarding scripts, template repositories and written setup instructions together. Otherwise, two teammates following different versions of the instructions could end up with different assumptions about where the same agent instructions belong.

I would make the intended scope explicit in the team's setup documentation even when it matches the default. That gives a reviewer something concrete to inspect and makes the next change of default less surprising. Assign one person to verify the fresh-environment path before calling the migration complete.

Preserve custom work before refreshing

The release notes warn that updating replaces built-in skill folders, including custom edits or additional files inside them. Save those changes first and inspect openspec update --dry-run. Installing or refreshing skills also requires Git and GitHub access. The npm installation requires Node 22.20.0 or newer; the standalone executable does not require Node.

Do not combine this rollout with unrelated changes to how your team writes specifications. Keeping the working method stable makes a missing-skill problem easier to identify. Review the proposed file removals, confirm the chosen scope, and have a teammate repeat the documented setup before merging the migration.

Global skills are a distribution convenience, not proof that every environment is configured. The useful finish line is straightforward: the people and agents doing the work can still find the right instructions after a fresh start.

I'm Paras. I work at the intersection of AI, engineering and distribution.

I help AI teams turn developer-tool changes into practical adoption and migration guidance.

Book a 30-minute call.