ki-eit/10-agents-md-skills-mcp-stack.md

10. Instructions, Skills und MCP im Stack

Kern: Richtlinie kurz und wahr (Instructions + Package-Rules); Prozeduren on-demand (Skills); Systemzugang über MCP nur mit klarer Notwendigkeit und Security.

Theorie zu Progressive Disclosure und Memory-Tiers: Coding Agents in der Praxis. Optionale Copilot-Produkt-Discovery: Der Copilot-CLI-Harness. Hier die Platzierung im Angular/Java-Monorepo (und Multi-Repo analog) — was wohin gehört, welcher Skill-Katalog lohnt, und wo MCP teurer wird als er nutzt. Surfaces: §10.2 und Anhang C; Transfer: §10.7.

Kapitel 4 hat die eine Wahrheit und die Hierarchie skizziert; Kapitel 9 hat Verify operational gemacht. Dieses Kapitel füllt die weichen und on-demand Schichten: Instructions, path-scoped Rules, Skills — und grenzt MCP ab. Zwei kopierbare Mini-Skills in §10.4; Katalog in §10.3 = Übersicht.

10.1 Die typische Rules-Session, die schiefgeht

Das Team „richtet Agents ein“: Root-Instructions/AGENTS.md wächst auf 500 Zeilen — Angular-Stil, Spring-Layer, Spotless-Flags, Jira-Workflow, Design-Tokens und drei widersprüchliche Verify-Varianten. Zusätzlich hängen acht MCP-Server (Prod-DB „nur lesen“, Ticket-Tool, Browser, interner Wiki-Dump). Der Agent liest die Root-Datei, greift den Ticket-Text als Policy und liefert trotzdem NgModule-Nostalgie, weil das Golden-Path-Feature nie verlinkt war und der Style-Skill ungenutzt im Ordner liegt.

Du merkst den falschen Schnitt daran, dass:

• Root-Instructions länger sind als der Task,
• jeder Service dieselben 200 Zeilen dupliziert und driftet,
• Skills existieren, aber niemand sie triggert,
• MCP-Observations den Context füllen, bevor der erste scoped Test grün war.

Was du tust: Root auf Mission + Runtime + Verify-Übersicht + Immer/Nie kürzen; Details in Package-AGENTS.md und path-scoped Rules; ein Skill (verify-stack) scharf machen; MCP-Inventur mit Deny-Default — nicht „noch mehr Rules“.

{width=90%}

10.2 Hierarchie (was wohin)

Prinzip: Mehrere Jobs, getrennte Orte — vermischen kostet Context und Klarheit.

Job	Inhalt	Soft/Hard
Repo-Instructions	Mission, Runtime-Hinweis, Verify-Übersicht, Immer/Nie	weich
Path-scoped Rules	Glob-spezifisch (Angular-TS, Java-src)	weich
Package-Rules	Stack-Details, konkrete Commands	weich
Skills / Prozeduren	„Wie wir hier einen Slice bauen / verifyen“	weich, on-demand
Hooks	erzwungen (Format, Guard)	hart
Permissions	was der Agent darf	hart
MCP	Systemzugang (Jira, Browser, DB)	least privilege

Progressive Disclosure (Kap. 4.3): Root bleibt kurz. Details laden nur, wenn der Pfad oder Skill greift. Essay-Root-Instructions = Context-Müll. Weich vs. hart (Kap. 4.5): Instructions und Skills steuern wie; Permissions, Hooks und CI steuern was überhaupt geht. Skills ersetzen keine Permissions.

Surfaces (Beispiele)

