ki-codex/05-mcp-skills-hooks-agents-plugins.md

Kapitel 5

MCP, Skills, Hooks, Agents und Plugins

Kern in einem Satz: Erweiterbarkeit hat Härtegrade – von weichem Memory über on-demand Skills und MCP-Tools bis zu erzwungenen Hooks und Rules; wähle den leichtesten Hebel, der das Risiko trägt.

---

5.1 Entscheidungsmatrix: Härtegrade

Szene: Das Team will „niemals rm -rf ohne Nachfrage“ und „vor Commit immer pytest -q“. Beides in AGENTS.md schreiben? Der erste Satz gehört hart (Hook/Rule/Sandbox), der zweite oft als Skill oder knappe Immer-Zeile – nicht als 200-Zeilen-Roman im Startkontext.

Härtegrad	Mechanismus	Greift wann	Typische Nutzung
Weich / immer	AGENTS.md	jeder Run (Cap!)	Build/Test, Nie-Liste, Layout
On-demand	Skills	wenn gewählt / geroutet	wiederholbare Workflows
Neue Tools	MCP	wenn Server connected	Docs, Browser, Tracker
Erzwingen	Hooks / Rules	Lifecycle / Command-Prefix	Guardrails, Format, Deny
Boundary	Sandbox × Approvals	jeder Tool-Call	was technisch geht
Org	Managed requirements	Admin-Policy	Full Access sperren

{width=90%}

Faustregel: Was du bitten kannst → Memory/Skill. Was nie passieren darf → Hook, Rule oder engere Sandbox. MCP erweitert die Tool-Oberfläche – es hebt Sandbox und Approvals nicht auf.

---

5.2 MCP – externe Tools andocken

MCP (Model Context Protocol) hängt Server an Codex: STDIO (lokaler Prozess) oder Streamable HTTP (URL + Auth). CLI, IDE und Desktop teilen dieselbe Config-Schicht.

{width=90%}

CLI und Config

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
codex mcp login <server-name>   # OAuth, wo unterstützt

In der TUI: /mcp (optional verbose).

# ~/.codex/config.toml oder trusted .codex/config.toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"  # Token nur in Env

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]  # nach enabled_tools
default_tools_approval_mode = "prompt"
enabled = true

Wichtige Keys (Kurz; Reference bei Drift):

Key	Rolle
command / args / env	STDIO-Server
url	HTTP-Server
bearer_token_env_var	Token aus Env – nie committen
enabled / required	aus / hart failen bei Init-Fehler
enabled_tools / disabled_tools	Allow/Deny der Tool-Liste
default_tools_approval_mode	u. a. auto, prompt, writes, approve
startup_timeout_sec / tool_timeout_sec	Timeouts

Vorlage: vorlagen/config.mcp.toml.

Achtung: MCP-Tools mit Side-Effects und destruktiven Annotationen brauchen Approval wie andere riskante Aktionen. Ein Docs-Server ist harmloser als ein Server mit Shell oder Cloud-Write – behandle MCP als Angriffsfläche (Prompt Injection über Tool-Output, zu weite Tokens).

Jetzt selbst machen

# Beispiel: nur listen, was schon da ist
codex mcp list

In einer Session:

/mcp

{width=90%}

---

5.3 Skills – Workflows on demand

Ein Skill ist ein Ordner mit SKILL.md (Pflicht: Frontmatter name + description) plus optional scripts/, references/, assets/. Codex lädt zur Discovery vor allem Metadaten; den vollen Body oft erst bei Aktivierung – progressive disclosure gegen Context-Bloat.

.agents/skills/verify/SKILL.md     # Projekt (Repo-Kette: CWD → Root)
~/.agents/skills/…                 # User (persönlich, repo-übergreifend)
# Admin/System: /etc/codex/skills bzw. mit Codex gebündelt – siehe Build-Skills-Doku

Skills liegen nicht unter CODEX_HOME (~/.codex). CODEX_HOME steuert Config, History, Hooks-Datei, Rules – Skills-Discovery liest die .agents/skills- und Admin-Pfade oben. Einzelne Skills abschalten geht über [[skills.config]] in ~/.codex/config.toml (Pfad zur SKILL.md + enabled = false).

