fix(codex): native skills fallback refresh + legacy prompt suppression by RbBtSn0w · Pull Request #1930 · github/spec-kit

RbBtSn0w · 2026-03-21T04:50:37Z

Background

This is a follow-up fix after the previous skills/frontmatter work was already merged.

In local debugging and re-init scenarios (specify init --here --ai codex --ai-skills), two issues were observed:

Older release assets can still contain legacy Codex prompt layout (.codex/prompts), which should not appear in skills mode.
For native-skills agents (Codex/Kimi), when bundled skills are not usable and fallback conversion is required, existing SKILL.md files were not refreshed due to additive-only behavior.

Why this change

The goal is to make Codex/Kimi skills-mode initialization resilient without broad behavioral changes:

Keep current default behavior for non-native flows.
Only adjust the native fallback path where stale/missing bundled skills cause functional issues.

What changed

Skip legacy Codex prompt directory in skills mode

In download_and_extract_template(...), add skip_legacy_codex_prompts.
When ai=codex and --ai-skills is enabled, do not materialize .codex from the downloaded archive.

Native fallback compatibility

For native-skills agents, if bundled skills are not detected, call install_ai_skills(...) as fallback instead of failing immediately.
Keep explicit failure if both bundled skills and fallback conversion are unavailable.

Minimal-impact overwrite policy

Add overwrite_existing: bool = False to install_ai_skills(...).
Preserve default additive behavior globally.
Enable overwrite only in native fallback branch (overwrite_existing=True) so fallback can refresh stale native SKILL.md files.

Why this is minimal impact

No global overwrite behavior change.
No behavior change for non-native agents.
Existing additive semantics remain the default API contract.
Scope is limited to Codex/Kimi fallback path and legacy Codex prompt suppression in skills mode.

Tests

Updated native-fallback tests to assert fallback invocation and overwrite flag usage.
Added coverage for overwrite-enabled replacement of existing SKILL.md.

Validation run:

uv run pytest tests/test_ai_skills.py -q -> 89 passed

Copilot

Pull request overview

This PR tightens Codex skills-mode initialization by avoiding legacy .codex prompt extraction and making native-skills agents (Codex/Kimi) attempt an install_ai_skills() fallback when bundled skills are missing, with updated tests and documentation to reflect the skills-based Codex layout.

Changes:

Add skip_legacy_codex_prompts support to template extraction and enable it for codex + --ai-skills.
For native-skills agents, attempt install_ai_skills() fallback when bundled skills are missing; keep a clear error when both bundled skills and fallback fail.
Update tests, docs, and release-package skill generators to align SKILL.md frontmatter.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`src/specify_cli/__init__.py`	Adds legacy `.codex` skip/removal during extraction and implements native-skills fallback behavior in `init`.
`tests/test_ai_skills.py`	Updates Codex native-skills tests to assert fallback is attempted and non-speckit skill dirs trigger fallback.
`src/specify_cli/agents.py`	Adds a technical-debt note documenting expected SKILL.md frontmatter schema alignment.
`AGENTS.md`	Updates Codex directory documentation to `.agents/skills/` and adjusts directory conventions section.
`.github/workflows/scripts/create-release-packages.sh`	Adds `compatibility` and `metadata` fields to generated SKILL.md frontmatter.
`.github/workflows/scripts/create-release-packages.ps1`	Mirrors the SKILL.md frontmatter additions for PowerShell packaging.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/__init__.py

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/__init__.py

tests/test_ai_skills.py

…raction

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tests/test_ai_skills.py

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/__init__.py

