kit-copilot-create-skill

name	kit-copilot-create-skill
description	Scaffolds a new Agent Skill directory and SKILL.md file following the Agent Skills open standard. Use when a user asks to create, scaffold, or set up a new skill or reusable capability for GitHub Copilot.
argument-hint	Skill name, purpose, and any specific capabilities or resources it should include
user-invocable	false
disable-model-invocation	false

Create a New Agent Skill

What This Skill Does

Creates a properly structured Agent Skill directory containing a SKILL.md file and optional resources (scripts, templates, examples). Follows the Agent Skills specification and VS Code docs for Copilot's skills development.

An Agent Skill is a reusable capability — a multi-step procedure with optional bundled resources that the AI agent follows to complete a specific type of task. Skills are portable across VS Code, Copilot CLI, and Copilot coding agent.

Key Concepts: Skill vs Agent vs Prompt vs Instructions

Understanding the separation of concerns is critical for creating effective skills. Each customization mechanism has a distinct purpose:

Component	Defines	Analogy	File Type
Agent Skill	Reusable CAPABILITY or multi-step workflow	A specialized training module the employee can use	SKILL.md in a skill directory
Custom Agent	WHO the AI is and HOW it behaves	The employee's role, personality, and work style	.agent.md
Prompt File	WHAT specific task to perform	A work order or task assignment	.prompt.md
Custom Instructions	WHERE — project context and standards	The company handbook	.instructions.md

- Multi-step procedures the agent follows methodically (Interview → Scan → Draft → Generate → Validate) - Reusable workflows with bundled scripts, templates, or examples - Domain-specific knowledge that loads on-demand via progressive disclosure - Convention detection and adaptation to project patterns - Tasks requiring workspace scanning before execution - Capabilities that should work across VS Code, CLI, and coding agent (portability) - AI persona definitions (philosophy, behavioral traits) → custom agents (`.agent.md`) - Simple one-shot task templates with no bundled resources → prompt files (`.prompt.md`) - Project coding standards and conventions → custom instructions (`.instructions.md`) - Generic AI advice the model already knows ("write clean code", "handle errors") - Tool API documentation — focus on WHEN to use tools, not their internal parameters If during the interview the user's needs don't match a skill, recommend the right mechanism:

• The workflow is a simple one-shot task with no bundled resources → recommend a prompt file instead
• The user is defining a persona or role rather than a procedure → recommend a custom agent instead
• The user only needs project-wide coding standards → recommend custom instructions instead
• The user needs guaranteed deterministic automation (format on save, block commands) → recommend a hook instead

Step-by-step Procedure

Step 1: Interview

Before creating anything, gather requirements from the user. Use #tool:vscode/askQuestions if available to ask all clarifying questions in a single structured prompt. Otherwise, ask in chat.

Problem Reframing (How Might We): Before diving into questions, reframe the user's raw request as an opportunity question: "How might we help the agent automate [specific task] so that the user gets [consistent, quality outcome] with [minimal input]?" This shifts focus from "what files to create" to "what problem to solve" — leading to better skill scope and design.

