Skill Manager for Copilot — User Guide

You are helping a developer who uses the Skill Manager for Copilot VS Code extension. This skill teaches you how the extension works so you can guide them effectively.

What is a Skill?

A skill is a Markdown file (SKILL.md) that gives you (the AI agent) domain-specific knowledge. Skills are organized in Git repositories and synced to the developer's local workspace via this extension.

Extension Commands

Command	What it does
Skills: Add Repository	Adds a Git repo URL as a skill source
Skills: Add Official Repository	Adds the curated official skill repo
Skills: Remove Repository	Removes a previously added repo
Skills: Pull All	Syncs all skills from all configured repos
Skills: Pull Repo	Syncs skills from a specific repo
Skills: Push Feedback	Sends local feedback to the repo via branch + PR
Skills: Status	Shows sync status of all skills
Skills: Enable Skill	Re-enables a disabled skill (including workspace-disabled)
Skills: Disable Skill	Disables a skill without deleting it
Skills: Enable Agent	Re-enables a disabled agent (including workspace-disabled)
Skills: Disable Agent	Disables an agent without deleting it
Skills: Move Agent to Workspace	Moves an agent from global to the current workspace
Skills: Move Agent to Global	Moves an agent from workspace back to global
Skills: Browse Catalog	Opens the skill catalog in the browser

How Sync Works

1. The extension clones configured repos to a local cache.
2. On Pull, it copies skills from <repo>/skills/<name>/ to the workspace's .github/skills/ directory.
3. Each synced skill gets a .manifest.json tracking its origin and hash.
4. If the local copy hasn't been edited, it auto-updates on next pull.
5. If the local copy was edited, the conflict strategy kicks in (configurable).

Configuration

Users configure the extension in VS Code settings (skillManager.*):

{
  // List of skill repositories
  "skillManager.repos": [
    { "name": "Official", "url": "https://github.com/AllanSantos-DV/skill-kit.git", "priority": 1 },
    { "name": "Team", "url": "https://github.com/my-org/team-skills.git", "priority": 2 }
  ],

  // Auto-sync interval in minutes (0 = disabled)
  "skillManager.syncIntervalMinutes": 30,

  // What to do when same skill exists in multiple repos
  // "highest-priority" | "ask" | "keep-local"
  "skillManager.conflictStrategy": "highest-priority",

  // What to do when local skill was edited and repo has update
  // "keep-local" | "overwrite" | "ask"
  "skillManager.localEditStrategy": "ask"
}

Skill Structure

Every skill lives in a folder under skills/ in the repo:

skills/
  my-skill/
    SKILL.md            ← Required: the skill content (you read this)
    FEEDBACK.md         ← Optional: feedback protocol for this skill
    references/         ← Optional: extra docs loaded on-demand
      api-reference.md
      examples.md

SKILL.md Frontmatter

---
name: my-skill
description: What this skill teaches
---

Supported attributes: name, description, argument-hint, compatibility, disable-model-invocation, license, metadata, user-invocable.

Version Convention

• Patch (1.0.0 → 1.0.1): typos, clarifications
• Minor (1.0.1 → 1.1.0): new scenarios, improvements
• Major (1.1.0 → 2.0.0): fundamental rewrites

Feedback Flow

If a skill has FEEDBACK.md, users can submit improvements:

1. Developer writes feedback in the local skill directory
2. Skills: Push Feedback creates a branch and pushes
3. A PR is created on the skill repo for the maintainer to review

Sidebar & Status

• The Skill Manager sidebar shows all skills grouped by repo
• Icons indicate state: ✓ synced, ↑ local-only, ⊘ disabled
• The status bar shows overall sync state: synced, divergent, error, or syncing
• Skills with benchmark reports show a 📊 icon; reports are centralized in ~/.copilot/skill-benchmarks/

Scoped Disable & Remove (Skills and Agents)

When disabling or removing a global skill or agent, the extension prompts "Global or this workspace?":

• Global — disables/removes for all workspaces. Persisted in placements.json (survives .excluded.json cleanup).
• This workspace — disables only in the current workspace. The item remains visible in other workspaces.

Re-enabling a workspace-disabled item (via Enable Skill or Enable Agent) reactivates it by removing the workspace entry from placements.json.

Moving Agents Between Scopes

Just like skills, agents can be moved between global and workspace scope:

• Move to Workspace — copies the agent file to .github/agents/ in the current workspace and removes from global. Tracked in placements.json.
• Move to Global — copies the agent file back to ~/.copilot/agents/ and removes from workspace. Tracked in placements.json.

On next Pull, the sync respects these decisions — an agent moved to a workspace is not reinstalled globally.

Benchmark Reports

Benchmark reports are centralized in ~/.copilot/skill-benchmarks/. When pulling from a repo that contains benchmarks (under skill-benchmarks/), results are:

1. Copied to the global benchmarks directory
2. Registered in placements.json for quick lookup
3. Accessible from the sidebar via the 📊 icon or the benchmark command

When the User Asks for Help

• "How do I add a skill repo?" → Ctrl+Shift+P → Skills: Add Repository → paste the Git URL
• "My skills aren't updating" → Run Skills: Pull All, check status bar for errors
• "How do I disable a skill?" → Right-click the skill in sidebar → Disable Skill
• "How do I create my own skill?" → Create a folder under skills/ with a SKILL.md containing frontmatter + content
• "How do I submit improvements?" → Edit the local skill, then Skills: Push Feedback