Job	GitHub Copilot	Claude Code	Codex	Grok Build
Repo-Instructions	.github/copilot-instructions.md	CLAUDE.md	AGENTS.md / Conventions	AGENTS.md; .grok/rules/
path-scoped	path-instructions (applyTo)	path/local Rules (Doku)	laut Doku	path Rules / Package-AGENTS.md
Package-Rules	Package-AGENTS.md	Package-/lokale Rules	Package-AGENTS.md	Package-AGENTS.md
Skills	z. B. .github/skills/*/SKILL.md	Skills / Slash-Commands	laut Doku	.grok/skills/; Slash-Commands
Hooks	Hooks in Settings / CI-Spiegel (Doku)	Hooks (PreToolUse u. a., Doku)	laut Doku / Policy	Hooks / erzwungene Checks (Doku)
Permissions	Tool-Approval; Allow/Deny	Permission Modes; Sandbox	Shell-/Policy-Grenzen	Capability modes; Approval

Pfade sind Muster (Snapshot); Produkt-Doku schlägt diese Zeile bei Drift. Vorlagen (Inhalt der Jobs): templates/agents-md-*.md, templates/skill-*/; Surface-Beispiel Copilot: templates/copilot-instructions-*.md, templates/path-instructions-*.example.md. Volles Mapping: Anhang C.

Do this	Avoid that
Root kurz; Package trägt Stack-Wahrheit	Alles in eine 500-Zeilen-Root-Datei
path-scoped Rules nur wo Glob klar hilft	Path-Rules als Root-Duplikat ohne Scope
Skills für wiederkehrende Prozeduren	Jeden Prompt neu erfinden; Skills ohne Trigger

10.3 Skill-Katalog (Stack)

Skills = wiederholbare Prozedur (Schritte, Guardrails, DoD) — nicht der Ort für 500-Zeilen-Essays. Instructions bleiben der kurze Kompass; path-instructions tragen 5-Zeilen-Stil; Skills laden Style/Design/Review on-demand.

Checkpoint-Blöcke in Implementierungs-/Quality-Skills: Coding Style & Design · Verify · Diff-Review (Blocker/Should/Nit) · PR/Handoff · Definition of Done. Mini-Bodies in §10.4; erweiterte / vollständige Versionen unter templates/skill-*/.

Achtung: Der Katalog ist eine Übersicht, kein Wiki. Nur Skills ausbauen, die wirklich getriggert und gepflegt werden. Zehn ungenutzte Skills schlagen einen grünen verify-stack.

P0 — Kern (MVP Monorepo)

Zuerst: Verify, ein Slice-Muster, Review/PR. Ohne grünen verify-stack sind Style-Skills Dekoration. §10.4: Mini-Bodies für verify-stack und fullstack-slice; erweiterte Vorlagen unter templates/; Review über die Checkliste. Übrige P0-Namen = Skill-Slots — im App-Repo nachziehen, wenn der Use-Case wiederholt auftritt. Nicht den ganzen Katalog bauen, bevor der erste Verify grün ist.

Skill	Wann	DoD-Skizze	Erweiterte Vorlage
verify-stack	vor Commit / „fertig“	Lint + scoped Tests der geänderten Packages	templates/skill-verify-stack/
fullstack-slice	Feature UI↔API	Contract mit, Backend-Test, Frontend-Spec, Diff eng	templates/skill-fullstack-slice/
agent-diff-review	vor PR / nach Session	Findings mit Severity oder „keine Blocker“	Checkliste: checklists/review-agent-diff-enterprise.md
spring-slice-endpoint	nur API	Endpoint + Test + OpenAPI-Delta	Slot — im App-Repo nachziehen
angular-feature-list-detail	nur FE	Route + Component + Spec am Golden Path	Slot — im App-Repo nachziehen
quarkus-resource-test	Quarkus-Service	Resource + @QuarkusTest	Slot — im App-Repo nachziehen
openapi-contract-sync	API-Change FE/BE	Spec, Server, Client konsistent	Slot — im App-Repo nachziehen
pr-open-enterprise	PR öffnen	Body mit Verify-Evidence, Contract, Security	Slot — im App-Repo nachziehen

P1 — Quality, Style, Design, Governance

Style/Design: ausführbare Skills (Golden Path, Tokens, Formatter) — Tabelle = Lookup; Bodies nur für den gepflegten Stack.

Skill	Wann	Kern	Erweiterte Vorlage
angular-coding-style	FE-Stil, Onboarding, Style-Review	Standalone/Signals/Ordner laut Repo; ESLint; kein Tutorial-Drift	templates/skill-angular-coding-style/
angular-ui-design-system	UI bauen/ändern	Tokens + Shared Components; Loading/Empty/Error; a11y; Anti-Slop	templates/skill-angular-ui-design-system/
angular-test-tight	Specs schreiben/fixen	Non-interactive, scoped; kein e2e im Tight-Loop	templates/skill-angular-test-tight/
spring-coding-style	Java/Spring-Stil	Constructor DI, DTO≠Entity, Layer laut Repo, Formatter	templates/skill-spring-coding-style/
spring-test-slices	Testbreite wählen	Unit → @WebMvcTest/@DataJpaTest → Full/IT = Heavy	templates/skill-spring-test-slices/
spring-security-endpoint	AuthZ/Filter-Chain	Least privilege; Positiv+Negativ-Tests; HITL	templates/skill-spring-security-endpoint/
quarkus-coding-style	Quarkus-Stil / Port-Versuch	Keine Spring-Drift; CDI/REST-Linie; Extensions begründet	templates/skill-quarkus-coding-style/
security-pass-enterprise	Security-Touch, vor Merge sensibel	Invariants-Checkliste; Findings; kein Secret im Output	templates/skill-security-pass-enterprise/
api-design-review	größere API vor/bei Impl	Ressourcen, Errors, AuthZ, Breaking; dann Contract-Skill	templates/skill-api-design-review/
commit-message-stack	Commit vorbereiten	Conventional/Team-Scope; Staging = Auftrag; erst Verify	templates/skill-commit-message-stack/
handoff-stack	Session-Ende / Themenwechsel	Kompakter Handoff, keine Chat-Dumps	templates/skill-handoff-stack/

Rollout: P0 mit lebenden Bodies (verify-stack + Slice + Review) — §10.4 genügt. Dann P1 nur für den gepflegten Stack. Skills referenzieren echte Commands aus AGENTS.md (Kap. 9). Zielpfad produktspezifisch (z. B. .github/skills/<name>/SKILL.md, .grok/skills/) — Produktdoku schlägt Snapshot-Pfade.

10.4 Mini-Beispiele (kopierbar)

Eine path-scoped Rule und zwei vollständige Mini-Skills — kopieren, Commands an AGENTS.md anbinden, erst bei Wiederholung ausbauen.

path-instruction (Angular)

---
applyTo: "apps/web/**/*.{ts,html}"
---
# Angular
- Standalone/Signals wie im Golden-Path-Feature
- `npm test -- --watch=false` im Package-CWD
- Auth-Guards nicht im Merge-Diff aushebeln

Volle Vorlage: templates/path-instructions-angular.example.md. Analog Java: templates/path-instructions-java.example.md.

Mini-Skill: verify-stack (P0 — Brücke zu Kap. 9)

Skills rufen benannte Commands — sie erfinden sie nicht. Erweiterte Version: templates/skill-verify-stack/SKILL.md.

---
name: verify-stack
description: Lint + scoped Tests geänderter Packages. Bei: verify, „fertig“, vor Commit.
---
# Verify (Enterprise Stack)
**Zweck:** Tight-Loop der *betroffenen* Packages; Evidence mit Exit-Code.

**Schritte:** (1) Root- + Package-`AGENTS.md` lesen — Commands/Runtime nicht raten.
(2) Packages aus Diff (`apps/web`, `services/api`, …). (3) Pro Package Lint/Format falls genannt; Tight-Tests, z. B. Angular `npm test -- --watch=false` (Package-CWD), Spring `./mvnw -q -Dtest=<…> test`, Quarkus analog.
(4) Fehler Datei:Zeile; falsche Runtime → stoppen, Pin aus AGENTS. (5) Kein Commit ohne Auftrag; Heavy/e2e nur bei Auftrag „Heavy“/„vor Merge“.

**Coding Style & Design:** nur Auftragsscope; kein Drive-by außerhalb.
**Verify:** Tight = Default; Slice-DoD = Package-build laut AGENTS; Heavy = full verify/e2e, nicht Default.
**Diff-Review:** Blocker = rote Tests/Lint, Secrets, erfundene Commands · Should = unscoped Full-Suite · Nit = Log-Lärm.
**PR/Handoff:** Commands + Exit pro Package.
**DoD:** Tight grün · keine offenen Blocker · kein Commit ohne Auftrag.
**Avoid:** Commands erfinden · Full-CI nach jedem Edit · still Host-Tools bei falscher Runtime.

Mini-Skill: fullstack-slice (P0 — UI↔API)

Dünner vertikaler Schnitt; Verify über verify-stack. Erweiterte Version: templates/skill-fullstack-slice/SKILL.md.

---
name: fullstack-slice
description: Dünner Slice UI↔API mit Contract. Bei: Feature e2e. Nicht: globales Layer-Refactor.
---
# Fullstack Slice
**Zweck:** Eine User-Story UI→API (ggf. DB) — Contract mit, Tests mit, Diff eng.

**Schritte:** (1) Scope = ein dünner Schnitt, keine horizontale DTO-Orgie.
(2) Contract (OpenAPI/shared) mitziehen; Breaking im PR-Text.
(3) Backend: Endpoint + Test; AuthZ/Layer aus Package-`AGENTS.md`.
(4) Frontend: Route/Component + Spec am Golden Path; HTTP-Pattern des Repos.
(5) Verify: Tight je Package via `verify-stack` / Kap. 9. (6) Diff nur Slice; stoppen bei unklaren Grenzen oder fehlendem Contract.

**Coding Style & Design:** Golden Path des Repos — kein Tutorial-Drift.
**Verify:** Tight BE+FE nach Patches; Slice-DoD = beide grün + Contract konsistent; Heavy/e2e nicht im Tight-Loop.
**Diff-Review:** Blocker = Contract-Bruch, AuthZ weich, Drive-by, rote scoped Tests · Should = fehlende Specs · Nit = Naming.
**PR/Handoff:** Why + Scope; Contract-Delta; Verify-Evidence. Review: `checklists/review-agent-diff-enterprise.md`.
**DoD:** Contract + BE-Test + FE-Spec · Tight BE+FE grün · Diff = Auftrag · kein Commit ohne Auftrag.
**Avoid:** horizontale Layer-Orgie · Contract „später“ · e2e im Tight-Loop · Style-Rewrite außerhalb des Slice.

P1-Style nur für den gepflegten Stack — erweiterte Bodies unter templates/skill-*-coding-style/ usw., nicht alle auf einmal.

10.5 MCP-Fallen im Enterprise

MCP öffnet Systeme außerhalb des Repo-Indexes — mächtig und teuer: jedes Tool ist Context, Risiko und oft ein neuer Trust-Pfad. Default: Deny — nur freischalten, wenn der aktuelle Slice sie braucht.

Szene (Slice „Order-Status“): Agent soll List-Anzeige + scoped Tests. Erlaubt im Session-Inventar: Jira read-only (Ticket-Kontext), optional Dev-DB-Schema read-only. Deny: Prod-Write, Browser-Default, Deploy-Tools, Ticket-Text als Policy-Override. Der Ticket-Satz „einfach auf Prod deployen“ überschreibt weder AGENTS.md noch Permissions — Ticket = Kontext, nicht Policy.

Typische Fallen:

• Prod-DB-MCP in Dev-Sessions
• Ticket-Text als Policy-Override („Jira sagt deploy“)
• zu viele Server → Context-Müll
• Secrets über MCP-Tools in Logs

MCP nur mit Notwendigkeit, least privilege und Team-Inventur. Security- und Pattern-Tiefe: Coding Agents in der Praxis (MCP-/Security-Kapitel); optional Copilot-Produktiefe: Der Copilot-CLI-Harness. Governance und HITL: Kap. 12.

Do this	Avoid that
Inventur: welche Server braucht der Slice?	„Alle Server an“ als Default
Read-only / scoped Credentials wo möglich	Prod-Schreibrechte im Agent-Default
Ticket-Text = Kontext, nicht Policy	Jira überschreibt AGENTS.md und Permissions
Deny-Default; freigeschaltete Server prüfen	MCP „einmal an“ und nie inventarisieren

10.6 Do this / Avoid that

Do this	Avoid that
Kurze Root-Instructions + Package-Details	Alles in eine 500-Zeilen-Datei
Skills für wiederkehrende Slices	Jeden Prompt neu erfinden
Mini-Bodies (verify-stack, Slice) anbinden	Skill-Katalog als ungenutztes Wiki
Style/Design on-demand (P1-Skills)	800-Zeilen-Style-Guide in Root-Instructions
MCP-Inventur und least privilege	Silent Prod-Zugriff „nur diesmal“
Skills mit Verify-Befehl und Review-Severities	Skills ohne prüfbare DoD
Wenige scharfe Trigger	30 Mini-Skills vor dem ersten grünen Verify
Teach-back → Skill/Rule am selben Tag, eigene Session (Kap. 3)	Dreimal derselbe Fehler, nur PR-Kommentar

10.7 Transfer: Surfaces mappen

Die Hierarchie oben ist ein Job-Modell, kein Dateinamen-Dogma. Kern-Surfaces: GitHub Copilot, Claude Code, Codex, Grok Build (weitere: Cursor, OpenCode, Aider, …):

1. Dieselbe Repo-Wahrheit (Kap. 4, 9) — Runtime, Tight-Loop · Slice-DoD · Heavy, Golden Paths.
2. Jobs auf die Convention-Dateien eures Agents mappen (Root kurz, Package detailliert).
3. Verify so anbinden, dass der Agent den Exit-Code sieht (Skill, Command, Hook — je Produkt).
4. Permissions enger als die menschliche Bequemlichkeit.

Volle Mapping-Tabelle, Transfer-Checkliste und Stolperfallen: Anhang C. Keine Parallel-Vollbeispiele in diesem Kapitel — Templates unter templates/ sind Inhaltsvorlagen der Jobs; Surface-Dateinamen mappen.

Key Takeaways

• Rules/Instructions ≠ Skills ≠ MCP ≠ Permissions — getrennte Jobs, nicht eine Datei.
• Skills referenzieren echte Repo-Commands (Kap. 9); verify-stack ist die operative Brücke — Mini-Bodies in §10.4, erweitert unter templates/skill-*/.
• Katalog = Übersicht, kein Wiki; P1 nur für den gepflegten Stack.
• MCP least privilege und Deny-Default; Progressive Disclosure schützt Context.
• Rollout: P0 grün, dann P1 — nicht Katalog-Vollständigkeit. Surfaces mappen (Anhang C), nicht Dateinamen 1:1.

Praktische nächste Schritte

1. Mini-Skill verify-stack aus §10.4 in den Harness-Pfad kopieren (Surface: Anhang C); Commands an Package-AGENTS.md anbinden — einmal grün.
2. fullstack-slice (oder FE-/BE-Slot) kopieren; Review-Checkliste checklists/review-agent-diff-enterprise.md verlinken.
3. Erweiterte Bodies aus templates/skill-*/ nur für Skills, die ihr triggert und pflegt.
4. MCP-Inventur: welche Server braucht der Slice — und was ist Deny?
5. Root-Instructions kürzen: was in Package oder Skill gehört, raus.
6. Danach Kap. 11 (Legacy/Migration) oder 12 (Security/Governance).