Skills (Tools)

Ein Skill ist eine in sich geschlossene Fähigkeit, die das LLM aufrufen kann. Das Skill-Framework leitet automatisch die LLM-Tool-Registrierung, die HTTP-API, das UI-Formular, das Berechtigungs-Gate und das Audit-Log aus einem einzigen Metadaten-Struct ab — ein neues Skill hinzuzufügen heißt, eine Datei zu schreiben und Register in init() aufzurufen.

Skills sind L2 (device-direkt), wenn sie auf einem Edge-Agent laufen, L3 (Intelligenz), wenn sie auf dem Manager laufen. Beide sind erstklassig.

Anatomie

Jeder Skill liefert:

// internal/skill/types.go:99
type Metadata struct {
    Key          string   // lower_snake — id in dedupe keys, audit logs, LLM tool names
    Name         string   // human label
    Description  string   // shown to humans AND to the LLM
    Class        Class    // safe | mutating | dangerous
    Scope        Scope    // host (default) | manager
    Category     string   // free-form group label
    Params       ParamSchema
    ResultPreview string
}

Plus einen Executor:

type Executor interface {
    Metadata() Metadata
    Execute(ctx context.Context, params json.RawMessage) (json.RawMessage, error)
}

Das Framework dispatcht basierend auf Scope:

• ScopeHost — der Manager wickelt den Aufruf in eine Tunnel-RPC (Caller.Call(ctx, edgeID, "execute_skill", body)), der eine execute_skill-Handler des Edge-Agenten dispatcht per Key. Der LLM-Tool-Wrapper injiziert eine erforderliche edge_id-Integer-Eigenschaft im Schema.
• ScopeManager — läuft in-process. Kein edge_id; nützlich für öffentlich-Internet-Aufrufe (web_search), externe APIs, Subprocess-Skill-Packs.

Berechtigungsklassen

In die Metadaten eingebaut, sodass das Gate bei jeder Invokation läuft, nicht als Bolt-on:

Class	Beispiele	Wer kann aufrufen
safe	probe_*, read_file, tail_file, query_promql	LLM, beliebige Rolle
mutating	restart_service, kill_process	Erfordert Human-in-the-Loop-Genehmigung (geparkt, aber das Gate existiert)
dangerous	rm, reboot, drop_table	Erfordert RSA-signiertes SOP + Dual Approval (geparkt)

Die Default-Klasse ist safe — aber das Framework loggt zur Registrierungszeit eine Warnung, wenn ein Autor vergisst, das Feld zu setzen, sodass das nicht still durchrutschen kann. Siehe types.go:205.

Die skill_bridge.go in der aiops-Tools-Registry exponiert derzeit nur ClassSafe-Skills an das LLM — siehe skill_bridge.go. Mutating- und Dangerous-Klassen warten auf den PR-G4 Approval-Workflow.

Die drei Skill-Populationen

Go-Builtins (Edge)

Handgeschrieben in internal/skill/builtin/:

Key	Was
probe_http, probe_dns, probe_tcp	Read-only Netzwerk-Erreichbarkeit
tail_file, read_journal	Log-Oberfläche
host_netns_inspect	Netzwerk-Namespace-Inventar
web_search	Manager-seitig; SearXNG Default, konfigurierbar
restart_service	Mutating; gegatet

Jedes ist eine Go-Datei mit init(), das skill.Register aufruft. Das Edge-Binary liefert jedes Builtin eingebacken — kein Plugin-Install, keine Remote-Code-Execution-Oberfläche.

Subprocess-Skill-Packs

Für Fähigkeiten, die Sie ohne Rebuild des Edge-Agenten einfügen wollen, liefern Sie ein Verzeichnis mit einem skill.json-Manifest und einem ausführbaren Binary. Der Loader in internal/skill/subprocess.go liest das Manifest, registriert das Skill, dispatcht Execute an das Binary mit stdin-Params.

