skill-creator

# Skill Creator for GitHub Copilot Create and maintain skills in `.github/skills/` that extend GitHub Copilot's capabilities with project-specific knowledge. ## What Are Skills Skills are SKILL.md files that provide specialized, procedural knowledge that Copilot doesn't inherently have. They turn Copilot from a general assistant into a domain expert for specific tasks in this codebase. Skills provide: - **Specialized workflows** — multi-step procedures for project-specific domains - **Domain expertise** — architecture patterns, conventions, business logic - **Bundled references** — detailed docs loaded only when needed ## Skill Anatomy ``` .github/skills/ └── skill-name/ ├── SKILL.md (required — frontmatter + instructions) └── references/ (optional — detailed docs, loaded on demand) ``` ### SKILL.md Structure ```markdown --- name: my-skill-name description: What this skill does and WHEN to use it. Include trigger words and scenarios. This is the primary mechanism for Copilot to decide whether to load the skill body. --- # Skill Title Concise instructions for using this skill. ## When to Use - Bullet list of triggering scenarios ## Core Content (workflow, patterns, examples) ``` ### Wiring the Skill After creating the SKILL.md, register it in [.github/copilot-instructions.md](/.github/copilot-instructions.md) under the `<skills>` section: ```xml <skill> <name>my-skill-name</name> <description>Same or similar description as in SKILL.md frontmatter</description> <file>${workspaceFolder}\.github\skills\my-skill-name\SKILL.md</file> </skill> ``` > **Note:** Replace `${workspaceFolder}` with the absolute path to the repository root on your machine (e.g. `\home\user\repos\vscode-documentdb`). VS Code resolves skill file paths at runtime and currently requires absolute paths. Copilot reads skill metadata (name + description) to decide when to trigger. The SKILL.md body is loaded only after triggering. ## Core Principles ### 1. Concise is Key The context window is shared with conversation history, other instructions, and user requests. Challenge each paragraph: "Does Copilot already know this?" and "Does this justify its token cost?" - **Prefer concise examples over verbose explanations** - **Only include what Copilot doesn't already know** — skip general TypeScript/React knowledge - **Target under 300 lines** for SKILL.md body; split into references if larger ### 2. Progressive Disclosure Use a three-level loading system: 1. **Metadata** (name + description) — always visible (~50 words) 2. **SKILL.md body** — loaded when skill triggers 3. **References** — loaded on demand by Copilot when deeper detail is needed For skills with multiple variants or extensive reference material, keep the core workflow in SKILL.md and move details to `references/`: ```markdown ## Advanced Topics - **Detailed format spec**: See [FORMAT.md](./FORMAT.md) - **Migration patterns**: See [references/migration.md](./references/migration.md) ``` ### 3. Match Freedom to Task Fragility | Freedom Level | When | Example | | ----------------------------------- | ------------------------- | ---------------------------- | | **High** (text guidance) | Multiple valid approaches | Architecture recommendations | | **Medium** (patterns with examples) | Preferred pattern exists | tRPC router creation | | **Low** (exact steps) | Fragile, error-prone | Release note formatting | ### 4. Do NOT Include - README.md, CHANGELOG.md, or auxiliary documentation - Setup/installation instructions for the skill itself - User-facing documentation — skills are for Copilot, not humans - Information Copilot already knows (general language features, common libraries) ## Skill Creation Workflow ### Step 1: Understand the Domain Identify concrete scenarios the skill addresses: - What tasks trigger it? - What does Copilot get wrong without it? - What project-specific knowledge is needed? ### Step 2: Plan Contents For each scenario, determine: - What code patterns or templates are repeatedly needed? - What reference material should be available? - What pitfalls must be called out? ### Step 3: Write the Skill 1. **Create** `.github/skills/{skill-name}/SKILL.md` 2. **Write frontmatter**: `name` and `description` (description is the trigger — be comprehensive about when to use) 3. **Write body**: Core workflow, patterns, examples. Keep it lean. 4. **Add references** (optional): Split out detailed format specs, schemas, or variant-specific docs 5. **Register** in `.github/copilot-instructions.md` ### Step 4: Validate - Ensure the description covers all trigger scenarios - Verify code examples follow project conventions (see `.github/copilot-instructions.md` and `.github/instructions/`) - Check that referenced files exist and paths are correct - Confirm the skill doesn't duplicate information already in `.github/instructions/` files ## Existing Skills Reference | Skill | Purpose | | --------------------------- | ------------------------------------------------------ | | `writing-release-notes` | Release notes and changelog generation | | `accessibility-aria-expert` | Accessibility issues in React/Fluent UI webviews | | `webview-trpc-messaging` | tRPC communication between extension host and webviews | ## Example: Minimal Skill ```markdown --- name: my-pattern description: Implements the XYZ pattern for this codebase. Use when creating new XYZ instances, modifying existing XYZ behavior, or debugging XYZ-related issues. --- # XYZ Pattern ## When to Use - Creating a new XYZ - Modifying XYZ behavior - Debugging XYZ issues ## Pattern \`\`\`typescript // core pattern example \`\`\` ## Common Pitfalls - Don't do X because Y - Always do Z when W ```