docs: document copilot skills mode (--skills) and markdown deprecation by Quratulain-bilal · Pull Request #3313 · github/spec-kit

Quratulain-bilal · 2026-07-02T20:11:16Z

fixes #3300

as suggested by @mnriem on the issue.

what

the copilot skills mode (added in #3256, v0.12.3) wasn't documented in docs/reference/integrations.md:

the copilot row in the supported-agents table had an empty notes cell, while other skills-capable agents (codex, kimi, devin, ...) describe their skills behavior there.
--skills was missing from the integration-specific options table — only generic and kimi were listed.

how

fill the copilot notes cell: installs .agent.md by default; --integration-options "--skills" scaffolds speckit-<name>/SKILL.md under .github/skills/; the markdown default is deprecated.
add a copilot / --skills row to the integration-specific options table.

verified against the code

CopilotIntegration.options() in src/specify_cli/integrations/copilot/__init__.py defines --skills as a flag with help "Scaffold commands as agent skills (speckit-/SKILL.md) instead of .agent.md files".
dispatch_command uses .github/skills/, speckit-<stem>/SKILL.md, and invokes /speckit-<stem> in skills mode; --agent speckit.<stem> otherwise.
_warn_legacy_markdown_default() emits the deprecation warning when installing without --skills.

docs-only change.

note: i used an ai assistant to help investigate and write this up.

as of github#3256 (v0.12.3) the copilot integration supports a skills mode via `--integration-options "--skills"`, and installing without it warns that the legacy markdown default is being phased out. this was undocumented: - the copilot row in the supported-agents table had an empty notes cell while other skills-capable agents describe their behavior there. - `--skills` was missing from the integration-specific options table (only generic and kimi were listed). fill both. wording matches the code: skills scaffold as speckit-<name>/SKILL.md under .github/skills/ and are invoked as /speckit-<name>; without the flag the install emits the deprecation warning from _warn_legacy_markdown_default(). fixes github#3300

Copilot

Pull request overview

Updates the integration reference documentation to cover GitHub Copilot’s --skills mode (introduced in v0.12.3) and to note the deprecation warning for Copilot’s legacy markdown-based default scaffold.

Changes:

Adds a detailed Notes entry for the GitHub Copilot row in the supported agents table, including --integration-options "--skills" behavior and deprecation messaging.
Adds a copilot / --skills entry to the Integration-Specific Options table.

Show a summary per file

File	Description
docs/reference/integrations.md	Documents Copilot skills mode usage and adds the missing integration-specific option entry.

Review details

Tip

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

Files reviewed: 1/1 changed files
Comments generated: 2
Review effort level: Low

mnriem

Please address Copilot feedback. If not applicable, please explain why

…prompt.md) the copilot rows said the default installs .agent.md files, but the default scaffold also writes companion .prompt.md files under .github/prompts/. also reworded to 'legacy markdown mode' to match the deprecation warning users actually see and to avoid ambiguity, since skills are markdown too.

Quratulain-bilal · 2026-07-06T23:59:56Z

both correct. pushed 43f23af: both copilot rows now say the default is legacy markdown mode and spell out the .agent.md + companion .prompt.md (.github/prompts/) layout, and use the 'legacy markdown mode' wording that matches the deprecation warning users see instead of the ambiguous 'markdown default'.

Copilot

Review details

Files reviewed: 1/1 changed files
Comments generated: 2
Review effort level: Low

mnriem · 2026-07-08T12:43:53Z

Please address Copilot feedback

…pilot rows address the follow-up copilot review: name where the default scaffold writes files (.github/agents/*.agent.md plus .github/prompts/*.prompt.md and a .vscode/settings.json merge), and switch speckit-<name> to speckit-<command> to match the rest of the table. verified all three paths against the copilot integration source.

Quratulain-bilal · 2026-07-08T13:17:56Z

addressed in 37414d1. both copilot rows now spell out the legacy markdown layout (.github/agents/.agent.md plus .github/prompts/.prompt.md and the .vscode/settings.json merge) and use speckit- to match the rest of the table. verified each path against the copilot integration source (folder .github/, agents dir .github/agents, prompts .github/prompts, and the settings.json write).

Copilot

Review details

Files reviewed: 1/1 changed files
Comments generated: 1
Review effort level: Low

 | [Forge](https://forgecode.dev/)                                                      | `forge`          |                                                                                                                                           |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli)                            | `gemini`         |                                                                                                                                           |
-| [GitHub Copilot](https://code.visualstudio.com/)                                     | `copilot`        |                                                                                                                                           |
+| [GitHub Copilot](https://code.visualstudio.com/)                                     | `copilot`        | Defaults to legacy markdown mode: `.agent.md` command files under `.github/agents/`, companion `.prompt.md` files under `.github/prompts/`, and a `.vscode/settings.json` merge. Pass `--integration-options "--skills"` to scaffold skills as `speckit-<command>/SKILL.md` under `.github/skills/` instead. Legacy markdown mode is deprecated and will stop being the default in a future release. |


mnriem · 2026-07-10T12:06:16Z

Please address Copilot feedback

match the equals form the rest of the doc uses (generic row, the options table, and the install example) so readers don't mistake the quotes for part of the value. addresses copilot review feedback.

Quratulain-bilal · 2026-07-10T15:00:04Z

addressed in b3935ca. the copilot notes cell now uses --integration-options="--skills" (equals form), matching the generic row, the options table, and the install example elsewhere in this doc so the quotes aren't read as part of the value.

Quratulain-bilal requested a review from mnriem as a code owner July 2, 2026 20:11

mnriem requested a review from Copilot July 6, 2026 13:26

Copilot started reviewing on behalf of mnriem July 6, 2026 13:26 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread docs/reference/integrations.md Outdated

Comment thread docs/reference/integrations.md Outdated

mnriem requested changes Jul 6, 2026

View reviewed changes

mnriem requested a review from Copilot July 7, 2026 18:12

Copilot started reviewing on behalf of mnriem July 7, 2026 18:23 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread docs/reference/integrations.md Outdated

Comment thread docs/reference/integrations.md Outdated

mnriem requested a review from Copilot July 9, 2026 13:11

Copilot started reviewing on behalf of mnriem July 9, 2026 13:21 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

docs: use --integration-options="..." form in copilot notes cell

b3935ca

match the equals form the rest of the doc uses (generic row, the options table, and the install example) so readers don't mistake the quotes for part of the value. addresses copilot review feedback.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: document copilot skills mode (--skills) and markdown deprecation#3313

docs: document copilot skills mode (--skills) and markdown deprecation#3313
Quratulain-bilal wants to merge 4 commits into
github:mainfrom
Quratulain-bilal:docs/copilot-skills-mode

Quratulain-bilal commented Jul 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Uh oh!

Quratulain-bilal commented Jul 6, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jul 8, 2026

Uh oh!

Quratulain-bilal commented Jul 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem commented Jul 10, 2026

Uh oh!

Quratulain-bilal commented Jul 10, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Quratulain-bilal commented Jul 2, 2026

what

how

verified against the code

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Quratulain-bilal commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jul 8, 2026

Uh oh!

Quratulain-bilal commented Jul 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

mnriem commented Jul 10, 2026

Uh oh!

Quratulain-bilal commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Quratulain-bilal commented Jul 6, 2026 •

edited

Loading

Quratulain-bilal commented Jul 10, 2026 •

edited

Loading