Skip to content

[Bug]: Copilot skills mode generates unsupported mode frontmatter in SKILL.md #2799

@lselvar

Description

@lselvar

Bug Description

Title

Copilot skills mode generates unsupported mode frontmatter in SKILL.md

Summary

When initializing spec-kit with the Copilot integration in skills mode, generated SKILL.md files include a mode: frontmatter attribute.

Example:

---
name: "speckit-plan"
description: "Create an implementation plan using the plan template to generate design artifacts."
compatibility: "Requires spec-kit project structure with .specify/ directory"
metadata:
  author: "github-spec-kit"
  source: "templates/commands/plan.md"
mode: speckit.plan


The VS Code GitHub Copilot plugin does not appear to support mode as a valid SKILL.md frontmatter field. Current VS Code/Copilot Agent Skills docs describe skill discovery via name and description, plus supported fields like user-invocable and disable-model-invocation, but not mode.

### Steps to Reproduce

1. Run the command - specify init --here --integration copilot --integration-options "--skills"
2. Inspect a generated skill: cat .github/skills/speckit-plan/SKILL.md







### Expected Behavior

Generated Copilot skills should only include frontmatter fields supported by VS Code Copilot Agent Skills, or mode: should be configurable/opt-in if it is intended for another Copilot surface.

### Actual Behavior

Generated Copilot skills include:
mode: speckit.plan

### Specify CLI Version

0.8.18

### AI Agent

GitHub Copilot

### Operating System

macOS

### Python Version

3.13

### Error Logs

```shell
VS Code Copilot plugin does not execute Skill calls with mode frontmatter. After removing it, it works.

Additional Context

Why This Matters

The generated skills are intended for VS Code Copilot, but the VS Code plugin does not support the mode attribute in SKILL.md. This can make the generated files appear invalid or unsupported, depending on how strictly the plugin validates skill frontmatter.

Suspected Source

The field appears to be injected here:

src/specify_cli/integrations/copilot/init.py CopilotIntegration.post_process_skill_content()
The method explicitly inserts:

mode: {skill_name}
for generated Copilot skills.

Suggested Fix

Remove the mode: injection from Copilot skills mode, or make it opt-in via an integration option, for example:

--integration-options "--skills --include-mode-frontmatter"
Default behavior should match the current VS Code Copilot Agent Skills schema.

References

VS Code Agent Skills docs: https://code.visualstudio.com/docs/copilot/customization/agent-skills
GitHub Copilot CLI skills reference: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference
Agent Skills specification: https://agentskills.io/specification

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions