[Bug]: `integration upgrade` overwrites extension-and preset- provided Copilot skills

[dtimon]

Bug Description

When an extension or preset provides a command override, the command is correctly registered in Copilot skills mode. However, running:

specify integration upgrade --force

regenerates  .github/skills/*/SKILL.md  from the core command templates and removes the command content supplied by installed extensions or presets.

Environment

• Spec Kit:  0.14.2 
• Integration: Copilot
• Mode:  --integration-options="--skills" 
• Affected assets: extensions and presets that provide command overrides

Steps to Reproduce

specify extension add --dev /path/to/extension

or

specify preset add --dev /path/to/preset

Verify that the generated skill contains custom command content. Then run:

specify integration upgrade --force

Inspect the skill again:

grep -n "custom marker or command-specific text" \ .github/skills/<skill-name>/SKILL.md

The extension- or preset-specific content is gone.

Expected Behavior

 integration upgrade  should preserve the effective command content from all active layers:

1. Project overrides
2. Presets
3. Extensions
4. Core templates

Generated  SKILL.md  files should reflect the highest-priority effective command, including  wrap ,  prepend , and  append  composition strategies.

Actual Behavior

 integration upgrade  rewrites skills from the core command templates only. This removes active extension and preset command overrides, even though those assets remain installed and registered.

The registry may still list the corresponding entries under  registered_skills , but the generated files no longer contain their effective content.

Specify CLI Version

0.14.2

AI Agent

GitHub Copilot

Operating System

macOS 26.5.1

Python Version

3.14.6

Error Logs

Additional Context

Root cause

Extension and preset installation paths perform command registration and skill reconciliation. The integration upgrade path regenerates integration files afterward but does not reconcile the active extension and preset command layers.

Suggested fix

After an integration upgrade regenerates agent skills, run the same reconciliation logic used after extension and preset installation/removal.

The reconciliation should:

• Resolve the effective command for each registered command.
• Apply the complete extension/preset/core composition stack.
• Generate the corresponding  SKILL.md  with the correct integration frontmatter.
• Preserve user-managed files according to the existing manifest/hash rules.
• Avoid changing unrelated integrations or skills.

[github-actions]

Bug assessment — upgrade-overwrites-copilot-skills: Valid · severity high

---

Bug Assessment: integration upgrade Overwrites Copilot Skills

• Slug: upgrade-overwrites-copilot-skills
• Created: 2026-07-29T12:31:00Z
• Source: issue [Bug]:  integration upgrade overwrites extension-and preset- provided Copilot skills #3849
• Verdict: valid
• Severity: high

Report (summarized)

Reported by @dtimon. Running specify integration upgrade --force on a Copilot project configured with --integration-options="--skills" regenerates all .github/skills/speckit-<name>/SKILL.md files from core templates only. Any content injected by installed extensions or presets (via wrap, prepend, or append composition) is silently overwritten and lost, even though those extensions/presets remain installed and registered.

Environment: Spec Kit 0.14.2, GitHub Copilot, skills mode, macOS.

Symptom

After specify integration upgrade --force, the generated SKILL.md files under .github/skills/ contain only the core template content — extension- and preset-provided command overrides are gone. The registry may still list them under registered_skills, but the on-disk file no longer reflects the effective composed content.

Reproduction

1. specify init my-project --integration copilot --integration-options="--skills"
2. specify extension add --dev /path/to/extension (extension that wraps/prepends/appends a command)
3. Verify the generated SKILL.md contains the extension content.
4. specify integration upgrade --force
5. grep -n "extension-specific text" .github/skills/speckit-<name>/SKILL.md
   → Extension content is absent; only core template content remains.

Suspected Code Paths

• src/specify_cli/integrations/_migrate_commands.py:integration_upgrade() (~line 572) — calls _register_extensions_for_agent and _register_presets_for_agent after setup(), but the critical ordering flaw is in what setup() already writes.

• src/specify_cli/extensions/__init__.py:_register_extension_skills() (~line 1265) — the core issue. Lines 1364–1377 contain this guard:

  if skill_file.exists() or skill_file.is_symlink():
      if not is_expected_dev_symlink:
          continue          # <-- extension content silently skipped
  elif skill_dir_preexists:
      continue              # <-- also skipped if dir exists

  This guard is correct for a fresh extension install (it should not overwrite user-modified files), but it becomes incorrect when called after integration.setup() has just freshly regenerated the core template SKILL.md files — all skill files now exist, so _register_extension_skills skips every one of them.

• src/specify_cli/integrations/copilot/__init__.py:CopilotIntegration.setup() — writes core-template SKILL.md files during upgrade (Phase 1), before the re-registration step gets a chance to compose extension/preset layers on top.

• src/specify_cli/presets/__init__.py:_register_skills() (~line 2647) — uses a different guard: if (skills_dir / skill_name).is_dir() it overwrites. So preset skills do get re-applied after upgrade. This asymmetry means extensions are broken but presets may survive.

Root Cause Hypothesis

Confidence: high.

_register_extension_skills deliberately refuses to overwrite existing SKILL.md files or write into pre-existing skill directories, to protect user-customized skills. This is the correct policy for extension install. However, integration upgrade calls integration.setup() in Phase 1, which writes fresh core-template SKILL.md files for every command. When the post-upgrade re-registration then calls _register_extensions_for_agent → _register_extension_skills, every skill file already exists (just written by setup()), so the skip guard fires and no extension content is ever applied. The result is that the upgrade's final on-disk state is indistinguishable from having no extensions at all.

Proposed Remediation

Preferred: Introduce a force: bool = False parameter to _register_extension_skills (and thread it through register_enabled_extensions_for_agent / _best_effort_extension_op). In the upgrade path, pass force=True so the skip guard does not fire for files written by the immediately preceding setup() call. The hash-tracked manifest guards in the outer integration_upgrade function already protect against unintended user-file overwrites at the integration level; repeating that protection inside _register_extension_skills is redundant in the upgrade context and causes the bug.

An equivalent, narrower alternative: rather than a force flag, delete the skill sub-directories that are known to be core-template outputs (tracked in the new manifest) before calling _register_extensions_for_agent, so the skip guard sees no pre-existing file and lets extensions write their composed content. This is more surgical but requires threading the new manifest into the helper.

Alternatives:

• Run extension/preset re-registration before setup() (and re-run setup in a mode that is aware of the effective composed content). This inverts the current architecture and is a larger refactor.
• Add a dedicated reconcile_after_upgrade method on ExtensionManager that mirrors the preset path (which already overwrites): always overwrite skill files when the caller explicitly opts in. This keeps the upgrade-specific logic isolated without changing the default fresh-install behavior.

Files likely to change:

• src/specify_cli/extensions/__init__.py — add force param to _register_extension_skills and its callers; change the skip guard to if skill_file.exists() and not force and not is_expected_dev_symlink: continue.
• src/specify_cli/integrations/_helpers.py — thread force through _best_effort_extension_op → register_enabled_extensions_for_agent.
• src/specify_cli/integrations/_migrate_commands.py — pass force=True (or force=force) when calling _register_extensions_for_agent inside integration_upgrade.
• tests/integrations/test_integration_copilot.py — add a test for the upgrade path that verifies extension skill content survives integration upgrade --force.

Tests to add or update:

• A test that: (1) initialises a Copilot project in skills mode, (2) installs a dev extension that overrides a command, (3) verifies the SKILL.md contains extension content, (4) runs integration_upgrade(force=True), (5) asserts the SKILL.md still contains extension content (not just core template content).
• Optionally, a parallel test for presets to confirm their existing overwrite behaviour is preserved (regression guard).

Risks & Considerations

• The force guard change in _register_extension_skills must remain off-by-default so that a plain extension add (non-upgrade) still refuses to overwrite user-modified skill files — the existing protection must not be weakened.
• Threading force through multiple layers (extension manager → registrar → helpers) is mechanical but touches several call sites; each must be checked to ensure the flag is not inadvertently forwarded where it should not be.
• The asymmetry between extensions (broken) and presets (working, due to different overwrite logic) should be confirmed by a test; if presets also break in certain scenarios the fix scope widens.
• No data loss beyond already-lost extension content; no migration required; no API breakage outside internal helpers.

Open Questions

• [NEEDS CLARIFICATION: Does the same skip-guard issue affect non-Copilot command-backed integrations when in skills mode (e.g. Bob in skills mode), or is it isolated to Copilot?]
• [NEEDS CLARIFICATION: Does specify preset add followed by integration upgrade --force correctly preserve preset skill content, or does the create_missing_skills flag need to be True in the post-upgrade path for presets to also be reliably re-applied?]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 🐛 Assess Bug from Labeled Issue for issue #3849 · 578.9 AIC · ⌖ 11.3 AIC · ⊞ 34.2K · ◷

[github-actions]

Pull request created: #3853

Generated by Fix Bug from Labeled Issue · 1.4K AIC · ⌖ 17.5 AIC · ⊞ 36.4K

[github-actions]

A draft fix has been proposed in #3853 for the upgrade-overwrites-copilot-skills bug.

What changed: Added a force: bool = False parameter to _register_extension_skills() and threaded it through register_enabled_extensions_for_agent() and _register_extensions_for_agent(). The upgrade path (integration_upgrade()) now passes force=True so extension content is layered on top of the core-template SKILL.md files that setup() just regenerated, instead of being silently skipped by the existing-file guard.

Next steps: Please review the draft PR. If this project has the bug-test stage configured, applying the bug-test label after merging will trigger automated regression-test validation.

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 🛠️ Fix Bug from Labeled Issue for issue #3849 · 1.4K AIC · ⌖ 17.5 AIC · ⊞ 36.4K · ◷

[github-actions]

Bug test — upgrade-overwrites-copilot-skills: ⚠️ inconclusive · 0 passed, 0 failed, 0 skipped · fix from PR #3853 (head 7c7aff7)

---

Bug Test Report: integration upgrade Overwrites Copilot Skills

• Slug: upgrade-overwrites-copilot-skills
• Date: 2026-07-29
• Source issue: [Bug]:  integration upgrade overwrites extension-and preset- provided Copilot skills #3849
• Fix under test: PR [bug-fix] Fix upgrade-overwrites-copilot-skills: pass force=True to extension skill re-registration after upgrade #3853, branch origin/fix/3849-upgrade-overwrites-copilot-skills-629c8acbe03af673, head commit 7c7aff7
• Test command: uv run pytest tests/test_extension_skills.py::TestRegisterExtensionSkillsForceFlag -v (could not execute — see Notes)
• Scope: focused subset (new regression tests in TestRegisterExtensionSkillsForceFlag)
• Result: inconclusive

Summary

The fix in PR #3853 was successfully checked out and the changed files verified. The test suite could not be executed because outbound PyPI access is blocked by the CI firewall, preventing installation of pytest and project dependencies. No pass/fail verdict is available for this run.

Test Results

Metric	Count
Passed	—
Failed	—
Skipped	—
Errored	—
Duration	—

Failures (if any)

None (tests not executed).

Fix Review (code inspection only)

The fix matches the proposed remediation from the bug-assess comment exactly. Changed files and their roles:

File	Change
src/specify_cli/extensions/__init__.py	Added force: bool = False to _register_extension_skills() (line 1295); skip guards at lines 1404 and 1406 now check and not force, so passing force=True bypasses them.
src/specify_cli/integrations/_helpers.py	Threaded force through _register_extensions_for_agent() (line 398) down to register_enabled_extensions_for_agent(key, force=force) (line 424).
src/specify_cli/integrations/_migrate_commands.py	The integration_upgrade() call at lines 870–875 now passes force=True to _register_extensions_for_agent, so the post-upgrade re-registration overwrites core-template SKILL.md files rather than skipping them.
tests/test_extension_skills.py	New class TestRegisterExtensionSkillsForceFlag (line 2949) with four regression tests covering: force=False preserves existing file; force=True overwrites it; force=True threads end-to-end through register_enabled_extensions_for_agent; force=True writes into a pre-existing directory that has no SKILL.md.

The code change is minimal and surgical: the force default is False so the existing extension-install protection is unchanged; only the upgrade path opts in with force=True.

Verification vs. Historical Fix

Not applicable — this is a fresh bug with no historical fix referenced yet (PR #3853 is the proposed fix, not a merged historical commit).

Notes & Caveats

• Environment/setup failure — tests could not run. The CI runner's firewall blocks all outbound connections to PyPI (403 Forbidden on every pip/uv install attempt). Neither pytest nor hatchling (the build backend) could be installed, making pip install -e .[test] impossible. The verdict is therefore inconclusive rather than a real pass/fail.
• The fix was checked out successfully from pull/3853/head as ref bug-test-fix (commit 7c7aff7).
• Code inspection confirms the fix matches the assessment's recommended approach verbatim, including the force=False default (safe for extension-install callers) and force=True only in the upgrade path.
• To obtain a real passing/failing verdict, rerun this workflow in an environment with PyPI access, or pre-install pytest>=7.0 and pytest-cov>=4.0 in the runner image. The focused test command would be: pytest tests/test_extension_skills.py::TestRegisterExtensionSkillsForceFlag -v

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 🧪 Test a Bug Fix from a Labeled Issue for issue #3849 · 1.2K AIC · ⌖ 11 AIC · ⊞ 36.8K · ◷