Skip to content

Self-improving AI Employees for everyone

feat(auto_skill): auto-add matching skill when tool connects to AI agent

trohitg6c3ea9f1533b
diff --git a/client/src/Dashboard.tsx b/client/src/Dashboard.tsx
index 1c8a4286..d8932302 100644
--- a/client/src/Dashboard.tsx
+++ b/client/src/Dashboard.tsx
@@ -43,6 +43,7 @@ import { workflowApi } from './services/workflowApi';
import { useDragAndDrop } from './hooks/useDragAndDrop';
import { useComponentPalette } from './hooks/useComponentPalette';
import { useReactFlowNodes } from './hooks/useReactFlowNodes';
+import { useAutoSkillEdges } from './hooks/useAutoSkillEdges';
import { useCopyPaste } from './hooks/useCopyPaste';
import { useWebSocket } from './contexts/WebSocketContext';
import { useNodeStatusStore } from './stores/nodeStatusStore';
@@ -210,7 +211,15 @@ const DashboardContent: React.FC = () => {
workflowLock.workflow_id === currentWorkflow?.id;
const [globalModelDefaults, setGlobalModelDefaults] = React.useState<{ provider: string; model: string } | null>(null);
const { onDragOver, onDrop, handleComponentDragStart } = useDragAndDrop({ nodes, setNodes, saveNodeParameters, globalModelDefaults });
- const { onConnect, onNodesDelete, onEdgesDelete } = useReactFlowNodes({ setNodes, setEdges });
+ const { onConnect: baseOnConnect, onNodesDelete, onEdgesDelete: baseOnEdgesDelete } = useReactFlowNodes({ setNodes, setEdges });
+ const { onConnect, onEdgesDelete } = useAutoSkillEdges({
+ baseOnConnect,
+ baseOnEdgesDelete,
+ nodes,
+ edges,
+ setNodes,
+ setEdges,
+ });
const { copySelectedNodes, pasteNodes } = useCopyPaste({ nodes, edges, setNodes, setEdges, saveNodeParameters });
// Override all agent nodes to use the global model. Agent membership is
diff --git a/client/src/hooks/useAutoSkillEdges.ts b/client/src/hooks/useAutoSkillEdges.ts
new file mode 100644
index 00000000..2d4ae9ce
--- /dev/null
+++ b/client/src/hooks/useAutoSkillEdges.ts
@@ -0,0 +1,127 @@
+/**
+ * Wraps useReactFlowNodes' onConnect / onEdgesDelete with the
+ * auto-add-skill behaviour: when a tool node is connected to (or
+ * disconnected from) an AI agent's `input-tools` handle, dispatch the
+ * decision to the backend (`evaluate_auto_skill`) and apply the
+ * returned workflow-ops batch via `applyOperations`.
+ *
+ * This hook is a pure orchestrator -- no domain rules live here. The
+ * backend owns:
+ * - whether the source node has a paired skill (visuals.json)
+ * - whether the target node is an agent (plugin registry)
+ * - the canonical SkillConfig shape and toggle semantics
+ *
+ * The frontend only does:
+ * - a trivial edge filter to find any Master Skill already wired to
+ * the agent's input-skill handle (pure React Flow state lookup)
+ * - apply the backend's chosen ops via the standard applier
+ * (lib/workflowOps.ts) which handles add_node / add_edge /
+ * set_node_parameters and resolves cross-op client_ref placeholders.
+ *
+ * The user-level toggle (`auto_add_skill_for_tools` in UserSettings)
+ * gates the WS round-trip so disabled state has zero overhead.
+ */
+
+import { useCallback } from 'react';
+import type { Node, Edge, Connection } from 'reactflow';
+import { useWebSocket } from '../contexts/WebSocketContext';
+import { useUserSettingsQuery } from './useUserSettingsQuery';
+import { applyOperations, type WorkflowOperation } from '../lib/workflowOps';
+
+const MASTER_SKILL_TYPE = 'masterSkill';
+const SKILL_HANDLE = 'input-skill';
+
+interface UseAutoSkillEdgesProps {
+ baseOnConnect: (params: Edge | Connection) => void;
+ baseOnEdgesDelete: (deleted: Edge[]) => void;
+ nodes: Node[];
+ edges: Edge[];
+ setNodes: (updater: (ns: Node[]) => Node[]) => void;
+ setEdges: (updater: (es: Edge[]) => Edge[]) => void;
+}
+
+interface EvaluateAutoSkillResponse {
+ operations: WorkflowOperation[];
+}
+
+export function useAutoSkillEdges({
+ baseOnConnect,
+ baseOnEdgesDelete,
+ nodes,
+ edges,
+ setNodes,
+ setEdges,
+}: UseAutoSkillEdgesProps) {
+ const { sendRequest, saveNodeParameters } = useWebSocket();
+ const settingsQuery = useUserSettingsQuery();
+ const enabled = settingsQuery.data?.auto_add_skill_for_tools ?? true;
+
+ const dispatch = useCallback(
+ async (action: 'connect' | 'disconnect', edgeLike: Edge | Connection) => {
+ if (!enabled) return;
+ const sourceId = edgeLike.source;
+ const targetId = edgeLike.target;
+ if (!sourceId || !targetId) return;
+
+ const source = nodes.find(n => n.id === sourceId);
+ const target = nodes.find(n => n.id === targetId);
+ if (!source || !target) return;
+
+ // Trivial RF state lookup: which masterSkill (if any) is wired
+ // into the target agent's input-skill handle? Not policy.
+ const skillEdge = edges.find(
+ e => e.target === targetId && e.targetHandle === SKILL_HANDLE,
+ );
+ const masterSkill = skillEdge && nodes.find(
+ n => n.id === skillEdge.source && n.type === MASTER_SKILL_TYPE,
+ );
+ const masterSkillId = masterSkill?.id ?? null;
+ const masterSkillConfig = masterSkillId
+ ? ((masterSkill?.data as any)?.skillsConfig ?? null)
+ : null;
+
+ const result = await sendRequest<EvaluateAutoSkillResponse>('evaluate_auto_skill', {
+ action,
+ source_type: source.type ?? '',
+ target_type: target.type ?? '',
+ target_handle: edgeLike.targetHandle ?? '',
+ target_node_id: targetId,
+ master_skill_id: masterSkillId,
+ master_skill_config: masterSkillConfig,
+ });
+
+ if (!result?.operations?.length) return;
+
+ await applyOperations(result.operations, {
+ nodes,
+ edges,
+ setNodes,
+ setEdges,
+ saveNodeParameters,
+ });
+ },
+ [enabled, nodes, edges, sendRequest, saveNodeParameters, setNodes, setEdges],
+ );
+
+ const onConnect = useCallback(
+ (params: Edge | Connection) => {
+ baseOnConnect(params);
+ void dispatch('connect', params);
+ },
+ [baseOnConnect, dispatch],
+ );
+
+ const onEdgesDelete = useCallback(
+ (deleted: Edge[]) => {
+ baseOnEdgesDelete(deleted);
+ // Each deleted edge gets its own dispatch -- backend filters out
+ // anything that doesn't match the tool->agent input-tools shape.
+ for (const edge of deleted) {
+ void dispatch('disconnect', edge);
+ }
+ },
+ [baseOnEdgesDelete, dispatch],
+ );
+
+ return { onConnect, onEdgesDelete };
+}
diff --git a/server/nodes/_visuals.py b/server/nodes/_visuals.py
index 2ff55471..f9325dd1 100644
--- a/server/nodes/_visuals.py
+++ b/server/nodes/_visuals.py
@@ -64,3 +64,18 @@ def get_color(node_type: str) -> str:
if not entry:
return ""
return str(entry.get("color", ""))
+
+
+def get_skill(node_type: str) -> str:
+ """Return the teaching skill folder name registered for ``node_type``.
+
+ Many tool / utility nodes have a paired skill in ``server/skills/``
+ that documents how an AI agent should use them. The ``skill`` field
+ in ``visuals.json`` is the reverse lookup consumed by
+ ``services.auto_skill`` to decide what to do when a tool node is
+ connected to an AI agent.
+ """
+ entry = _VISUALS.get(node_type)
+ if not entry:
+ return ""
+ return str(entry.get("skill", ""))
diff --git a/server/routers/websocket.py b/server/routers/websocket.py
index 59f0e6c8..4cd8fe98 100644
--- a/server/routers/websocket.py
+++ b/server/routers/websocket.py
@@ -2623,6 +2623,30 @@ async def handle_save_skill_content(data: Dict[str, Any], websocket: WebSocket)
return {"success": False, "error": f"Skill '{skill_name}' not found"}
+@ws_handler("action", "source_type", "target_type", "target_handle")
+async def handle_evaluate_auto_skill(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Decide what to do when a tool->agent edge is connected/disconnected.
+
+ Owns the auto-add-skill policy: visuals.json reverse map +
+ plugin-registry agent classification + canonical SkillConfig
+ shape. Frontend forwards minimal edge details and the current
+ Master Skill state; this returns a standard workflow-ops batch
+ (see docs-internal/workflow_ops_protocol.md).
+ """
+ from services import auto_skill
+
+ result = auto_skill.evaluate(
+ action=data["action"],
+ source_type=data["source_type"],
+ target_type=data["target_type"],
+ target_handle=data["target_handle"],
+ target_node_id=data.get("target_node_id"),
+ master_skill_id=data.get("master_skill_id"),
+ master_skill_config=data.get("master_skill_config"),
+ )
+ return {"success": True, **result}
+
+
@ws_handler()
async def handle_list_skill_folders(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""List top-level subdirectories under server/skills/.
@@ -3487,6 +3511,7 @@ MESSAGE_HANDLERS: Dict[str, MessageHandler] = {
"save_skill_content": handle_save_skill_content,
"scan_skill_folder": handle_scan_skill_folder,
"list_skill_folders": handle_list_skill_folders,
+ "evaluate_auto_skill": handle_evaluate_auto_skill,
"lookup_skill_metadata": handle_lookup_skill_metadata,
# Memory and Skill Clear/Reset
diff --git a/server/services/auto_skill.py b/server/services/auto_skill.py
new file mode 100644
index 00000000..5c405504
--- /dev/null
+++ b/server/services/auto_skill.py
@@ -0,0 +1,152 @@
+"""Auto-add-skill policy.
+
+Decides what should happen when an edge is connected (or disconnected)
+between a tool node and an AI agent's ``input-tools`` handle. Owns the
+domain rules so the frontend stays a thin dispatcher: it sends the
+edge details + current Master Skill state, and gets back a workflow-
+operations batch (see ``services.workflow_ops``) to apply.
+
+Why backend: the rules read ``visuals.json`` for the tool->skill
+reverse map, the plugin registry for agent classification, and the
+canonical ``SkillConfig`` shape that ``handlers/ai.py``
+``_collect_agent_connections`` consumes at execution time. Putting
+those rules anywhere but the backend would scatter the source of
+truth across two languages.
+
+Output contract: standard workflow-ops batch
+``{"operations": [...]}``. See
+``docs-internal/workflow_ops_protocol.md``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+from nodes._visuals import get_skill
+from services.node_registry import get_node_class
+from services import workflow_ops
+
+
+_TOOL_HANDLE = "input-tools"
+_SKILL_HANDLE = "input-skill"
+_SKILL_OUTPUT_HANDLE = "output-tool"
+_AGENT_KIND = "agent"
+_MASTER_SKILL_TYPE = "masterSkill"
+_MASTER_SKILL_LABEL = "Master Skill"
+_MASTER_SKILL_OFFSET = {"x": -60.0, "y": 220.0}
+
+
+class SkillConfig(TypedDict):
+ enabled: bool
+ instructions: str
+ isCustomized: bool
+
+
+SkillsConfig = Dict[str, SkillConfig]
+
+
+def _is_agent_node(node_type: str) -> bool:
+ """True iff the node's plugin class is registered as ``component_kind = 'agent'``."""
+ cls = get_node_class(node_type)
+ if cls is None:
+ return False
+ return getattr(cls, "component_kind", "") == _AGENT_KIND
+
+
+def _toggle_skill(
+ config: Optional[SkillsConfig],
+ skill_name: str,
+ enabled: bool,
+) -> SkillsConfig:
+ """Return a new skillsConfig with ``skill_name`` toggled.
+
+ Preserves any existing ``instructions`` / ``isCustomized`` so a
+ user-customised skill keeps its content when toggled. New entries
+ default to empty instructions + ``isCustomized=False``; the
+ backend ai handler then loads canonical SKILL.md content at
+ execution time (see ``handlers/ai.py``
+ ``_collect_agent_connections``).
+ """
+ base: SkillsConfig = dict(config or {})
+ existing = base.get(skill_name, {})
+ base[skill_name] = {
+ "enabled": enabled,
+ "instructions": existing.get("instructions", ""),
+ "isCustomized": existing.get("isCustomized", False),
+ }
+ return base
+
+
+def evaluate(
+ *,
+ action: Literal["connect", "disconnect"],
+ source_type: str,
+ target_type: str,
+ target_handle: str,
+ target_node_id: Optional[str] = None,
+ master_skill_id: Optional[str] = None,
+ master_skill_config: Optional[SkillsConfig] = None,
+) -> Dict[str, List[Any]]:
+ """Decide what (if anything) to do for an edge connect/disconnect.
+
+ Returns a workflow-ops batch ``{"operations": [...]}``.
+
+ The three possible outcomes:
+
+ * Empty batch -- the event is irrelevant (not a tool node, not the
+ tools handle, not an agent target).
+ * One ``set_node_parameters`` op -- a Master Skill is already
+ wired; toggle the matching skill in its ``skillsConfig``.
+ * One ``add_node`` + one ``add_edge`` op -- no Master Skill exists
+ yet; spawn one, wire it into the agent's ``input-skill``, and
+ seed it with the matching skill enabled.
+ """
+ if target_handle != _TOOL_HANDLE:
+ return workflow_ops.empty()
+ if not _is_agent_node(target_type):
+ return workflow_ops.empty()
+ skill = get_skill(source_type)
+ if not skill:
+ return workflow_ops.empty()
+
+ enabled = action == "connect"
+
+ if master_skill_id:
+ new_config = _toggle_skill(master_skill_config, skill, enabled)
+ return {
+ "operations": [
+ workflow_ops.set_node_parameters(
+ master_skill_id,
+ {"skillsConfig": new_config},
+ ),
+ ],
+ }
+
+ # No Master Skill wired yet. Auto-creation only on connect; a
+ # disconnect with no MS in scope is a no-op.
+ if not enabled or not target_node_id:
+ return workflow_ops.empty()
+
+ new_config = _toggle_skill(None, skill, True)
+ client_ref = "auto_master_skill"
+ return {
+ "operations": [
+ workflow_ops.add_node(
+ client_ref,
+ _MASTER_SKILL_TYPE,
+ {"skillsConfig": new_config},
+ label=_MASTER_SKILL_LABEL,
+ position=workflow_ops.anchored(
+ target_node_id,
+ offset_x=_MASTER_SKILL_OFFSET["x"],
+ offset_y=_MASTER_SKILL_OFFSET["y"],
+ ),
+ ),
+ workflow_ops.add_edge(
+ {"client_ref": client_ref},
+ target_node_id,
+ source_handle=_SKILL_OUTPUT_HANDLE,
+ target_handle=_SKILL_HANDLE,
+ ),
+ ],
+ }