GitHub Copilot mit Markdown-Dateien steuern

GitHub Copilot arbeitet kontextbasiert. Wer immer wieder dieselben Rahmenbedingungen erklären muss – Framework, Namenskonventionen, verbotene Bibliotheken –, verliert Zeit. Markdown-Dateien lösen dieses Problem: Einmal gepflegt, automatisch bei jeder Copilot-Interaktion berücksichtigt.

Es gibt drei Ebenen: die Benutzerebene (gilt für alle Projekte), die Workspace-Ebene (gilt für ein Repository) und die Aufgabenebene (gilt für bestimmte Dateitypen oder wiederkehrende Aufgaben).

Ebene 1: Benutzerebene – persönliche Standardvorgaben

VS Code sucht benutzerspezifische Instruktionsdateien standardmäßig hier:

Windows: C:\Users\<Benutzername>\.copilot\instructions\
Linux:   ~/.copilot/instructions/

In diesem Verzeichnis können eine oder mehrere Dateien mit der Endung .instructions.md abgelegt werden. VS Code durchsucht es rekursiv, Unterordner sind erlaubt. Wer einen anderen Speicherort bevorzugt, trägt diesen in der Einstellung chat.instructionsFilesLocations ein.

Visual Studio kennt keine benutzerweit gültige Markdown-Datei für Instruktionen. Persönliche Vorgaben werden über Tools | Options | GitHub | Copilot konfiguriert.

Ebene 2: Workspace-Ebene – projektweite Regeln

Die wichtigste Datei ist copilot-instructions.md im .github-Verzeichnis. Sie gilt für das gesamte Projekt und wird bei jeder Copilot-Interaktion geladen – im Chat, im Agent-Modus und beim Coding Agent. Der Pfad ist für VS Code und Visual Studio identisch:

Windows: <Projektverzeichnis>\.github\copilot-instructions.md
Linux:   <Projektverzeichnis>/.github/copilot-instructions.md

Typische Inhalte sind Architekturvorgaben, Namenskonventionen und die Teststrategie:

# Projekt: WebShop API
## Architektur
- .NET 9 Minimal API mit Clean Architecture
- src/Api/ – Endpoints, src/Domain/ – Entities, src/Infrastructure/ – EF Core
## Konventionen
- Records für DTOs, keine statischen Methoden in Domain-Klassen
- Jeder Endpoint braucht einen Integrationstest
- Fehlerbehandlung über ProblemDetails (RFC 9457)

In VS Code wird die Datei automatisch erkannt. In Visual Studio wird sie ab Version 2022 17.10 unterstützt.

Ebene 3: Dateispezifische Anweisungen

Regeln für bestimmte Dateitypen kommen in das Verzeichnis .github/instructions/. Die Dateiendung lautet zwingend .instructions.md.

Windows: <Projektverzeichnis>\.github\instructions\*.instructions.md
Linux:   <Projektverzeichnis>/.github/instructions/*.instructions.md

Jede Datei enthält im YAML-Frontmatter ein applyTo-Feld mit einem Glob-Muster:

---
applyTo: "**/*.Tests/**/*.cs"
---
## Regeln für Unit-Tests
- Testframework: xUnit, Mocking: NSubstitute
- Namensschema: MethodName_Szenario_ErwartetesErgebnis
- Arrange-Act-Assert-Kommentare in jedem Test

In VS Code vollständig unterstützt, in Visual Studio ab Version 2026.

Ebene 4: Wiederverwendbare Prompts

Für wiederkehrende Aufgaben lassen sich Prompt-Dateien mit der Endung .prompt.md anlegen:

Windows: <Projektverzeichnis>\.github\prompts\*.prompt.md
Linux:   <Projektverzeichnis>/.github/prompts/*.prompt.md

In VS Code über /prompt aufrufbar, in Visual Studio 2026 per #-Referenz im Copilot-Chat.

Ebene 5: AGENTS.md – der offene Standard

Die AGENTS.md ist ein offener Standard, den neben GitHub Copilot auch andere KI-Agenten wie Claude Code oder OpenAI Codex verstehen. Sie dient als gemeinsame Wissensbasis für alle Agenten im Projekt.

Windows: <Projektverzeichnis>\AGENTS.md
         Unterverzeichnis: <Projektverzeichnis>\src\AGENTS.md
Linux:   <Projektverzeichnis>/AGENTS.md
         Unterverzeichnis: <Projektverzeichnis>/src/AGENTS.md

Die Empfehlung: copilot-instructions.md für Copilot-spezifische Regeln, AGENTS.md als gemeinsame Basis für alle KI-Agenten. Die AGENTS.md wird vom Coding Agent, von VS Code im Agent-Modus und von Copilot CLI gelesen. In Visual Studio wird sie derzeit nicht ausgewertet.

Ebene 6: Agent Skills

Agent Skills sind aufgabenbezogene Fähigkeiten, die Copilot nur bei Bedarf lädt – im Gegensatz zu Instruktionen, die immer aktiv sind. Sie eignen sich für Workflows, Templates und mehrstufige Abläufe, die nur in bestimmten Situationen relevant sind.

Neu seit Mai 2026: Visual Studio unterstützt Agent Skills. Über das Skills-Panel (Zahnrad-Icon im Copilot-Chat) lassen sich Skills direkt in der IDE anlegen, durchsuchen und bearbeiten. Visual Studio generiert dabei eine SKILL.md-Vorlage, die man anschließend befüllt.

Skills werden an zwei Orten abgelegt – projektbezogen im Repository oder persönlich im Benutzerprofil:

Projektbezogen (Windows): <Projektverzeichnis>\.github\skills\<SkillName>\SKILL.md
Projektbezogen (Linux):   <Projektverzeichnis>/.github/skills/<SkillName>/SKILL.md

Persönlich (Windows): C:\Users\<Benutzername>\.copilot\skills\<SkillName>\SKILL.md
Persönlich (Linux):   ~/.copilot/skills/<SkillName>/SKILL.md

Persönliche Skills stehen in allen Projekten zur Verfügung. Neben .copilot/skills/ werden auch .claude/skills/ und .agents/skills/ als Speicherorte erkannt.

Copilot liest zunächst nur den YAML-Frontmatter (Name und Beschreibung). Erst bei einem passenden Prompt wird der vollständige Inhalt geladen. Neben der SKILL.md können im selben Verzeichnis weitere Dateien liegen – zum Beispiel Templates oder Checklisten, auf die der Skill verweist.

---
name: security-review
description: Sicherheits-Review für C#-Code. Aktivieren bei Fragen zu
             OWASP, SQL-Injection oder Authentifizierung.
---
## Anweisungen
- Nur parametrisierte Queries, kein String-Concat bei SQL
- Input-Validierung auf allen public-Methoden prüfen
- Befunde mit Verweis auf OWASP Top 10 dokumentieren

Agent Skills funktionieren im Coding Agent, in VS Code im Agent-Modus, in Visual Studio (ab Mai 2026) und im Copilot CLI.

Übersicht: Welche Datei wirkt wo?

Empfehlungen für den Einstieg

Der beste Einstieg ist die copilot-instructions.md im .github-Verzeichnis – sie wirkt sofort in beiden IDEs und beim Coding Agent. Als nächster Schritt lohnen sich zwei oder drei Prompt-Dateien für häufige Aufgaben wie Unit-Tests oder Code-Reviews. Wer mehrere KI-Agenten einsetzt, legt zusätzlich eine AGENTS.md an. Agent Skills sind der richtige Baustein, sobald sich bestimmte Workflows wiederholen – zum Beispiel ein fester Ablauf für Security-Reviews oder das Anlegen von GitHub-Issues nach einem Teamstandard.