shimo4228/agent-stocktake

agent-stocktake – Qualitätsprüfung von Agenten-Definitionen

Bewerte jede Agenten-Definition unter <harness>/agents/*.md und weise ein Urteil zu: Keep / Improve / Update / Merge / Demote to skill / Dissolve / Retire. Die Prüfeinheit ist die Datei, aber die Kosteneinheit ist auf zwei Ebenen aufgeteilt – diese Aufteilung ist der Grund, warum dieser Skill als drittes Geschwister neben skill-stocktake und rules-stocktake existiert.

Designhinweis – das hybride Kostenmodell. Die Kosten eines Skills sind Trigger-Verschmutzung (probabilistisches Auslösen verschlechtert die Auswahl); die Kosten einer Regel sind Residenz (immer geladen). Ein Agent hat beides gleichzeitig: Seine description wird in jede Sitzung über die Liste der „Verfügbaren Agententypen“ injiziert (Residenz, wie eine Regel), während sein Körper nur geladen wird, wenn der Agent aufgerufen wird (Invocation, wie ein Skill – aber ausgelöst durch Claudes Delegationsurteil, nicht durch Übereinstimmung der Beschreibung mit den Worten des Benutzers). Die Beschreibung wird also auf Residenzdichte und der Körper auf Aufrufqualität geprüft, mit unterschiedlichen Fragen für jede Ebene.

Designhinweis 2 – genehmigte Änderungen werden von diesem Skill selbst auf dem Apply-Branch angewendet. Gleiche Begründung wie bei rules-stocktake: Es gibt keine Verbesserungs-Engine für Agenten-Definitionen, und der Korpus ist klein genug, um in einem Kontext gelesen zu werden – Delegation wäre Overengineering. Die Ausnahme ist Demote to skill (das Erstellen eines Skills ist Aufgabe des Skill-Schreibers).

Wurzeln. <harness> unten ist der Harness, den diese Prüfung abdeckt: standardmäßig ~/.claude oder .claude/ eines Repositorys, wenn der Skill harness-stocktake im Projektmodus ausgeführt wird (seine Roots-Abschnitt bildet die Pfade ab, benennt Beweise, die dort n/a sind, und sagt, welche Konventionsprüfungen gelten). Das Ledger <ledger> gehört zu diesem Harness: ${CLAUDE_SKILL_DIR}/results.json, wenn sich das Verzeichnis dieses Skills innerhalb von <harness> befindet (der Harness trägt seine eigene Kopie des Skills), ansonsten <harness>/stocktake/agent-stocktake.json (ein installiertes Plugin oder Projektmodus). In beiden Fällen wird es zusammen mit den anderen Änderungen des Harness auf dem Apply-Branch committed.

Modi ($ARGUMENTS)

Argument	Verhalten
none / full	Jede Agenten-Definition lesen und bewerten (Standard)
changed	Nur Dateien neu bewerten, deren mtime neuer ist als <ledger>s evaluated_at; die restlichen aus dem Ledger übernehmen

changed erkennt Änderungen inline (kein Skript):

Pfade unten beginnen bei ${CLAUDE_SKILL_DIR}, dem Verzeichnis, das diese SKILL.md enthält; ein Agent, der die Variable nicht ersetzt, liest sie als dieses Verzeichnis.

find <harness>/agents -name "*.md" -newermt "$(jq -r .evaluated_at "<ledger>")"

Wie bei rules-stocktake laufen die Integritätsprüfungen der Phase 1 immer über die gesamte Menge – die Außerdienststellung eines Skills oder Hooks unterbricht stillschweigend einen Verweis innerhalb eines unveränderten Agentenkörpers, und die mtime kann das nicht erkennen. Jeder Agent, dessen Referenzprüfung (Schritt 3 unten) neu fehlschlägt, kommt zur Neubewertungsmenge hinzu. Das Skript hat auch keinen changed-Modus, und zwar aus einem anderen Grund: Die nahezu identischen Paare und die Residenzsumme sind Set-Eigenschaften, sodass ein partieller Korpus falsche Zahlen liefern würde, nicht weniger.

Phase 1 – Beweise, Inventar, Nutzung

Schritt 1 – Das Beweisskript ausführen (nicht von Hand zählen)

uv run --frozen --project "${CLAUDE_SKILL_DIR}" \
       --directory "${CLAUDE_SKILL_DIR}" \
       python scripts/agent_evidence.py --root <harness>

Beweismodus: JSON auf stdout, Exit 0 unabhängig von der Anzahl der Funde (Exit 2 nur, wenn der Korpus nicht lesbar ist). Es misst und zählt; es weist niemals ein Urteil zu.

Übertrage das JSON in Funde – niemals von Hand neu messen. Was es liefert:

JSON-Feld	Ersetzt
desc_words / body_lines / total_desc_words	den wc -w / wc -l-Durchlauf
tools.items[].status + registry.known_tools	builtin / unverified / mcp. unverified bedeutet „nicht in der datierten Liste des Skripts“, nicht „existiert nicht“ – du hältst das Live-Tool-Register und das Skript nicht, also bestätige ein unverified anhand deiner eigenen Werkzeugliste, bevor du es als Update-Beweis bezeichnest. registry.known_tools.as_of ist das Datum dieser Liste (null, wenn --known-tools sie ersetzt hat)
tools.items[].server_in_config + registry.mcp_config_files	Kein Urteil. Es sagt nur, ob der Server in den aufgeführten lokalen Konfigurationsdateien erscheint – Server, die von einem Connector bereitgestellt werden, erscheinen dort nie, also ist ein false nicht „außer Dienst gestellt“. null bedeutet, dass keine Konfigurationsquelle analysiert wurde. Überprüfe den status jeder Quelle, bevor du dies überhaupt verwendest; ein false neben einer nicht-ok-Quelle ist kein Beweis
unreadable	Dateien, die der Scan nicht öffnen konnte, mit Grund. Nicht leer bedeutet, dass der Scan unvollständig ist – benenne sie und behebe dies, bevor du eine Gesamtzahl angibst, da eine Unterdrückungsanweisung innerhalb einer nicht lesbaren Datei jetzt als nicht vorhanden zertifiziert ist
tools_unparsable	Agenten, deren tools:-Zeile nicht analysiert werden konnte (z. B. YAML-Flow-Stil). Ihre items ist [], was identisch mit einem Agenten ohne tools:-Schlüssel aussieht – d. h. uneingeschränkt. Das ist es nicht; die Liste wurde einfach nicht gelesen
description_near_duplicates	die Prüfung auf nahezu identische Beschreibungen; Zwillinge teilen den Delegationsverkehr, daher speist jedes Paar die Überlappungsfrage der Stufe 1
suppression_candidates	Zeilennummerierte Kandidaten für die Unterdrückungsfrage der Stufe 1 (der Katalog ist zweisprachig, da der Korpus es ist)
always_never_candidates	Zeilennummerierte Kandidaten für die Überbeschränkungsfrage, nur Körper – eine Beschreibung ist ein Delegationsauslöser, keine Anweisung an den Agenten

Die letzten beiden sind Kandidaten, keine Funde – lies jede genannte Zeile, bevor du sie aufschreibst. Der Katalog ist auch ein Boden, keine Volkszählung: Er enthält fünf Formulierungen aus einem Korpus, sodass eine Unterdrückung, die auf andere Weise geschrieben wurde („Überspringe alles, bei dem du dir unsicher bist“, „Vermeide Funde, die nur Rauschen wären“) in keinem JSON-Feld erscheint. Lies weiter für diese; eine leere Liste ist kein Freibrief.

Die gemessenen False-Positive-Verhältnisse leben außerhalb dieser Datei, sodass dieser Schritt keine Zahlen enthält, die veralten.

Schritt 2 – Die Gatter lesen, die den Rest bereits besitzen

Drei Prüfungen bleiben außerhalb des Skripts, weil sie in einem Harness mit einem Lint-Gatter (<harness>/scripts/hooks/harness_lint.py) diesem Gatter gehören. Lies seine Ausgabe, wenn sie existiert; ohne sie, führe die drei Prüfungen mit Read / Grep durch:

• Frontmatter wird geparst und enthält name, description, origin, model, und model ist ein Alias → das lint_agents des Lint-Skripts (im Harness des Autors läuft es in .claude/verify.sh und dem Pre-Commit-Hook). Ein fehlender Origin, wenn der Harness die Origin-Konvention angibt, ist immer noch ein Integritätsfund, der in Improve mündet.
• name entspricht dem Dateinamenstamm → dasselbe lint_agents. Es lässt kein Urteil zu und das Delegationsregister hängt davon ab, also gehört es zu einem Gatter, das einen Commit verhindert – nicht zu einem Beweis, den ein Leser transkribieren kann oder nicht. Ein Fund hier ist ein blockierter Commit, kein Stocktake-Urteil.
• Markdown-Links innerhalb von Agentenkörpern sind auflösbar → dasselbe Skripts lint_markdown_links (sein Gültigkeitsbereich umfasst agents).

Schritt 3 – Bare-Path-Referenzen auflösen (die eine Prüfung, die sonst niemand besitzt)

lint_markdown_links sieht nur Link-Syntax, und skill-healths scan_refs.py scannt den Skills-Baum. Ein Pfad, der als Prosa innerhalb eines Agentenkörpers geschrieben ist (<harness>/hooks/foo.sh, skills/foo/SKILL.md), wird von keinem von beiden abgedeckt. Grep den Korpus danach und ls jeden einzelnen.

Schritt 4 – Inventar

Aufzählen mit Glob: <harness>/agents/*.md. Lies jede Datei in einen Kontext (der Korpus ist klein). Die Residenz- und Körperspalten stammen aus dem JSON von Schritt 1 – verlasse dich niemals auf in Dokumenten geschriebene Zahlen, einschließlich dieser.

Schritt 5 – Nutzungszahlen

Beweiseingabe: geringe Nutzung nominiert einen Kandidaten, und der Inhalt entscheidet über das Urteil. Wenn das Setup ein Agenten-Nutzungsprotokoll führt (<harness>/metrics/agent-usage.jsonl; nicht vorhanden = Nutzung n/a), lies es inline (ein Nutzungsprotokollierungs-Hook wie log-agent-usage.sh hängt ein invoke-Ereignis pro Agent-Tool-Start an, geschlüsselt nach seinem agent-Feld, dessen Wert der subagent_type ist) und zähle die Ereignisse pro Agent über 7 / 30 / 90 Tage. Aggregiere mit einem Einzeiler python3/jq.

• Wenn das Protokoll fehlt oder sein erstes Ereignis jünger als 90 Tage ist, zeige die Nutzung als — (nicht gemessen) an. Zeige sie niemals als 0 an – nicht gemessen und nicht genutzt sind unterschiedliche Tatsachen.
• Zählungen sind untere Grenzen: Nur Starts des Agent (Task)-Tools werden erfasst. Workflow agent()-Worker, plugin-interne Verteilung und eingebaute Mechanismen, die den Tool-Aufruf umgehen, erreichen den Hook nicht. Ein wenig genutzter Agent tritt in Stufe 1 als Retire/Dissolve-Kandidat ein; sein Wert kann episodisch sein (z. B. Paper-Reviewer feuern nur in der Nähe einer Einreichung), also entscheidet der Inhalt.
• Protokoll existiert seit 2026-07-27; vor diesem Datum gibt es überhaupt keine Messung.

Gib das Scan-Ergebnis vorab an, indem du die Zählungen aus dem JSON von Schritt 1 nimmst: agents_total abzüglich allem in unreadable, das benannt werden muss, total_desc_words (die Residenzsteuer pro Sitzung der Auflistung), Integritätsfehler und ob die Nutzung messbar ist. Trage Fehler als vorberechnete Beweise in Stufe 1 ein.

Phase 2 – Bewertung (vollständig inline, ganzheitlich)

Lies jeden Körper, während du die gesamte Menge siehst.

Stufe 1 – Binärer Bildschirm (jeder Agent). Explizites Ja/Nein pro Element; zeige nur die Nein-Antworten an. Die ersten beiden Fragen prüfen die Beschreibungsebene (Residenz), der Rest die Körperschicht (Invocation):

• Verdient die Beschreibung ihre Residenz? – dicht, deutlich und auswahlermöglichend in der immer geladenen Auflistung; gibt an, wann zu delegieren UND wann nicht
• Ist die Beschreibung wahrheitsgemäß zum Körper? – was sie verspricht, tut der Körper (eine abweichende Beschreibung führt jede Sitzung fehl, selbst wenn der Körper in Ordnung ist)
• Ist der Körper frei von Unterdrückungsanweisungen? – beginne bei diesem Agenten suppression_candidates im JSON von Phase 1, behandelt gemäß Schritt 1. Was zählt: Konfidenzschwellen („Melde nur Funde, bei denen du ≥N% sicher bist“, „Weise jedem Fund eine Konfidenz zu und verwerfe die niedrigen“), Schweregradschwellen („nur hoher Schweregrad“), „sei konservativ“-Rahmungen. Die aktuelle Anleitung ist: Melde alles, filtere in einem separaten Durchlauf – eine Unterdrückungsanweisung wird buchstäblich befolgt und lässt stillschweigend Funde fallen. Ein Nein hier ist ein Verbessern-durch-Umkehrung-Kandidat: Schreibe die Anweisung in die entgegengesetzte Richtung um, niemals lösche einfach den Abschnitt (Löschen hinterlässt den unterdrückenden Rahmen; Umkehrung ersetzt ihn)
• Externe Kopie aktuell? – für einen Agenten, dessen origin ein externes Repo ist und dessen Körper eine wörtliche Kopie ist (z. B. ein eingebauter Überschrieb wie Explore), die Quellversion, die im führenden Kommentar des Körpers genannt wird, mit dem installierten Tool (claude --version) übereinstimmt; eine Abweichung ist ein Update (Diff gegen das Bundle und erneutes Kopieren). Die Unterdrückungs- und Überbeschränkungsfragen werden für solche Kopien übersprungen – der Körper stammt vom Anbieter, nicht von uns
• Frei von Überbeschränkungen vorheriger Generationen? – erschöpfende Schritt-für-Schritt- Verfahren für Urteile, die das aktuelle Modell nativ hält, wiederholte Betonung, ALWAYS/NEVER-Paare, die das umgebende Kontexturteil besitzen sollte. Phase 1s always_never_candidates lokalisiert die Tokens; zu entscheiden, ob ein Treffer eine Direktive ist oder lediglich die Worte zitiert, ist die Aufgabe dieser Frage
• Nicht vom Substrat absorbiert? – deckt der Harness jetzt die Aufgabe dieses Agenten nativ ab (native Überprüfungsmechanismen, Planmodus, eingebaute Slash-Befehle)? Absorption → Dissolve-Kandidat; die Behauptung muss ihren Absorbierer konkret benennen. Urteile mit der Achse frischer/reicher Kontext: Rollen, die von frischem Kontext profitieren (Überprüfung, adversarielle Verifikation, Essenz- Bewertung – Dekorrelation von den versunkenen Kosten des Vorschlagenden) leben legitimerweise in einem Subagenten; Rollen, die von reichem Kontext profitieren (Planung, Generierung, Implementierung – Benutzerabsicht, Einschränkungen im Gespräch) sind Hauptschleifenarbeit, also zählt für sie die Hauptschleife selbst als Absorbierer. Zwei zusätzliche Begründungen überschreiben legitimerweise den Pull des reichen Kontexts: ein Rendervertrag für fixierte Eingabe – der Aufrufer fixiert ein in sich geschlossenes Paket vor dem Aufruf, sodass Gesprächskontext nicht benötigt wird (Prompt-Forager, der absichtlich eine Zeile bekommt) – und Massenkontextisolierung – die Arbeit liest oder produziert ein Volumen, das den Hauptkontext verschmutzen würde (Researcher, ein Web-Research-Winkel pro Durchlauf)
• Technische Referenzen aktuell? – überprüfe bedingungslos jedes Artefakt, das der Körper nennt: ls jeden referenzierten Pfad, führe --help / Versionsprüfungen für benannte Befehle, Flags, Modellnamen und Werkzeuglisten durch. „Überprüfe, ob es veraltet aussieht“ ist verbotene Formulierung – die Bedingung ist, was verwässert; deterministisch überprüfbare Behauptungen erhalten deterministische Überprüfungen, jedes Mal
• Einzigartig innerhalb der Menge? – kein anderer Agent (oder Skill) besitzt dieselbe Aufgabe; ein dokumentierter Orchestrator→Sub-Agent-Split ist KEINE Überlappung

Acht Fragen und nicht mehr – weitere Zerlegung verschlechtert das ganzheitliche Urteil (siehe Referenzen).

Stufe 2 – Urteils-Stresstest (nur Nicht-Keep-Kandidaten). Generiere 1–3 agentenspezifische atomare Ja/Nein-Fragen, die versuchen, das Entwurfsurteil zu widerlegen, jede beantwortet mit einer Zeile Beweis (Datei lesen, Pfad prüfen, --help, WebSearch, Harness-Dokumentation prüfen). Für Dissolve-Kandidaten ist eine Frage obligatorisch: „Kann die absorbierende Harness-Funktion konkret benannt werden – Ja/Nein“ – eine Absorptionsbehauptung, die ihren Absorbierer nicht benennen kann, ist widerlegt. Und wenn ein Dissolve kurz davor ist, von einer Fähigkeit, die das Substrat-Gegenstück nicht besitzt (ein Tool, ein verdrahteter Sub-Agent), widerlegt zu werden, ist eine Gegenfrage obligatorisch, bevor die Widerlegung akzeptiert wird: „Ist der Sub-Agent der richtige Ort, um diese Fähigkeit zu nutzen – oder hält die Hauptschleife sie trotzdem?“ Fähigkeitsexistenz ist notwendig, aber nicht ausreichend; die Achse frischer/reicher Kontext entscheidet, wo die Fähigkeit hingehört (Präzedenzfall: die Planer-Widerlegung brach zusammen, weil die Hauptschleife das vollständige Agent-Tool hält). Keep-gebundene Agenten erhalten keine dynamischen Fragen.

Die Bewertung ist *

… [für die Übersetzung gekürzt]