Validate Docs Against Source

---
name: validate-docs-against-source
description: Validates documentation content against official source repositories and documentation. Use when updating Copilot customization documentation, editing content about GitHub Copilot features, committing changes to docs, or when the user mentions verifying facts, checking sources, or validating accuracy.
metadata:
  author: customize-your-repo
  version: "1.2"
  spec-version: agentskills.io
---

# Validate Documentation Against Source

## When to Use This Skill

Use this skill when:
- User updates content in documentation files about GitHub Copilot
- User edits files describing Copilot primitives (instructions, prompts, agents, skills, MCP)
- User explicitly asks to verify facts or check accuracy
- User mentions "validate", "verify", "check source", or "fact-check"
- Content references file paths, settings, or configuration options
- **Before any commit** that includes changes to documentation files
- User is preparing a PR with documentation changes

## Pre-Commit Validation (Required)

**This skill MUST run before committing documentation changes.**

When the user attempts to commit changes to files in `docs/` or any `*.md` files that document Copilot features:

1. Automatically identify all claims that reference official features
2. Validate against primary sources
3. **If discrepancies are found:** Prompt the user before proceeding

### Pre-Commit Workflow

## Primary Sources

Always validate against these authoritative sources:

| Topic | Primary Source |
|-------|----------------|
| VS Code Copilot features | https://code.visualstudio.com/docs/copilot |
| Custom instructions | https://code.visualstudio.com/docs/copilot/customization/custom-instructions |
| Prompt files | https://code.visualstudio.com/docs/copilot/customization/prompt-files |
| Custom agents | https://code.visualstudio.com/docs/copilot/customization/custom-agents |
| Agent skills | https://code.visualstudio.com/docs/copilot/customization/agent-skills |
| MCP servers | https://code.visualstudio.com/docs/copilot/customization/mcp-servers |
| GitHub Copilot docs | https://docs.github.com/en/copilot |
| Repository instructions | https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot |
| Agent Skills spec | https://agentskills.io/specification |
| Source code (VS Code) | https://github.com/microsoft/vscode |
| Source code (Copilot Chat) | https://github.com/microsoft/vscode-copilot-chat |

## Version Tracking (Required)

**Always identify and report the version context for all validated content.**

### Determining Current GA Versions

Before validating, fetch current GA (Generally Available) versions:

| Product | Version Source | How to Check |
|---------|---------------|--------------|
| VS Code | https://code.visualstudio.com/updates | Look for "Version X.YZ" at top |
| Copilot Chat Extension | VS Code Marketplace or release tags | Check `microsoft/vscode-copilot-chat` releases |
| GitHub Copilot (web) | https://github.blog/changelog | Search for Copilot announcements |

### Version Status Categories

Mark each documented feature with its version status:

| Status | Meaning | Action |
|--------|---------|--------|
| 🟢 **GA** | Feature is in current stable release | Document normally |
| 🟡 **Preview** | Feature is in VS Code Insiders or preview | Add clear "Preview" label |
| 🔵 **Future** | Feature announced but not yet released | Add prominent warning |
| 🔴 **Deprecated** | Feature has been removed or replaced | Update or remove content |

### Version Callout Format

**Always include version context in validation reports:**

```markdown
## Version Context

**Validated against:**
- VS Code: {version} (GA/Insiders)
- Copilot Chat Extension: v{version}
- Documentation date: {date on docs page}

**Content references:**
- GA features: {count}
- Preview features: {count} ⚠️
- Future features: {count} ⚠️

⚠️ **FUTURE VERSION REFERENCE DETECTED**

The following content references features not yet generally available:

| Feature | Current Status | Expected GA |
|---------|---------------|-------------|
| {feature} | Insiders only | {if known} |
| {feature} | Announced | {if known} |

**This documentation describes upcoming functionality.**
Readers using the stable VS Code release may not have access to these features.

**Options:**
1. **Add version badge** - Mark section with "Available in VS Code Insiders" or "Coming soon"
2. **Move to future section** - Separate from GA content
3. **Remove for now** - Document only when GA
4. **Keep as-is** - Proceed with clear labeling (requires explicit confirmation)

⚠️ **Version Mismatch Detected**

Your documentation appears to reference **VS Code {doc_version}** features,
but the current GA release is **VS Code {ga_version}**.

| Feature | Documented As | Actually Available In |
|---------|--------------|----------------------|
| {feature} | GA | Insiders {version}+ |
| {setting} | Default: {value} | Default changed in {version} |

**How would you like to proceed?**

1. **Update to GA** - Adjust content to match current stable release
2. **Add version note** - Keep content but add "Requires VS Code {version}+"
3. **Split content** - Separate GA features from preview/future features
4. **Confirm as-is** - Document is intentionally forward-looking

docs: update always-on instructions for VS Code 1.109

- Verified against VS Code 1.109 GA release
- Added /init command (new in 1.108)
- Updated setting names per 1.107 changes

## Validation Report

**File:** {filename}
**Date:** {current date}

### Version Context
| Product | GA Version | Doc References |
|---------|------------|----------------|
| VS Code | {version} | {version if mentioned} |
| Copilot Chat | v{version} | {version if mentioned} |

**Version Status:** 🟢 All GA / 🟡 Contains Preview / 🔵 Contains Future

### Findings

| Claim | Status | Version | Notes |
|-------|--------|---------|-------|
| {claim 1} | ✅/⚠️/❌/❓/🔵 | GA/Preview/Future | {explanation} |
| {claim 2} | ✅/⚠️/❌/❓/🔵 | GA/Preview/Future | {explanation} |

### Version Warnings

{If any 🔵 Future items exist:}
⚠️ This documentation references {N} features not yet in GA release.
See "Future Version Warnings" section for details.

### Recommended Updates

1. {Update 1}
2. {Update 2}

⚠️ **Validation found {N} issue(s) in your documentation changes:**

| Issue | Claim | Problem |
|-------|-------|---------|
| 1 | "{claim}" | {what's wrong} |
| 2 | "{claim}" | {what's wrong} |

**How would you like to proceed?**

1. **Fix now** - Update the content to match official documentation
2. **Commit anyway** - Proceed with current content (not recommended)
3. **Review details** - Show full validation report with sources
4. **Cancel** - Abort the commit to investigate further

❓ **Unable to verify {N} claim(s) against official sources:**

- "{claim 1}" - No authoritative source found
- "{claim 2}" - Documentation page unavailable

**Options:**

1. **Add citation** - Mark these claims with [needs verification]
2. **Remove claims** - Delete unverifiable statements
3. **Proceed anyway** - Commit with unverified content
4. **Research more** - I'll search additional sources

⚠️ **{N} item(s) may be outdated:**

| Item | Current Doc Says | Your Content Says |
|------|------------------|-------------------|
| {setting/path} | {official value} | {your value} |

**This likely changed in a recent VS Code/Copilot update.**

1. **Update to current** - Apply the official values
2. **Keep as-is** - Your content may be intentionally different
3. **Show diff** - Compare full context from both sources

<!-- Validation: {date} -->
<!-- Decision: {user choice} -->
<!-- Reviewer: {user/auto} -->

🛑 **Critical accuracy issue detected**

The claim "{claim}" directly contradicts official documentation:
- **Your content:** {what you wrote}
- **Official docs:** {what docs say}
- **Source:** {url}

This could mislead readers. I recommend fixing before committing.

**Proceed anyway?** (type "yes" to override)