Add independent skill version metadata to Dev Proxy SKILL frontmatter

[Copilot]

Adds explicit version metadata to the skills/dev-proxy entrypoint so consumers can compare local vs source skill versions and decide when to refresh their local copy.

• Frontmatter update

  • Added version: 1.0.0 to skills/dev-proxy/SKILL.md YAML frontmatter, alongside existing name and description fields.
  • No other skill content or references were changed.

• Resulting metadata shape

---
name: dev-proxy
version: 1.0.0
description: "Simulate API failures, mock responses, test rate limiting, and analyze API traffic..."
---

Original prompt

Add a version field to the YAML frontmatter in skills/dev-proxy/SKILL.md to enable independent versioning of the skill.

The frontmatter currently has name and description fields. Add version: 1.0.0 as the initial version.

The updated frontmatter should look like:

---
name: dev-proxy
version: 1.0.0
description: "Simulate API failures, mock responses, test rate limiting, and analyze API traffic..."
---

This version field will be used by consumers to check whether their local copy of the skill is current, and decide whether to pull the latest version from the source repo.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: In the repo we have an agent skill @dotnet/dev-proxy/files/skills/dev-proxy

How should we best approach versioning of the skill and it's contents.

Assistant: Here's my recommendation for versioning the dev-proxy skill:

Approach: Tie Skill Version to Dev Proxy Version

Since the skill content (schemas, plugin references, config examples) is tightly coupled to the Dev Proxy product version, the most practical approach is to version the skill in lockstep with Dev Proxy releases rather than independently.

1. Add a version field to the SKILL.md frontmatter

The SKILL.md already uses YAML frontmatter (name, description). Add a version field:

---
name: dev-proxy
version: 2.4.0
description: "Simulate API failures..."
---

This makes the skill version machine-readable and immediately visible.

2. Keep schema URLs as the source of truth for compatibility

Your reference files already embed versioned schema URLs like:

https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v2.4.0/rc.schema.json

When Dev Proxy releases a new version, the skill content (schema URLs, plugin names, config structures) needs to be updated to match. This is already your natural trigger for updating the skill.

3. Update the skill as part of the existing release process

You already follow semver for Dev Proxy and have an upgrade-devproxy-version skill for version bumps. Extend that process to also update:

• The version field in SKILL.md
• Schema URLs in all reference files under skills/dev-proxy/references/
• Any plugin names, config properties, or CLI flags that changed

This keeps everything in sync without a separate versioning workflow.

4. Use the repo's existing Git tags for history

Since the skill lives in the same repo as the product, every Dev Proxy release tag (e.g., v2.5.0) already captures a snapshot of the skill at that point. No need for separate skill tags.

5. Consider a lightweight changelog in the skill folder

A simple skills/dev-proxy/CHANGELOG.md noting what changed per version would help consumers understand when the skill content was last updated:

## 2.4.0
- Initial skill release
- Covers: mocking, resilience testing, LLM testing, API analysis, CI/CD, configuration

## 2.5.0 (future)
- Added new plugin X reference
- Updated schema URLs to v2.5.0

Summary

Concern	Recommendation
Version identifier	version field in SKILL.md frontmatter, matching Dev Proxy version
When to bump	Every Dev Proxy release that changes plugins, schemas, or CLI
How to bump	Include in the existing upgrade-devproxy-version workflow
History tracking	Git tags (already exist) + optional CHANGELOG.md
Independent patches	Use patch version if skill-only fixes are needed between releases (e.g., 2.4.1)

This keeps things simple, avoids version drift, and leverages your existing release infrastructure.

User: Ok first of all, we don't want to tie the version to Dev Proxy as we want to be able to release the skill independently of the main Dev Proxy package.

Assistant: That makes sense. Here's a revised approach for independent skill versioning:

Independent Skill Versioning

1. Add a version field to SKILL.md frontmatter

Start at 1.0.0 with its own semver lifecycle:

---
name: dev-proxy
version: 1.0.0
description: "Simulate API failures..."
---

Bump independently based on skill content changes, not Dev Proxy releases.

2. Define what triggers each version bump

Bump	When
Major	Structural changes to SKILL.md (e.g., renamed/removed reference files, changed agent interaction patterns)
Minor	New reference files, new plugin coverage, new scenarios added
Patch	Fixes to instructions, typos, clarifications, schema URL updates

3. Track Dev Proxy compatibility separately

Add a compatibility field in the frontmatter so consumers know which Dev Proxy versions the skill supports:

---
name: dev-proxy
version: 1.2.0
dev-proxy: ">=2.4.0"
description: "Simulate API failures..."
---

This decouples the two version numbers while keeping the relationship explicit.

4. Add a CHANGELOG.md in t...

This pull request was created from Copilot chat.

[Copilot]

Pull request overview

Adds explicit, machine-readable version metadata to the dev-proxy skill entrypoint frontmatter so downstream consumers can detect updates independently of the main Dev Proxy product version.

Changes:

• Added version: 1.0.0 to the YAML frontmatter in skills/dev-proxy/SKILL.md.

[garrytrinder]

Issue with CodeQL build, closing and re-raised #1652