# Agent Skills sind kein Markdown. Sie brauchen ein Qualitäts-Gate. Canonical URL: https://huecki.com/blog/agent-skills-qualitaets-gate/ Markdown URL: https://huecki.com/blog/agent-skills-qualitaets-gate.md Language: German Published: 2026-08-11 Updated: 2026-08-11 Author: Dominic Hückmann Topic: AI Agent Workflows - Agent topics: Agent Security, Context Engineering, Agent Evals - Tags: AI Agents, Agent Skills, Agent Evals, AI Security, Developer Workflow - Audience: Entwickler von Agent-Systemen, Teams mit Coding Agents, OpenClaw-Nutzer, Betreiber interner Skill-Registries - Concepts: agent-skills, skill-evals, supply-chain-security, trajectory-evaluation, runtime-permissions Thesis: Ein Skill ist erst gut, wenn er gegenüber keinem Skill reproduzierbar bessere Ergebnisse erzeugt, dabei innerhalb externer Rechte bleibt und seine Kosten, Annahmen und Fehler sichtbar macht. Content status: field-note ## Summary Ein praktisches Qualitäts-Gate für Agent Skills: Nutzen gegen eine No-Skill-Baseline messen, Aktivierung und Trajektorie prüfen, Rechte außerhalb des Skill-Texts binden und nur versionierte, überprüfbare Kandidaten promoten. ## Description Viele Agent Skills sind sicherer klingender Kontext-Matsch. Aktuelle Benchmarks zeigen, wie Teams Skills mit A/B-Evals, Traces, Security-Scans, Runtime-Rechten und Promotion Gates wirklich prüfen. ## Body Viele Agent Skills sehen aus, als hätte jemand ein paar gute Praktiken in Markdown gegossen. Der Agent soll erst planen. Dann gründlich recherchieren. Immer alle Fehler prüfen. Sich selbst reflektieren. Tests schreiben. Sicherheit beachten. Nach jeder Aufgabe lernen. Alles klingt vernünftig. Zusammen wird daraus oft **Matschebrei**: zu breit, widersprüchlich, teuer, schwer auslösbar und unmöglich sauber zu evaluieren. Das Problem ist nicht nur schlechter Prompt-Stil. Ein Skill verändert Agentenverhalten. Er beeinflusst, wann ein Agent aktiv wird, welchen Kontext er lädt, welche Tools er auswählt, was er als Erfolg betrachtet und ob er bei einem Fehler stoppt oder weitermacht. Ein Skill ist deshalb keine Dokumentation. Er ist eine **Verhaltensabhängigkeit**. Und Verhaltensabhängigkeiten brauchen ein Qualitäts-Gate. ## Die kurze Version Ein Skill kommt nur in die aktive Library, wenn er vier Dinge belegt: ```txt 1. Er löst eine klar begrenzte Aufgabe. 2. Er ist reproduzierbar besser als kein Skill. 3. Er bleibt innerhalb extern erzwungener Rechte. 4. Er ist versioniert, beobachtbar und rückrollbar. ``` Eine valide `SKILL.md`, ein grüner LLM-Review und ein erfolgreicher Demo-Run reichen dafür nicht. ## Die Forschung widerspricht dem Skill-Hype Die aktuelle Evidenz ist interessant, weil sie in zwei Richtungen zeigt. [SkillsBench](https://arxiv.org/abs/2602.12670) evaluiert die aktuelle Benchmark-Version mit 87 Aufgaben, deterministischen Verifiern und gepaarten Läufen mit und ohne kuratierte Skills. Im Mittel steigt die Erfolgsrate von 33,9 auf 50,5 Prozent. Das sind 16,6 Prozentpunkte. Skills können also sehr nützlich sein. Aber derselbe Benchmark berichtet auch, dass fokussierte Skills mit höchstens drei Modulen größere, erschöpfende Bundles schlagen. Mehr Anleitung ist nicht automatisch mehr Fähigkeit. [SWE-Skills-Bench](https://arxiv.org/abs/2603.15401) liefert das wichtigere Gegengewicht für Coding Agents. Die Autoren testen 49 öffentliche Software-Engineering-Skills auf echten, versionierten GitHub-Repositories mit ausführbaren Acceptance Tests. Das Ergebnis ist ernüchternd: - 39 von 49 Skills verbessern die Pass Rate überhaupt nicht. - Der durchschnittliche Gewinn liegt nur bei 1,2 Prozent. - Der Tokenverbrauch steigt in einzelnen Fällen um bis zu 451 Prozent, ohne dass die Erfolgsrate steigt. - Drei Skills verschlechtern die Ergebnisse, weil ihre Anleitung nicht zur Projektversion passt. Das ist die Definition von Skill-Matschebrei: zusätzlicher Kontext, zusätzliche Sicherheit im Ton, zusätzliche Kosten – aber kein nachgewiesener Nutzen. ## Welche Skills helfen tatsächlich? Die Gewinner aus den Benchmarks sind keine allgemeinen Rollenbeschreibungen. Es sind enge Fachverfahren, die dem Modell fehlendes Wissen, eine exakte Berechnung oder einen überprüfbaren Werkzeugablauf geben. In SWE-Skills-Bench erzielen nur sieben der 49 untersuchten Coding-Skills überhaupt einen positiven Effekt: - `risk-metrics-calculation` verbessert die Pass Rate um 30 Prozentpunkte und benötigt zugleich rund 35 Prozent weniger Tokens. - `similarity-search-patterns` gewinnt 10 Punkte bei 32 Prozent weniger Tokens. - `distributed-tracing` gewinnt 7,7 Punkte bei 30 Prozent weniger Tokens. - `istio-traffic-management` gewinnt 7,1 Punkte bei 22 Prozent weniger Tokens. - `gitlab-ci-patterns` gewinnt 14,3 Punkte, benötigt dafür aber 59 Prozent mehr Tokens. - `prompt-engineering-patterns` gewinnt 10 Punkte bei 46 Prozent mehr Tokens. - `tdd-workflow` gewinnt 7,1 Punkte, bleibt mit 28,6 Prozent Pass Rate aber schwach und verbraucht 79 Prozent mehr Tokens. Erfolgsgewinn und Effizienz sind deshalb zwei getrennte Metriken. Ein Skill kann Aufgaben häufiger lösen und trotzdem wirtschaftlich fragwürdig sein. Er kann auch die gleiche Erfolgsrate erreichen, aber den Weg verkürzen. `python-resilience` und `v3-performance-optimization` verbesserten im Benchmark beispielsweise keine bereits perfekte Pass Rate, reduzierten den Tokenverbrauch aber um 77,6 beziehungsweise 56,4 Prozent. Das Gegenbeispiel ist `service-mesh-observability`: gleiche perfekte Pass Rate mit und ohne Skill, aber 451 Prozent mehr Tokens mit Skill. Der Agent arbeitet nicht besser. Er arbeitet nur länger. Außerhalb klassischer Softwareentwicklung wird das Muster noch deutlicher. Die größten Zugewinne in SkillsBench entstehen bei kleinen Kombinationen spezialisierter Verfahren: - Keyframe-Extraktion, Bildbearbeitung und Object Detection für Videoanalyse: plus 85,7 Prozentpunkte. - PDF-Extraktion und Excel-Pivot-Erstellung: plus 85,7 Prozentpunkte. - USGS-Daten, NWS-Grenzwerte und Hochwassererkennung: plus 77,1 Prozentpunkte. - 13F-Analyse und Fuzzy Search für Fondsnamen: plus 74,3 Prozentpunkte. Die Grundessenz ist damit ziemlich eindeutig: > **Gute Skills sind kleine ausführbare Fachverfahren – keine allgemeinen Rollenbeschreibungen.** Also eher: „Berechne VaR exakt nach diesen Formeln“ oder „Extrahiere Keyframes mit diesem geprüften Verfahren“ als: „Du bist ein Senior Developer und beachtest Best Practices.“ Das erklärt auch, warum umfassende Dokumentationspakete schlechter abschneiden. Sie erweitern den Entscheidungsraum, konkurrieren mit dem eigentlichen Task-Kontext und verankern den Agenten möglicherweise auf veralteten Beispielen. Ein enger Skill reduziert Unsicherheit. Ein breiter Skill erzeugt neue. ## Ein valider Skill kann trotzdem schlecht sein Die [Agent Skills Specification](https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx) ist bewusst schlank. Erforderlich sind im Kern `name` und `description`. Felder wie `compatibility` und `allowed-tools` sind optional; `allowed-tools` ist experimentell und wird nicht von jeder Runtime gleich interpretiert. Das Format löst Portabilität. Es löst nicht Qualität. Der offizielle Validator `skills-ref validate` kann Frontmatter, Namen und Formatregeln prüfen. Er kann nicht wissen, ob der Skill: - veraltete Paketversionen empfiehlt, - unnötig oft aktiviert wird, - einen schlechteren Workflow als das Basismodell erzwingt, - bei Fehlern in Schleifen gerät, - zu viel Kontext lädt, - oder dem Agenten Autorität einredet, die er nicht haben sollte. Schema-valid ist kein Qualitätsurteil. ## Das Qualitäts-Gate Ich würde Skills wie kleine Software-Releases behandeln. ### 1. Der Skill braucht einen Vertrag Ein guter Skill beantwortet nicht nur, **wie** etwas gemacht wird. Er macht auch klar, wann er zuständig ist und wann nicht. ```yaml name: postgres-migration-review owner: platform-team source: github.com/example/skills@8af31c2 status: experimental purpose: Prüft eine vorbereitete PostgreSQL-Migration vor dem Merge. activate_when: - Migration oder Schemaänderung liegt als Diff vor do_not_activate_when: - Agent soll die Migration selbst produktiv ausführen inputs: - repository snapshot - migration diff - target postgres version outputs: - review report with blocking findings permissions: - repository-read - local-test-container forbidden: - production database - outbound messaging - secret stores verification: - schema applies to disposable database - rollback path is tested known_failures: - extension-specific migrations need manual review eval_suite: evals/postgres-migration-review last_reviewed_at: 2026-08-11 expires_at: 2026-11-11 rollback: previous-approved-hash ``` Wichtig: `permissions` im Skill sind nur eine Behauptung. Die Runtime muss diese Grenze außerhalb des Skill-Texts durchsetzen. ### 2. Teste mit und ohne Skill Der wichtigste Skill-Eval ist banal: ```txt Gleiche Aufgabe + gleicher Ausgangszustand + gleiches Modell + gleicher Harness + gleiches Budget + mehrere Trials Variante A: ohne Skill Variante B: mit Skill ``` Dann vergleichst du: Der Skill gewinnt nur, wenn sein **marginaler Nutzen** positiv ist. Nicht wenn die Antwort fachlicher klingt. Nicht wenn der Agent den Skill lobt. Nicht wenn ein zweites LLM den Text mit 8,7 von 10 bewertet. ### 3. Teste auch, wann der Skill schweigen muss Skill-Auswahl ist ein eigener Fehlerkanal. [Under the Hood of SKILL.md](https://arxiv.org/abs/2605.11418) zeigt, dass bereits Beschreibung und Metadaten Discovery und Auswahl manipulieren können. Kurze semantische Trigger erhöhten in den Experimenten die Sichtbarkeit adversarialer Skills; Description-Framing verzerrte die Auswahl zwischen funktional ähnlichen Kandidaten. Deshalb braucht jeder Skill negative Kontrollen: ```txt Soll aktivieren: - explizite PostgreSQL-Migration prüfen - Schema-Diff auf Rollback-Risiko untersuchen Soll nicht aktivieren: - normale SQL-Abfrage erklären - SQLite-Test reparieren - Produktionsmigration ausführen - allgemeines Code Review ``` Ein Skill, der bei jeder halbwegs verwandten Aufgabe Kontext lädt, ist kein Generalist. Er ist Rauschen. ### 4. Prüfe Artefakt, Trajektorie und Outcome getrennt [SkillLearnBench](https://arxiv.org/abs/2604.20087) schlägt genau diese Dreiteilung für automatisch gelernte Skills vor: 1. **Skill-Qualität:** Ist der erzeugte Verhaltensbaustein klar, vollständig und intern konsistent? 2. **Execution Trajectory:** Nutzt der Agent den Skill sinnvoll, reagiert er auf Tool-Feedback und erholt er sich von Fehlern? 3. **Task Outcome:** Ist das tatsächliche Ergebnis korrekt? Das Paper findet außerdem, dass externe Rückmeldung über mehrere Iterationen helfen kann, während reines Selbstfeedback zu rekursivem Drift führt. Ein Agent kann also Skill-Kandidaten schreiben. Er sollte sie nicht selbst freigeben. Automatisch erzeugte Skills gehören zuerst in **Quarantäne**. ## Security ist ein separates Gate Ein Skill kann nützlich und gefährlich sein. Er kann auch sicher und nutzlos sein. Darum dürfen wir Security und Qualität nicht vermischen. Ein technischer Report über [reale Bedrohungen im Agent-Skill-Ökosystem](https://arxiv.org/abs/2605.28588) untersuchte 3.984 Skills und fand 76 bestätigte schädliche Payloads. 13,4 Prozent enthielten im untersuchten Snapshot mindestens ein Problem mit kritischem Schweregrad. Aber ein einzelner Scanner reicht nicht. [ClawHub Security Signals](https://arxiv.org/abs/2606.01494) vergleicht VirusTotal, statische Heuristiken und semantische Analyse auf 67.453 Skill-Versionen. Nur 0,69 Prozent wurden von allen drei Scanner-Familien markiert; 81,9 Prozent der markierten Skills wurden nur von einer Familie gefunden. Die Scanner sehen unterschiedliche Angriffsflächen: - Malware-Reputation erkennt gebündelte Schadsoftware. - Statische Analyse erkennt verdächtige Befehle, Secrets und Code-Muster. - Semantische Analyse erkennt manipulative Arbeitsanweisungen und Agentenrisiken. - Sandbox- und Trace-Prüfung zeigt, was der Skill tatsächlich auslöst. [SkillGate](https://arxiv.org/abs/2607.25619) liefert dafür ein praktisches Triage-Muster: günstige Regex-Prefilter markieren verdächtige Stellen; nur diese Snippet-Fenster gehen an einen LLM-Judge. Im eigenen 1.650-Skill-Benchmark berichtet das Paper 77 Prozent weniger LLM-Input-Tokens als beim Full-File-Screening. Das ist ein guter Filter. Es ist kein Sicherheitszertifikat. ## Eine brauchbare Toolchain Für ein kleines Team würde ich heute so anfangen: ```txt skills-ref validate -> Cisco Skill Scanner -> disposable container / VM -> positive + negative canaries -> paired A/B evals -> trace + outcome review -> human promotion -> exact commit pin ``` Der [Cisco AI Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner) ist aktuell die direkt brauchbarste offene Intake-Komponente, die ich in dieser Recherche gefunden habe. Er kombiniert statische Regeln, YARA, Bytecode- und Datenflussanalyse sowie optionale LLM-Prüfung. Er unterstützt Pre-Commit, GitHub Actions und SARIF. Ein CI-Aufruf kann so aussehen: ```bash skill-scanner scan-all ./skills \ --recursive \ --use-behavioral \ --fail-on-severity high \ --format sarif \ --output skill-scan.sarif ``` Das Projekt weist selbst auf die richtige Grenze hin: „No findings“ bedeutet nicht „sicher“. False Positives und False Negatives bleiben möglich; produktive oder privilegierte Skills brauchen weiterhin menschliches Review und Threat Modeling. Für Registry-Installationen sind außerdem `inspect` und Version Pinning Pflicht. [ClawHub](https://github.com/openclaw/clawhub) unterstützt Inspektion vor der Installation, Changelogs und gepinnte lokale Versionen. `latest` gehört nicht automatisch in eine Runtime mit Shell, Browser, Messaging, Secrets oder Produktionszugriff. ## Die Promotionsregel Ich würde nur eine harte Regel verwenden: ```txt Ein Skill wird promotet, wenn er gegenüber keinem Skill reproduzierbar bessere Outcomes liefert, keinen Hard Fail erzeugt, innerhalb seines Kostenbudgets bleibt und keine Rechte außerhalb seiner Runtime-Policy nutzt. ``` Hard Fails sind unabhängig vom Gesamtscore: - unerlaubter Secret-Zugriff - unerklärte Netzwerkziele - externe Nachricht ohne Freigabe - Produktionsänderung aus einer Testaufgabe - versteckte dauerhafte Memory-Änderung - Manipulation der eigenen Evals oder Freigaberegeln - Erfolg behauptet, obwohl der Systemzustand nicht stimmt Die Zukunft gehört nicht Agenten mit maximal vielen Skills. Sie gehört Agenten mit einer kleinen Library aus fokussierten, getesteten, versionierten und begrenzten Verhaltensbausteinen. Das ist weniger spektakulär als „der Agent lernt alles selbst“. Es ist aber der Unterschied zwischen einer Sammlung überzeugend klingender Markdown-Dateien und einem Agent-System, dem man echte Arbeit geben kann. ## Quellen und weiterführende Arbeiten ### Qualität und Evaluation - [SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks](https://arxiv.org/abs/2602.12670) - [SWE-Skills-Bench: Do Agent Skills Actually Help in Real-World Software Engineering?](https://arxiv.org/abs/2603.15401) - [SkillLearnBench: Benchmarking Continual Learning Methods for Agent Skill Generation](https://arxiv.org/abs/2604.20087) - [Agent Skill Evaluation and Evolution: Frameworks and Benchmarks](https://arxiv.org/abs/2606.11435) - [Organizing, Orchestrating, and Benchmarking Agent Skills at Ecosystem Scale](https://arxiv.org/abs/2603.02176) - [OpenClaw-Skill: Collective Skill Tree Search for Agentic Large Language Models](https://arxiv.org/abs/2606.16774) ### Angriffe und Security-Evaluation - [Skill-Inject: Measuring Agent Vulnerability to Skill File Attacks](https://arxiv.org/abs/2602.20156) - [RouteGuard: Internal-Signal Detection of Skill Poisoning in LLM Agents](https://arxiv.org/abs/2604.22888) - [Under the Hood of SKILL.md: Semantic Supply-chain Attacks](https://arxiv.org/abs/2605.11418) - [POISE: Position-Aware Undetectable Skill Injection](https://openreview.net/pdf?id=RcIyEkbuPj) - [SkillGate: Cost Efficient Runtime Malicious Skill File Detection](https://arxiv.org/abs/2607.25619) - [SkillSieve: A Hierarchical Triage Framework](https://arxiv.org/abs/2604.06550) - [Agent Skill Security: Threat Models, Attacks, Defenses, and Evaluation](https://arxiv.org/abs/2607.13987) - [ClawHub Security Signals](https://arxiv.org/abs/2606.01494) - [Exploring the Emerging Threats of the Agent Skill Ecosystem](https://arxiv.org/abs/2605.28588) ### Spezifikation und Tools - [Agent Skills Specification](https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx) - [Cisco AI Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner) - [ClawHub Registry](https://github.com/openclaw/clawhub) ## FAQ ### Wie erkennt man einen guten Agent Skill? Nicht am Schreibstil. Ein guter Skill verbessert in gepaarten Tests reproduzierbar das Ergebnis, aktiviert nur bei passenden Aufgaben, bleibt innerhalb externer Rechte und hat Quelle, Version, Owner, Evals und Rollback. ### Reicht ein Security-Scanner für Agent Skills? Nein. Scanner suchen nach bekannten oder wahrscheinlichen Risiken. Sie beweisen weder Sicherheit noch Nutzen. Funktionale A/B-Evals, Sandbox-Runs und Trajectory Reviews bleiben notwendig. ### Sollten Agents ihre Skills selbst schreiben dürfen? Sie dürfen Kandidaten erzeugen. Selbstgenerierte Skills sollten aber zunächst quarantiniert, mit externer Evidenz getestet und erst durch eine unabhängige Promotion-Entscheidung aktiviert werden. ### Was ist der wichtigste Skill-Eval? Dieselbe realistische Aufgabe mehrfach mit und ohne Skill unter identischem Modell, Harness, Budget und Ausgangszustand ausführen und Ergebnis, Trajektorie, Kosten und Nebenwirkungen vergleichen. ## Related - Zeigt, warum automatisch erzeugte Skills Provenance, Quarantäne und eine Registry brauchen.: automatisch-generierte-agent-skills-supply-chain - Ordnet Skills und Plugins als versionierte Verhaltensabhängigkeiten ein.: agent-plugins-npm-fuer-agent-verhalten - Überträgt Release Engineering auf Änderungen am gesamten Agent Harness.: your-agent-harness-needs-a-release-process ## Source References - [SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks](https://arxiv.org/abs/2602.12670) (paper) - [SWE-Skills-Bench: Do Agent Skills Actually Help in Real-World Software Engineering?](https://arxiv.org/abs/2603.15401) (paper) - [SkillLearnBench: Benchmarking Continual Learning Methods for Agent Skill Generation](https://arxiv.org/abs/2604.20087) (paper) - [Under the Hood of SKILL.md: Semantic Supply-chain Attacks](https://arxiv.org/abs/2605.11418) (paper) - [SkillGate: Cost Efficient Runtime Malicious Skill File Detection](https://arxiv.org/abs/2607.25619) (paper) - [ClawHub Security Signals](https://arxiv.org/abs/2606.01494) (paper) - [Agent Skills specification](https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx) (specification) - [Cisco AI Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner) (repository)