… dir

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/__init__.py

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…nc-main-2026-03-25 * upstream/main: (90 commits) fix(ps1): replace null-conditional operator for PowerShell 5.1 compatibility (github#1975) chore: bump version to 0.4.2 (github#1973) feat: Auto-register ai-skills for extensions whenever applicable (github#1840) docs: add manual testing guide for slash command validation (github#1955) Add AIDE, Extensify, and Presetify to community extensions (github#1961) docs: add community presets section to main README (github#1960) docs: move community extensions table to main README for discoverability (github#1959) docs(readme): consolidate Community Friends sections and fix ToC anchors (github#1958) fix(commands): rename NFR references to success criteria in analyze and clarify (github#1935) Add Community Friends section to README (github#1956) docs: add Community Friends section with Spec Kit Assistant VS Code extension (github#1944) chore: bump version to 0.4.1 (github#1953) Add checkpoint extension (github#1947) fix(scripts): prioritize .specify over git for repo root detection (github#1933) docs: add AIDE extension demo to community projects (github#1943) fix(templates): add missing Assumptions section to spec template (github#1939) chore: bump version to 0.4.0 (github#1937) fix(cli): add allow_unicode=True and encoding="utf-8" to YAML I/O (github#1936) fix(codex): native skills fallback refresh + legacy prompt suppression (github#1930) feat(cli): embed core pack in wheel for offline/air-gapped deployment (github#1803) ...

Copilot AI review requested due to automatic review settings March 21, 2026 04:50

Copilot started reviewing on behalf of RbBtSn0w March 21, 2026 04:51 View session

fix(codex): skip legacy prompts and fallback when bundled skills missing

3793b45

RbBtSn0w force-pushed the fix/skills-frontmatter-sync branch from 39e3690 to 3793b45 Compare March 21, 2026 04:53

RbBtSn0w requested a review from mnriem as a code owner March 21, 2026 04:53

Copilot AI reviewed Mar 21, 2026

View reviewed changes

src/specify_cli/__init__.py Outdated Show resolved Hide resolved

src/specify_cli/__init__.py Show resolved Hide resolved

fix(skills): allow native fallback to overwrite existing SKILL.md

94ec86e

RbBtSn0w changed the title ~~fix: codex ai-skills fallback + prevent legacy .codex prompts~~ fix(codex): native skills fallback refresh + legacy prompt suppression Mar 21, 2026

fix(codex): defer legacy .codex cleanup until after skills fallback

9736af9

Copilot AI review requested due to automatic review settings March 21, 2026 05:14

Copilot started reviewing on behalf of RbBtSn0w March 21, 2026 05:14 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

src/specify_cli/__init__.py Show resolved Hide resolved

src/specify_cli/__init__.py Outdated Show resolved Hide resolved

src/specify_cli/__init__.py Outdated Show resolved Hide resolved

tests/test_ai_skills.py Show resolved Hide resolved

RbBtSn0w added 2 commits March 21, 2026 13:18

fix(codex): preserve existing .codex while skipping legacy prompt ext…

979a30e

…raction

docs(skills): clarify overwrite_existing behavior

28b4801

Copilot AI review requested due to automatic review settings March 21, 2026 05:26

Copilot started reviewing on behalf of RbBtSn0w March 21, 2026 05:26 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

tests/test_ai_skills.py Show resolved Hide resolved

test(codex): cover fresh-dir suppression of legacy .codex layout

d98e275

RbBtSn0w requested a review from Copilot March 21, 2026 06:12

Copilot started reviewing on behalf of RbBtSn0w March 21, 2026 06:12 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

src/specify_cli/__init__.py Show resolved Hide resolved

This comment was marked as resolved.

Sign in to view

This comment was marked as outdated.

Sign in to view

docs(codex): clarify skip_legacy_codex_prompts suppresses full .codex…

9bec94d

… dir

RbBtSn0w requested a review from Copilot March 21, 2026 07:04

Copilot started reviewing on behalf of RbBtSn0w March 21, 2026 07:04 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

src/specify_cli/__init__.py Show resolved Hide resolved

src/specify_cli/__init__.py Show resolved Hide resolved

security(init): validate zip member paths before extraction

80cea01

RbBtSn0w requested a review from Copilot March 21, 2026 08:42

Copilot started reviewing on behalf of RbBtSn0w March 21, 2026 08:42 View session

RbBtSn0w mentioned this pull request Mar 21, 2026

[Bug]: Gemini and Codex --ai-skills on Windows 11 does not install skills #1915

Closed

Copilot AI reviewed Mar 21, 2026

View reviewed changes

mnriem merged commit 6223d10 into github:main Mar 23, 2026
11 of 12 checks passed

Conversation

RbBtSn0w commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Why this change

What changed

Why this is minimal impact

Tests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

RbBtSn0w commented Mar 21, 2026 •

edited

Loading