1. **Task**: What repetitive task do you want to automate? (e.g., writing tests, planning sprints, scaffolding components) 2. **Complexity**: How many steps does the workflow have? Does it need scripts, templates, or examples? (If it's a simple one-shot task with no resources, a prompt file may be more appropriate — see escalation criteria above.) 3. **Name**: What should the skill be called? (suggest a kebab-case name if the user doesn't have one) 4. **Invocation**: Should it be user-invocable from chat surfaces, or only trigger automatically? (determines `user-invocable` and `disable-model-invocation`) 5. **Triggers**: What phrases would a user say that should trigger this skill? (feeds into the description's "Use when" clause) 6. **Resources**: Does the skill need bundled resources — scripts, templates, examples?

Do NOT proceed to workspace scanning until you have clear answers to at least questions 1, 3, and 5. Use question 2 to validate that a skill (not a prompt) is the right mechanism.

Steel Manning for Escalation: If question 2 suggests a different mechanism (e.g., prompt file), don't immediately redirect. First, present the strongest case FOR keeping it as a skill: "The strongest argument for making this a skill is [X]." Then present the counter: "However, [Y] suggests a prompt is better because [Z]." This produces well-justified decisions and catches cases where the first instinct was wrong.

Step 2: Workspace Scan

Before drafting, scan the workspace for context.

1. **Check existing skills** — Search `.github/skills/` for existing `SKILL.md` files to avoid naming conflicts and maintain consistency with established patterns. 2. **Check naming conventions** — Look for `.github/instructions/` files that target skills (e.g., `skill-naming.instructions.md`). Apply any naming conventions found (like `kit-{category}-{verb}-{object}` patterns). 3. **Check existing prompts** — Search `.github/prompts/` for `.prompt.md` files that might already cover the same task. 4. **Check existing agents** — Search `.github/agents/` for `.agent.md` files that might already embed this capability. 5. **Check project instructions** — Read `copilot-instructions.md` and relevant `.instructions.md` files for project context the new skill should respect.

Report any findings to the user: "I found X existing skills. Your new skill complements/overlaps with [specific skill]."

Step 3: Draft

Using the interview answers and workspace scan:

Frontmatter:

• Derive the name in strict kebab-case (lowercase, hyphens only, max 64 chars). If the workspace uses a naming convention (e.g., kit-{category}-{verb}-{object}), follow it.
• Draft a description that follows the required [What it does]. Use when [trigger scenarios]. pattern, explicitly listing the trigger phrases from question 5
• Determine the directory location (.github/skills/{skill-name}/ or .github/skills/{category}/{skill-name}/)

Body:

• Plan the body structure using the Skill Body Structure Guide below
• Determine which XML tags are appropriate for the skill's content
• Identify any bundled resources to include (templates, examples, scripts)

Skill Design Analysis

Before presenting the draft to the user, run these four named analysis techniques. Use Sequential Thinking MCP (sequential-thinking/*) for complex skills where boundaries or requirements are unclear.

1. Requirements MECE Check — Decompose the skill's scope into five non-overlapping partitions. Verify nothing is missing and nothing overlaps:

Partition	Question to answer
Input	What triggers this skill? What arguments does it accept?
Procedure	What steps does the agent follow? What decisions does it make?
Output	What files, messages, or artifacts does it produce?
Boundaries	What does this skill explicitly NOT do? What does it delegate?
Error handling	What failure paths exist? How does the skill recover?

2. Scope Boundary Test — For the specific skill being designed, dynamically evaluate its borders against adjacent mechanisms. Ask: "Where does this skill's responsibility end? Does any step bleed into agent persona territory? Instruction territory? Prompt territory?" This is the dynamic version of the static <belongs-in-skill> / <does-not-belong-in-skill> analysis — applied to this particular skill's content.

3. Assumption Audit — List exactly 4 assumptions the skill design makes, one per dimension. For each, ask: "What if this is wrong? Does the skill still work, or does it fail silently?"

Dimension	What to audit
Workspace state	Project structure, existing files, directory layout
Agent capabilities	Tool access, MCP servers, file creation permissions
User expertise	Beginner vs. expert, familiarity with Copilot customization
Triggering context	How users will invoke the skill (auto vs. manual), typical phrasing

4. Skill Pre-Mortem — Imagine the skill has been deployed and an agent produced poor results using it. Check each of these five failure modes against the draft:

Failure Mode	What to verify in the draft
Description too vague → skill never auto-triggers	Description has specific verb + multiple trigger phrases
Steps too vague → agent improvises badly	Each step specifies what to do, check, and produce
Missing validation → poor output goes uncaught	Validation checklist covers structural + content quality
Scope too broad → skill does everything, does nothing well	Boundaries are explicit, escalation criteria defined
Missing edge cases → common scenarios fail	Empty/minimal/maximal/conflicting inputs handled

If any row fails, revise the draft before presenting to the user.

Present the draft frontmatter and body outline to the user for confirmation before generating.

Step 4: Generate

Once confirmed:

1. Create the directory named exactly as the skill name. 2. Create `SKILL.md` inside it using the bundled [skill-template.md](./skill-template.md) as the structural starting point: - Write valid YAML frontmatter (use quoted strings for `description`, never `>-`) - Write the body instructions using clear numbered steps (Step 1, Step 2, Step 3...) so the agent can follow them methodically - Use XML-like semantic tags per the repository's tag conventions: ``, ``, ``, `