Minimal:

---
name: verify
description: >-
  Run lint and unit tests for this repository.
  Use when asked to verify, check tests, or before commit.
---

# Verify

1. Test-Command aus `AGENTS.md` (z. B. `pytest -q`).
2. Lint, falls im Repo definiert.
3. Fehler mit Datei:Zeile zusammenfassen.
4. Nicht committen/pushen, außer explizit verlangt.

Buch-Vorlage: vorlagen/skills/verify/SKILL.md – an AGENTS.md dieses Repos anpassen.

In der Session: /skills zum Durchsuchen und Einbinden. Gute description = Routing-Vertrag („wann nutzen?“), nicht Marketing.

Skills ja	Skills nein (eher Hook/Rule)
wiederholbare Prozedur	absolute Verbote
Team-Workflow mit Scripts	OS-Boundary
spart Prompt-Copy-Paste	muss bei jedem Tool-Call greifen

---

5.4 Hooks – Lifecycle erzwingen

Hooks injizieren deterministische Scripts in die Agent-Schleife. Viele Features steuerst du unter [features] in der Config; Defaults können je Version driften – bei Zweifel /debug-config oder Config-Reference.

[features]
hooks = true   # oft Default an; false schaltet Hooks ab
# multi_agent / agents: Subagents – oft Default an (siehe 5.5)

Fundorte (alle greifenden Quellen werden gemerged, nicht „ersetzt“):

• ~/.codex/hooks.json bzw. inline [hooks] in User-config.toml
• trusted <repo>/.codex/hooks.json / Project-config.toml
• Plugin-bundled Hooks
• Managed requirements.toml (Org)

Events (Auswahl):

Wann	Events
im Turn	PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, PreCompact, PostCompact, Stop, …
Start	SessionStart, SubagentStart
Ende	SessionEnd (Hauptthread)

Beispiel-Struktur (offizielle Form – Keys/Schema der Doku folgen):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "timeout": 30,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

Matcher filtert u. a. Tool-Namen (Bash, apply_patch / Edit|Write, MCP-Namen). PreToolUse kann deny/rewrite; PermissionRequest allow/deny für Approvals; PostToolUse kann Feedback liefern, macht Side-Effects nicht rückgängig.

Achtung: Nicht-managed Command-Hooks müssen reviewed und trusted werden (/hooks). Geänderte Hooks sind untrusted, bis du sie freigibst. Managed Hooks kann der User nicht abschalten. --dangerously-bypass-hook-trust nur in kontrollierter Automation.

Vorlagen im Repo (vorlagen/hooks/): hooks.json-Form wie oben, Scripts unter .codex/hooks/scripts/. Nach dem Kopieren: /hooks reviewen und freigeben. Scripts: absolute oder git-root-relative Pfade (git rev-parse --show-toplevel), weil CWD ein Subdir sein kann.

---

5.5 Subagents – Kontext-Ventil

Subagents lagern laute Arbeit (Explore, Logs, parallele Review-Aspekte) aus dem Hauptthread aus und liefern Zusammenfassungen zurück. Feature: multi_agent (oft Default an).

{width=90%}

Review this branch with parallel subagents.
Spawn one for security risks, one for test gaps, one for maintainability.
Wait for all three, then summarize by category with file references.

In der CLI ist /agent der primäre Einstieg: Threads inspizieren und wechseln (Labels wie „Subagents“ in der UI können driften). Approvals können von Neben-Threads kommen – Overlay zeigt die Quelle.

Built-ins (Namen driftfähig): u. a. default, worker, explorer. Custom agents lädt Codex als TOML-Dateien – nicht als freies Markdown:

Form	Rolle
~/.codex/agents/*.toml oder trusted .codex/agents/*.toml	geladene Custom agents (Runtime)
Markdown-Briefing (z. B. Buch-Vorlage)	Inhalt entwerfen; manuell in TOML übernehmen oder als Prompt nutzen

# .codex/agents/reviewer.toml   ← Datei-Format der Runtime
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review like an owner. Prioritize correctness and security.
No style-only nits. Cite files. Prefer read over rewrite.
"""

Pflichtfelder: name, description, developer_instructions. Optional: model, sandbox_mode, eigene mcp_servers, skills.config, … Global unter [agents] (Defaults laut Doku oft an):

[agents]
# enabled = true   # multi-agent Tools; Default typisch true
max_concurrent_threads_per_session = 6
# default_subagent_model = "…"
# default_subagent_reasoning_effort = "…"

Subagents erben die aktuelle Sandbox/Approval des Parents (inkl. Session-Overrides und /permissions). Schreibende Parallelität = Merge-Konflikte und Review-Last – lieber read-heavy parallelisieren.

Konzept-Briefing (Inhalt → TOML oder Prompt, nicht 1:1 als Agent-Datei laden): vorlagen/agents/security-reviewer.agent.md.

---

5.6 Plugins

Ein Plugin bündelt Skills, optional MCP-Mappings und Hooks in ein installierbares Paket (Manifest unter .codex-plugin/plugin.json o. Ä. – Packaging-Doku).

codex plugin marketplace add owner/repo   # Quellen: Doku
codex plugin list
codex plugin add <plugin>
codex plugin remove <plugin>

In der Session: /plugins. User-Config kann Plugin-MCP und Tool-Policy nachziehen (plugins."<id>".mcp_servers.…). Plugin-Hooks brauchen trotzdem Trust-Review.

Skeleton: vorlagen/plugins/team-baseline/.

Plugin ja	Eher einzeln
Team-Standard wiederverwenden	einmaliger Skill
Skills + MCP + Hooks zusammen	nur eine MCP-Zeile

---

So baust du das nach

1. Härte entscheiden: Memory vs. Skill vs. Hook vs. Sandbox.
2. Optional einen read-only MCP-Server (Docs) andocken; /mcp prüfen.
3. Skill verify aus der Vorlage ins Projekt legen; /skills.
4. Optional PreToolUse-Guard für destruktive Shell – trusten via /hooks.
5. Einmal Subagent-Review-Prompt fahren; Diff der Findings gegen eigenen /diff.

Jetzt selbst machen (todo-cli)

cd beispiele/todo-cli
mkdir -p .agents/skills/verify
# SKILL.md aus vorlagen/skills/verify anpassen (pytest -q aus AGENTS.md)
codex

/skills
# Skill verify wählen, dann:
Verify the project. Summarize only.

---

Häufige Fehler

Symptom	Ursache
MCP „tot“	Server disabled; Init-Timeout; OAuth fehlt; untrusted Project-Config
Skill wird nie gewählt	schwache description; zu viele Skills
Hook läuft nicht	untrusted Definition; Feature aus; matcher mismatch; Project untrusted
Subagent-Chaos	zu viele Writer parallel; kein Wait/Summary-Auftrag
Custom agent „unsichtbar“	Markdown statt TOML; untrusted Project-.codex/agents/; Name ≠ name-Feld
Context voll trotz Skills	zu viel in AGENTS.md statt Skills; Hook-additionalContext zu groß

Was du jetzt kannst

• Erweiterungen nach Härtegrad wählen
• MCP per CLI/TOML anbinden und Tool-Policy eng halten
• Skills mit guter description bauen und on-demand nutzen
• Hooks als erzwungene Lifecycle-Scripts einordnen (Trust, Matcher, Limits)
• Subagents per /agent steuern und Custom agents als TOML (nicht nur Markdown) skizzieren
• Plugins als Bundle vs. Einzelteile unterscheiden

Nächste Schritte

• Kapitel 6: Team-Baseline, codex exec, Cloud, Managed
• Kapitel 7: Context, Compact, Symptom→Fix
• Vorlagen unter vorlagen/ – Schema immer gegen aktuelle Doku halten

Primärquellen: MCP, Skills / Customization, Hooks, Subagents, Plugins.