Verwendet für: Netzwerk-Forschungs-Tools (ovs-vsctl, nft, bpftool, ethtool, ip netns), Kubernetes-Inspect-Helfer — alles, wo das Binary bereits existiert und Shelling-out das Neuschreiben in Go schlägt.

Manager-seitige BaseTools

Die größte Population. Leben unter internal/manager/biz/aiops/tools/ als *_basetool.go-Dateien. Jedes trägt sein eigenes handgeschriebenes JSON-Schema (nötig für Formen, die das deklarative ParamSchema nicht ausdrücken kann: Arrays, verschachtelte Objekte, oneOf).

Ausgewählte BaseTools:

Tool	Was es tut
bash	Shell auf einer Ziel-Edge (gegatet; aufgezeichnet)
query_promql, query_logql, query_traceql	Die drei Observability-Backends
query_incidents, get_incident_detail, query_alert_rules	Alarm-Oberfläche
query_edges, query_change_events	Inventar + Audit
correlate_incident	Composite-Fan-out zu Prom + Log + Trace
expand_topology, find_topology_node, get_topology	Graph
query_knowledge	RAG
find_outlier_edges, rank_edges	Multi-Host-Vergleich
host_load, host_processes, host_files	Host-State-Batch-Tools
get_edge_summary	One-Shot-Edge-Health-Snapshot
restart_service	Manager-seitiger Wrapper um das Edge-Restart-Skill
send_message	Coordinator → Specialist-Agent-Kommunikation
task_stop, agent_tool	Worker-Lebenszyklus

Etwa 30+ insgesamt. Die vollständige Liste ist, was auch immer in BuildBaseTools in cmd/ongrid/main.go registriert ist.

Der Inventory-Bridge

Zwei parallele Registries existierten vor dem Bridge:

• Die Skill-Registry — ScopeHost-Go-Builtins + Subprocess-Packs. Auf der /skills-Seite der SPA mit Audit + Class-Gate sichtbar.
• Die BaseTool-Tasche — handgeschriebene manager-seitige Tools. Für das LLM sichtbar, aber NICHT für /skills.

Operatoren konnten ohne Quellcode-Lesen nicht sehen, welche cloud-seitigen Fähigkeiten der Agent tatsächlich hatte. Der inventory_bridge.go durchläuft die BaseTool-Tasche und registriert jedes Tool als Skill mit Scope=ScopeManager. Das opt-in RawSchemaProvider-Interface wird verwendet, um jedes handgeschriebene JSON-Schema der BaseTools wörtlich zu erhalten.

Pro 2026-05-08-Memo werden 18 BaseTools durch diesen Pfad gebridged — die /skills-Seite listet jetzt jede cloud-seitige Fähigkeit mit einem Scope-Chip, der edge vs. manager anzeigt.

Der umgekehrte Bridge ist auch verdrahtet: skill_bridge.go nimmt jedes sichere Skill und registriert es als LLM-orientiertes Tool, sodass das LLM Skills als Function-Calling-Tools mit einem edge_id-Parameter sieht, der für ScopeHost-Skills automatisch vorangestellt wird.

Audit

Jede Tool-Invokation schreibt eine Zeile in chat_tool_calls:

• session_id — die chatruntime-Session, die aufrief.
• tool_name, args_json, result_json, error.
• device_id — wenn das Tool einen bestimmten Host anzielte (das EdgeID-Feld auf ExecuteResult).
• started_at, finished_at, duration_ms.
• caller_user_id + caller_role — für LLM-originierte Aufrufe verwendet das Framework UserID=0 / Role="system".

Das HLD-010-Audit-Log piggybackt auf derselben Tabelle; die Admin-/admin/audit-Seite rendert sie mit Timeline + Per-Tool-Filtern.

Siehe auch

• WebShell — bash-Skill als interaktives Terminal statt One-Shot-Tool-Aufruf ausgedrückt.
• Wissensbasis — query_knowledge Deep Dive.
• Topologie — expand_topology / find_topology_node.
• Skill-Manifest — Wire-Format für Subprocess-Skill-Packs.