ki-grok/08-skills-plugins-hooks-und-marketplaces.md

Kapitel 8

Skills, Plugins, Hooks und Marketplaces

Kern in einem Satz: Skills sind wiederholbare Verfahren on-demand, Hooks erzwingen Lebenszyklus-Gates, Plugins/Marketplaces packen und verteilen beides – und du wählst bewusst weich vs. hart.

---

8.1 Steuerflächen im Vergleich

Alltagsschmerz: Der Agent „vergisst“ das Verify-Ritual, der Hook blockt still einen rm, und niemand weiß, ob das Team-Plugin überhaupt trusted ist. Die Tabelle sortiert weich → hart → verpackt.

Steuerfläche	Charakter	Typisches Beispiel
AGENTS.md	immer im Kontext, weich	„Tests: npm test“
Skill	bei Bedarf / per /name, Verfahren	/commit, /verify
Hook	Event-getrieben, kann blocken	PreToolUse: rm -rf deny
Plugin	Bundle aus Skills, Hooks, Agents, MCP	Team-„deploy-tools“
Marketplace	Katalog, aus dem du Plugins installierst	org/team-plugins

Wann Skill statt AGENTS.md? Zu speziell oder zu lang für jede Session, aber zu häufig zum Tippen.
Wann Hook statt Skill? „Darf gar nicht passieren“ oder „nach jedem Edit formatieren“ – ohne dass der Agent es „vergessen“ darf.
Wann Plugin? Mehrere Artefakte + Team-Distribution.

Weich vs. hart (K-05) und Skills vs. Hooks (M-07) hängen zusammen: erst die Härte-Skala, dann die Verpackung.

{width=90%}

{width=90%}

---

8.2 Skills: Aufbau und Orte

Ein Skill = Verzeichnis mit SKILL.md (YAML-Frontmatter + Markdown-Body).

Discovery (Priorität, höher gewinnt bei gleichem Namen):

Ort	Scope
./.grok/skills/, ./.grok/commands/	CWD/local (höchste)
<repo>/.grok/skills/, …/commands/	Repo
~/.grok/skills/, ~/.grok/commands/	User
Claude/Cursor-Pfade	Compat (konfigurierbar)
Bundled / Plugins	Plattform bzw. installiert

Zusätzlich: .agents/skills/ pro Tier; Walk von CWD bis Repo-Root. Flat commands/*.md → Slash-Commands (Stem = Name), Claude-Legacy-Layout.

Wichtig: Skill-Discovery ignoriert .gitignore nicht im Sinne von „ausblenden“ – Pfade unter bekannten Roots (.grok/, .agents/, .claude/, .cursor/) laden, wenn sie auf Disk liegen. Verstecken über Config:

[skills]
paths = ["~/my-team-skills"]
ignore = ["~/my-team-skills/wip"]
disabled = ["wip-skill"]

Minimal-SKILL.md

---
name: verify
description: >
  Run project tests and lint after code changes. Use when the user asks
  to verify, /verify, or before committing.
---

# Verify

1. Run the project's test command from AGENTS.md (fallback: `npm test`).
2. Run lint if defined.
3. Report pass/fail with the first failure excerpt.
4. Do not push or open PRs.

Frontmatter	Rolle
name	Identifier (lowercase, digits, hyphens; max 64)
description	Trigger für Auto-Invocation – spezifisch schreiben
when-to-use	extra Trigger-Phrasen
user-invocable	default true → erscheint als /name
disable-model-invocation	true = nur Slash, kein Auto
allowed-tools, model, effort, …	optional eng führen

Wie Trigger greifen: description und when-to-use steuern, wann der Agent den Skill von allein lädt. Vage Descriptions („hilft bei Code“) nerven: zu oft oder nie. Schärfe sie so, dass der Use-Case und die Slash-Form (/verify) erkennbar sind (Vertiefung: 8.3).

---

8.3 Skills nutzen und erzeugen

Aufruf

/verify
/commit fix the build
/local:commit          # CWD: ./.grok/skills/
/repo:commit           # Repo-Root: <repo>/.grok/skills/
/user:commit           # User: ~/.grok/skills/
/deploy-tools:release  # Plugin-Skill: /<plugin-name>:<skill>

/ öffnet das Menü (Builtins + Skills). Builtins gewinnen unqualifiziert über gleichnamige Skills – dann den Scope-Prefix nutzen. CLI-Übersicht: grok inspect.

Erzeugen mit /create-skill

Interaktiver Flow: Name, Scope (Project vs. User), Description-Draft, Verzeichnis, SKILL.md, Verify.

• Project: <repo>/.grok/skills/<name>/ – teamfähig, committen.
• User: ~/.grok/skills/<name>/ – persönlich.

Team-weit: lieber Plugin + Marketplace (unten) als 30 manuelle Kopien.

Reload: Dateiänderung auf Disk; Skills erscheinen meist in Sekunden im Slash-Menü. Neu installierte Plugin-Skills: r im Plugins-Tab oder neue Session.

Auto-Invocation: Grok matcht Prompt gegen description / when-to-use. Vage Descriptions = ungewollte Triggers. Für manuell-only: disable-model-invocation: true.

---

8.4 Plugins und Marketplaces

Marketplace = Katalog (noch nichts aktiv). Plugin = installierte Einheit (Skills, Commands, Agents, Hooks, MCP).

# Marketplace hinzufügen
grok plugin marketplace add my-org/team-plugins
grok plugin marketplace add https://gitlab.com/acme/plugins.git
grok plugin marketplace add ./my-marketplace
grok plugin marketplace list
grok plugin marketplace update
grok plugin marketplace remove <url>

# Plugin installieren
grok plugin install deploy-tools --trust
# ohne --trust: Warnung und Stop – Install bricht ab

Quellen: owner/repo, @ref/@sha, git URL, lokaler Pfad.

grok plugin list
grok plugin update
grok plugin enable|disable <name>
grok plugin uninstall <name>
grok plugin details <name>

TUI: /plugins (überall; auf VS-Code-Family der sichere Weg). Modal-Tabs: Hooks, Plugins, Marketplace, Skills, MCP. Keys u. a. r reload, Space enable/disable, i install (Marketplace).

Enable vs. Trust: Enable lädt Skills, Commands und Agents. Trust schaltet Hooks, MCP und LSP des Plugins scharf. Beides ist getrennt – enable allein startet keine Hook-/MCP-Ausführung.

Config-Quellen dauerhaft:

[[marketplace.sources]]
name = "My Team Plugins"
git = "https://github.com/my-org/plugins.git"

Achtung: Install + Trust aktiviert Hooks und MCP des Plugins. Nur Quellen, denen du vertraust. Untrusted Plugin-MCP erscheint als blocked, bis Trust greift.

Qualified Skill-Namen bei Kollision: /deploy-tools:release.

---

8.5 Hooks: erzwingen statt hoffen

Hook = Command oder HTTP an Lifecycle-Events.

Event	Blockierend?	Typischer Nutzen
SessionStart	nein	Setup, Env
UserPromptSubmit	nein	Logging
PreToolUse	ja – deny	Safety-Guard
PostToolUse	nein	Format, Log
PostToolUseFailure	nein	Alert
Stop / SubagentStop (Alias SubagentEnd)	ja – Stop blocken	„Tests müssen grün sein“
SubagentStart	nein	Audit
PreCompact / PostCompact	nein	Memory-Hygiene
SessionEnd	nein	Cleanup
PermissionDenied / Notification / StopFailure	nein	Audit / UI-Hinweise

Vollständige Event-Liste: User-Guide Hooks.

Orte (gemerged): ~/.grok/hooks/*.json, Projekt .grok/hooks/*.json (Folder-Trust nötig), Config-TOML, managed/requirements, Plugins, optional Claude/Cursor-Compat-Dateien.

Trust: Projekt-Hooks laufen erst nach Trust (/hooks-trust oder --trust). Decision in ~/.grok/trusted_folders.toml – derselbe Gate wie für repo-lokale MCP/LSP. Global ~/.grok/hooks/ ist immer trusted.

# Trust nur bewusst – multipliziert mit MCP
grok --trust
# in Session: /hooks-trust

Quick-Start PreToolUse-Guard (Skizze)

~/.grok/hooks/guard-rm.json (Pfad-Skizze; im Übungsrepo oft bin/block-rm.sh wie beispiele/todo-cli/, kopierfertig auch unter vorlagen/hooks/ mit scripts/block-rm.sh):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|run_terminal_command",
        "hooks": [
          {
            "type": "command",
            "command": "bin/block-rm.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Script liest JSON von stdin; bei gefährlichem Command stdout:

{"decision": "deny", "reason": "rm -rf blocked by policy"}

Sonst {"decision": "allow"}. Matcher akzeptiert Claude-Aliase (Bash ↔ run_terminal_command). MCP-Tools matchen als server__tool.

Fail-open: Timeouts/Crashes des Hooks blocken nicht – nur explizites deny. Für Compliance: Monitoring der Hook-Failures im Scrollback.

Hooks in config.toml

[[hooks.PreToolUse]]
matcher = "Bash|Write|Edit"
hooks = [
  { type = "command", command = "/opt/guard/pretooluse.sh", timeout = 10 },
]

Layer sind additiv (user + managed + requirements).

TUI: /hooks – geladene Hooks sehen, toggeln (Trust-Modell beachten).

---

8.6 Zusammenspiel: ein Tag im Leben

1. SessionStart-Hook setzt ENV=dev.
2. AGENTS.md sagt: Testcommand + Don'ts.
3. Du: Feature bauen.
4. Skill /verify – reproduzierbarer Testlauf.
5. PostToolUse-Hook formatiert nach Edits.
6. PreToolUse-Hook blockt git push --force.
7. Skill /commit – Conventional Message.
8. MCP aus Plugin (Kapitel 9) öffnet PR – nur wenn trusted.

Anti-Pattern: Alles in Hooks pressen (langsam, fragil) oder alles nur in AGENTS.md (wird ignoriert, wenn lang und weich).

---

8.7 Praxis-Sessions

Session 1 – Ersten Skill bauen

/create-skill

Oder manuell:

Lege .grok/skills/verify/SKILL.md an:
name verify, description mit Triggern /verify und "run tests",
Body: exakte Testcommands aus AGENTS.md, dann Lint, Report, kein Push.

/verify

Erfolg: Skill läuft; grok inspect listet project.

Session 2 – Auto vs. nur Slash

---
name: release-notes
description: Draft release notes from commits since last tag.
disable-model-invocation: true
user-invocable: true
---

# „schreib release notes“ soll NICHT auto feuern
/release-notes

Session 3 – Hook-Guard testen

1. PreToolUse-Hook installieren, der ein harmloses Pattern denyt (z. B. echo HOOK_DENY_TEST).
2. Agent bitten: echo HOOK_DENY_TEST auszuführen.
3. Deny-Reason im Scrollback sehen.
4. Hook entfernen/disable.

Trainingsziel: hartes Gate spüren, bevor du es auf rm legst.

Session 4 – Marketplace / Plugin (Team-Sim)

# nur wenn du eine vertrauenswürdige Quelle hast
grok plugin marketplace add ./path-to-local-marketplace   # oder org/repo
grok plugin install some-safe-plugin --trust
grok plugin details some-safe-plugin

In der TUI /plugins → Skills/Hooks/MCP des Plugins prüfen. Untrusted: MCP blocked.

Session 5 – Skill + AGENTS.md abgrenzen

AGENTS.md enthält nur: "Vor Commit: /verify oder äquivalent grün."
Die Schritte stecken im Skill, nicht in der Bibel.
Bestätige die Trennung und führe /verify aus.

---

8.8 Jetzt selbst machen: Extensions-Parcours (35 Minuten)

Jetzt selbst machen

1. Project-Skill verify anlegen und per /verify fahren.
2. description so schärfen, dass „run the tests“ auto oder manuell wie gewollt greift.
3. grok inspect – Source project verifizieren.
4. Globalen oder User-Hook SessionStart mit harmlosem echo testen.
5. /hooks öffnen – Hook sichtbar.
6. Optional: absichtlich untrusted Project-Hook-Ordner → ohne Trust still.
7. Notiere: Welcher Workflow wird als Nächstes ein Plugin?

---

8.9 Häufige Fehler

Symptom	Ursache	Fix
Skill erscheint nicht	Name/Pfad/disabled	grok inspect, Frontmatter
Falscher Skill bei Kollision	Unqualifizierter Name	/local:name / /repo:name / /user:name / /<plugin>:name
Auto-Skill nervt	Vage description	when-to-use schärfen oder disable-model-invocation
Project-Hooks tot	Kein Folder-Trust	/hooks-trust bewusst
Plugin Skills da, Hooks/MCP tot	enable ≠ trust	--trust / Trust im Modal, dann r
Plugin install, nichts passiert	nicht trusted / disable	--trust, enable, r
Hook „blockt nicht“ bei Crash	fail-open	Script härten, explizit deny

---

8.10 Checkliste

• Skills: ein Workflow pro Skill, spezifische description
• Team-Skills unter .grok/skills/ committed
• Hooks nur für echte Gates; Trust verstanden
• Plugins nur aus trusted Sources + Inventory (details)
• AGENTS.md bleibt kurz – Verfahren in Skills
• grok inspect nach Änderungen

---

Was du jetzt kannst

• Skills anlegen, aufrufen und von AGENTS.md abgrenzen
• Hooks als blockierende Gates einsetzen und Trust erklären
• Marketplaces/Plugins installieren und qualifizierte Skill-Namen nutzen
• Ein Zusammenspiel Skill + Hook + Rules für den Alltag skizzieren

Nächste Schritte

→ Kapitel 09 – MCP-Server und externe Tools: externe Systeme anbinden, ohne den Agenten zum Secret-Store zu machen.