jaktestowac/awesome-copilot-for-testers / plugins/creating-instructions/skills/creating-instructions
creating-instructions
VerifiedCreates GitHub Copilot instruction files for VS Code, including repository guidance and scoped `.instructions.md` rules. Use when encoding project conventions, choosing `applyTo` patterns, or shipping install-ready instruction examples with rationale and guardrails.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.8 KB |
| resources/copilot-instructions.example.md | markdown | 2.6 KB |
| resources/copilot-instructions.template.md | markdown | 1.7 KB |
| resources/custom-instructions.example.instructions.md | markdown | 1.5 KB |
| resources/custom-instructions.template.instructions.md | markdown | 849 B |
| resources/instructions-quality-checklist.md | markdown | 1.7 KB |
SKILL.md
View on GitHub---
name: creating-instructions
description: "Creates GitHub Copilot instruction files for VS Code, including repository guidance and scoped `.instructions.md` rules. Use when encoding project conventions, choosing `applyTo` patterns, or shipping install-ready instruction examples with rationale and guardrails."
argument-hint: "Repository context, target scope, sample files, and rules to encode"
user-invocable: true
---
# Creating Copilot Instructions
Use this skill when the goal is to package stable rules for GitHub Copilot instead of writing one-off guidance in chat.
It helps turn repository conventions into clean instruction files that are easy to install, reason about, and maintain.
## When to Use
Use this skill when the user asks for things like:
- "create a repo-wide Copilot instruction file"
- "write a `.instructions.md` file for these tests"
- "choose the right `applyTo` pattern"
- "turn our coding rules into installable instructions"
- "fix an instruction file that is too broad or too vague"
Typical scenarios:
- first-time setup of `copilot-instructions.md`
- adding targeted guidance for a folder, language, or test type
- splitting an overgrown instruction file into smaller units
- preparing public examples for a team repository or a shared collection
## What Good Looks Like
A strong instruction contribution usually includes:
- the right instruction type for the job: repo-wide or scoped
- a narrow, predictable scope
- short declarative rules with a reason when the rule is not obvious
- examples only where they materially improve compliance
- no workflow logic, no agent personality, and no prompt-specific scripting
## Instruction Design Rules
- **Rules over essays** - prefer short, stable guidance that survives multiple tasks.
- **Scope first** - the `applyTo` pattern is part of the design, not an afterthought.
- **Reason when needed** - if a rule is surprising, explain the consequence in the same bullet.
- **Examples beat abstraction** - include a preferred and avoided example for tricky patterns.
- **Context is expensive** - avoid loading broad instructions that repeat what tools already enforce.
## Workflow
### Phase 0: Frame the request
Clarify or infer:
- whether the user needs repo-wide guidance or scoped instructions
- who will install the file: one user, a team, or a public collection
- which files or folders must be affected
- what conventions are stable enough to encode as rules
### Phase 1: Study the source material
Before drafting:
- inspect existing instructions, README notes, and representative source files
- separate lint or formatter-enforced behavior from guidance that still needs human judgment
- collect only durable conventions; avoid temporary migration notes unless explicitly requested
### Phase 2: Choose the file shape
Use this decision rule:
- create `copilot-instructions.md` when the rules apply to nearly every task in the repository
- create `*.instructions.md` when the rules apply to a clear file pattern, directory, or workflow boundary
- split files when one audience would otherwise inherit unrelated rules
### Phase 3: Draft the instruction file
For scoped instruction files:
- choose a descriptive filename in kebab case
- write frontmatter with `description`, `applyTo`, `title`, and `name` when helpful
- keep each rule compact and testable
- add examples only for non-obvious conventions
For repo-wide instruction files:
- describe architecture, stack, folder responsibilities, commands, and non-obvious conventions
- organize by headings so Copilot can find the right rule quickly
- keep it opinionated enough to be useful but not so exhaustive that it becomes background noise
### Phase 4: Create the artifact bundle
Always prepare:
- the main instruction file
- a short installation note or target path
- at least one reference template or example when the instruction is meant to be reused
- a brief summary of why the scope and file type were chosen
Use these supporting resources:
- `./resources/copilot-instructions.template.md`
- `./resources/custom-instructions.template.instructions.md`
- `./resources/copilot-instructions.example.md`
- `./resources/custom-instructions.example.instructions.md`
### Phase 5: Validate before handoff
Check the final result against `./resources/instructions-quality-checklist.md`.
Pay extra attention to:
- `applyTo` being narrow enough to avoid accidental always-on context
- rules being declarative, not step-by-step workflows
- examples matching the claimed rule
- no duplication of agent behavior, prompt workflow, or skill instructions
## Common Failure Modes
- using `applyTo: '**'` for advice that only matters in one part of the repo
- turning the file into a tutorial instead of a rule set
- copying linter or formatter defaults instead of encoding missing conventions
- mixing multiple unrelated audiences into one instruction file
- writing rules without enough context for Copilot to understand why they matter
## Resource Map
- `./resources/copilot-instructions.template.md` - repo-wide starting point for a project constitution
- `./resources/custom-instructions.template.instructions.md` - scoped instruction template with frontmatter
- `./resources/copilot-instructions.example.md` - worked repo-level example for a test automation repository
- `./resources/custom-instructions.example.instructions.md` - worked scoped example with concrete rules
- `./resources/instructions-quality-checklist.md` - final review checklist before shipping
## Definition of Done
A task using this skill is complete when:
- the chosen instruction type matches the actual scope
- the file is install-ready and placed in the right target location
- the rules are concise, durable, and non-duplicative
- supporting template or example material exists when the artifact is meant for reuse
- the final result passes the quality checklist without obvious ambiguity
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |