Skills (tools)

Un skill es una capacidad autocontenida que el LLM puede invocar. El framework de skills auto-deriva el registro de tool para el LLM, la API HTTP, el formulario UI, el gate de permisos y el audit log a partir de un único struct de metadata — añadir un skill nuevo significa escribir un archivo y llamar a Register en init().

Los skills son L2 (device-direct) cuando corren en un agente de edge, L3 (intelligence) cuando corren en el manager. Ambos son first-class.

Anatomía

Cada skill trae:

// 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
}

Más un Executor:

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

El framework hace dispatch basado en Scope:

• ScopeHost — el manager envuelve la llamada en un RPC de túnel (Caller.Call(ctx, edgeID, "execute_skill", body)), el único handler execute_skill del agente edge hace dispatch por key. El wrapper de tool del LLM inyecta una propiedad entera edge_id requerida en el schema.
• ScopeManager — corre in-process. Sin edge_id; útil para llamadas a internet público (web_search), APIs externas, packs de skills por subproceso.

Clases de permisos

Integradas en la metadata para que el gate corra en cada invocación, no como un bolt-on:

Clase	Ejemplos	Quién puede invocar
safe	probe_*, read_file, tail_file, query_promql	LLM, cualquier rol
mutating	restart_service, kill_process	Requiere aprobación human-in-the-loop (parqueado, pero el gate existe)
dangerous	rm, reboot, drop_table	Requiere SOP firmado RSA + aprobación dual (parqueado)

La clase default es safe — pero el framework registra un warning en tiempo de registro cuando un autor olvida setear el campo, así que esto no puede colarse silenciosamente. Ver types.go:205.

El skill_bridge.go en el registry de tools de aiops actualmente solo expone skills ClassSafe al LLM — ver skill_bridge.go. Las clases mutating y dangerous esperan al workflow de aprobación PR-G4.

Las tres poblaciones de skills

Builtins Go (edge)

Escritos a mano en internal/skill/builtin/:

Key	Qué
probe_http, probe_dns, probe_tcp	Alcanzabilidad de red de solo lectura
tail_file, read_journal	Superficie de log
host_netns_inspect	Inventario de network namespace
web_search	Lado del manager; SearXNG default, configurable
restart_service	Mutating; gated

Cada uno es un archivo Go con init() llamando a skill.Register. El binario del edge trae cada builtin horneado — sin install de plugin, sin superficie de ejecución de código remoto.

Packs de skills por subproceso

Para capacidades que quieras dropear sin recompilar el agente edge, distribuye un directorio con un manifest skill.json y un ejecutable. El loader en internal/skill/subprocess.go lee el manifest, registra el skill, hace dispatch de Execute al binario con params por stdin.

Usado para: tools de research de red (ovs-vsctl, nft, bpftool, ethtool, ip netns), helpers de inspect de Kubernetes — cualquier cosa donde el binario ya existe y shellear le gana a reescribirlo en Go.

BaseTools del lado del manager

La población más grande. Viven bajo internal/manager/biz/aiops/tools/ como archivos *_basetool.go. Cada uno lleva su propio JSON Schema escrito a mano (necesario para formas que el ParamSchema declarativo no puede expresar: arrays, objetos anidados, oneOf).

BaseTools seleccionados:

Tool	Qué hace
bash	Shell en un edge target (gated; grabado)
query_promql, query_logql, query_traceql	Los tres backends de observabilidad
query_incidents, get_incident_detail, query_alert_rules	Superficie de alerting
query_edges, query_change_events	Inventario + audit
correlate_incident	Fan-out compuesto a prom + log + trace
expand_topology, find_topology_node, get_topology	Grafo
query_knowledge	RAG
find_outlier_edges, rank_edges	Comparación multi-host
host_load, host_processes, host_files	Tools batch de estado de host
get_edge_summary	Snapshot one-shot de salud de edge
restart_service	Wrapper del lado del manager alrededor del skill restart del edge
send_message	Comms coordinator → specialist agent
task_stop, agent_tool	Ciclo de vida del worker

Cerca de 30+ en total. La lista completa es lo que esté registrado en BuildBaseTools en cmd/ongrid/main.go.

El inventory bridge

Dos registries paralelos existían antes del bridge:

• El skill registry — builtins Go ScopeHost + packs por subproceso. Mostrado en la página /skills de la SPA con audit + gate de clase.
• El bag de BaseTools — tools del lado del manager escritos a mano. Mostrados al LLM pero NO a /skills.

Los operadores no podían ver qué capacidades cloud-side tenía realmente el agente sin leer el código fuente. El inventory_bridge.go recorre el bag de BaseTool y registra cada tool como un skill con Scope=ScopeManager. La interfaz opt-in RawSchemaProvider se usa para preservar el JSON Schema escrito a mano de cada BaseTool verbatim.

Según el memo del 2026-05-08, 18 BaseTools son puenteados a través de esta ruta — la página /skills ahora lista cada capacidad cloud-side con un chip de scope que indica edge vs manager.

El bridge inverso también está cableado: skill_bridge.go toma cada skill safe y lo registra como un Tool cara-al-LLM, así que el LLM ve los skills como tools de function-calling con un parámetro edge_id auto-antepuesto para los ScopeHost.

Audit

Cada invocación de tool escribe una fila a chat_tool_calls:

• session_id — la sesión de chatruntime que llamó.
• tool_name, args_json, result_json, error.
• device_id — cuando el tool apuntó a un host específico (el campo EdgeID en ExecuteResult).
• started_at, finished_at, duration_ms.
• caller_user_id + caller_role — para llamadas originadas por el LLM, el framework usa UserID=0 / Role="system".

El audit log de HLD-010 se sube sobre la misma tabla; la página admin /admin/audit la renderiza con timeline + filtros por-tool.

Ver también

• WebShell — el skill bash expresado como una terminal interactiva en vez de una llamada de tool one-shot. Mismo sustrato de audit.
• Conocimiento — deep dive de query_knowledge.
• Topología — expand_topology / find_topology_node.
• Skill manifest — wire format para packs de skills por subproceso.