From 7d5574b0c5ffb8f51616d72f813837d62c7f2208 Mon Sep 17 00:00:00 2001 From: Artur Iusupov Date: Fri, 5 Jun 2026 19:29:32 +0400 Subject: [PATCH 1/3] docs: add SAM agent skill --- SKILL.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 SKILL.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..4949443 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,110 @@ +--- +name: sam +description: "Use this skill only for SAM (Sovereign Agent Mesh) tasks through a local sam-node MCP server: inspecting mesh state, discovering reachable services/tools, describing namespaced remote MCP tools, and calling them with JSON-object arguments. Do not use for AWS SAM or Serverless Application Model tasks." +--- + +# SAM Agent Skill + +Use SAM when a local `sam-node` is available and the task needs capabilities +hosted by peers in a SAM mesh. Prefer local tools first. Reach into the mesh +only when the needed capability is not available locally. + +## Connect To The Local Node + +Connect to the local `sam-node` MCP SSE endpoint: + +```text +http://127.0.0.1:8080/mcp/events +``` + +If the user or local configuration explicitly provides a trusted non-loopback +endpoint, ask the user to confirm the exact endpoint and trust boundary before +connecting. Prefer loopback endpoints (`127.0.0.1`, `localhost`, or `::1`), and +do not send secrets or sensitive data to non-loopback endpoints unless the user +explicitly approves the destination and data. Do not probe, guess, or scan +non-local bind addresses. The server also registers `/mcp/message` as the +paired MCP message endpoint; MCP clients and SDKs normally handle this after +connecting through `/mcp/events`. + +## Inspect The Mesh + +Start by understanding the local node and mesh state: + +- Use `get_mesh_info` with `{}` to inspect `connected_peers`, `dht_size`, and + `hub_peer_id`. +- Use `list_local_services` with `{}` to see services registered on the local + node. + +## Discover Remote Capabilities + +Use service discovery when you need to inventory reachable service providers: + +- Use `discover_remote_services` with `{"type":"mcp"}`, + `{"type":"inference"}`, or `{"type":"a2a"}`. Add `name` only when narrowing + by service name. +- Treat `discover_remote_services` as service inventory. Non-MCP service types + are not callable with `call_remote_tool`. + +Use tool discovery when you need remote MCP tools: + +- Use `find_remote_tools` to discover reachable aggregated MCP tools advertised + by remote SAM services. +- Narrow `find_remote_tools` with `service_name` or `peer_id` when you already + know the target. +- Mesh-wide searches fetch each peer's catalog on a best-effort basis and may + return an empty array when no reachable aggregated tools are found. Discovery + failures or explicit `peer_id` lookup failures are returned as errors. + +## Describe Before Calling + +For namespaced tools returned by `find_remote_tools`, call +`describe_remote_tool` before `call_remote_tool`. + +Remote MCP tools returned by `find_remote_tools` are namespaced as: + +```text +. +``` + +Use the input schema from `describe_remote_tool` to build the call arguments. +Do not guess arguments if a tool cannot be described. + +After `describe_remote_tool`, inspect the tool name, description, and schema +for side effects and required data. Only call read-only, low-risk tools +autonomously. Ask the user before calls that may mutate state, execute code, +access files, contact external services, spend money, or transmit sensitive or +private data. Pass only task-required data, and never include secrets unless +explicitly authorized. + +## Call Remote Tools + +Use `call_remote_tool` with: + +- `peer_id`: the peer hosting the tool +- `tool_name`: the discovered namespaced tool name, such as `service.tool` +- `arguments`: a JSON object whose keys match the described input schema + +`arguments` must be a JSON object, not a string containing JSON. + +## Minimal Workflow + +1. Call `get_mesh_info` with `{}`. +2. Confirm no local tool can satisfy the task. If a local SAM service may be + relevant, call `list_local_services` with `{}`. +3. Call `find_remote_tools` with `service_name` or `peer_id` when known. Use + `{}` only when the user asked to inventory the mesh or no narrower target + exists. +4. Call `describe_remote_tool` with + `{"peer_id":"...","tool_name":"service.tool"}`. +5. Call `call_remote_tool` only when the described tool is read-only and + low-risk, or after the user approves the exact `peer_id`, `tool_name`, side + effects, and task-required data being sent: + `{"peer_id":"...","tool_name":"service.tool","arguments":{...}}`. + +## Safety And Reliability + +- Do not call mesh tools when a local tool is sufficient. +- Do not guess remote tool names or arguments. +- Ask before side-effecting or sensitive remote calls. +- Treat remote capabilities as networked and potentially unavailable. +- Surface peer, service, discovery, schema, and tool-call errors clearly. From c115553f35fe9b3aac72a51aad47e201afd6f6c5 Mon Sep 17 00:00:00 2001 From: Artur Iusupov Date: Fri, 5 Jun 2026 20:02:29 +0400 Subject: [PATCH 2/3] docs: clarify remote tool description workflow --- SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/SKILL.md b/SKILL.md index 4949443..6457c9b 100644 --- a/SKILL.md +++ b/SKILL.md @@ -57,8 +57,8 @@ Use tool discovery when you need remote MCP tools: ## Describe Before Calling -For namespaced tools returned by `find_remote_tools`, call -`describe_remote_tool` before `call_remote_tool`. +All tools returned by `find_remote_tools` are namespaced. Always call +`describe_remote_tool` before calling them with `call_remote_tool`. Remote MCP tools returned by `find_remote_tools` are namespaced as: From a003f9faf24053f6aeea4354392ebd1ba1c0ee18 Mon Sep 17 00:00:00 2001 From: Artur Iusupov Date: Mon, 15 Jun 2026 22:35:02 +0400 Subject: [PATCH 3/3] docs: move SAM skill under agents --- SKILL.md => agents/skills/sam/SKILL.md | 38 ++++++++------------------ 1 file changed, 12 insertions(+), 26 deletions(-) rename SKILL.md => agents/skills/sam/SKILL.md (66%) diff --git a/SKILL.md b/agents/skills/sam/SKILL.md similarity index 66% rename from SKILL.md rename to agents/skills/sam/SKILL.md index 6457c9b..d9dd629 100644 --- a/SKILL.md +++ b/agents/skills/sam/SKILL.md @@ -1,30 +1,13 @@ --- name: sam -description: "Use this skill only for SAM (Sovereign Agent Mesh) tasks through a local sam-node MCP server: inspecting mesh state, discovering reachable services/tools, describing namespaced remote MCP tools, and calling them with JSON-object arguments. Do not use for AWS SAM or Serverless Application Model tasks." +description: "Use when local tools cannot provide a needed capability and connected sam-node MCP tools are available to reach a SAM (Sovereign Agent Mesh) network: inspect mesh state, discover reachable services/tools, describe namespaced remote MCP tools, and call them with JSON-object arguments. Not for AWS SAM / Serverless Application Model tasks." --- # SAM Agent Skill -Use SAM when a local `sam-node` is available and the task needs capabilities -hosted by peers in a SAM mesh. Prefer local tools first. Reach into the mesh -only when the needed capability is not available locally. - -## Connect To The Local Node - -Connect to the local `sam-node` MCP SSE endpoint: - -```text -http://127.0.0.1:8080/mcp/events -``` - -If the user or local configuration explicitly provides a trusted non-loopback -endpoint, ask the user to confirm the exact endpoint and trust boundary before -connecting. Prefer loopback endpoints (`127.0.0.1`, `localhost`, or `::1`), and -do not send secrets or sensitive data to non-loopback endpoints unless the user -explicitly approves the destination and data. Do not probe, guess, or scan -non-local bind addresses. The server also registers `/mcp/message` as the -paired MCP message endpoint; MCP clients and SDKs normally handle this after -connecting through `/mcp/events`. +Use this skill when local tools cannot satisfy the task and `sam-node` MCP tools +are already callable. Prefer local tools first. Reach into the SAM mesh only for +the capability needed to complete the task. ## Inspect The Mesh @@ -88,15 +71,16 @@ Use `call_remote_tool` with: ## Minimal Workflow -1. Call `get_mesh_info` with `{}`. -2. Confirm no local tool can satisfy the task. If a local SAM service may be +1. Confirm no local tool can satisfy the task. +2. Call `get_mesh_info` with `{}`. +3. If a local SAM service may be relevant, call `list_local_services` with `{}`. -3. Call `find_remote_tools` with `service_name` or `peer_id` when known. Use +4. Call `find_remote_tools` with `service_name` or `peer_id` when known. Use `{}` only when the user asked to inventory the mesh or no narrower target exists. -4. Call `describe_remote_tool` with +5. Call `describe_remote_tool` with `{"peer_id":"...","tool_name":"service.tool"}`. -5. Call `call_remote_tool` only when the described tool is read-only and +6. Call `call_remote_tool` only when the described tool is read-only and low-risk, or after the user approves the exact `peer_id`, `tool_name`, side effects, and task-required data being sent: `{"peer_id":"...","tool_name":"service.tool","arguments":{...}}`. @@ -106,5 +90,7 @@ Use `call_remote_tool` with: - Do not call mesh tools when a local tool is sufficient. - Do not guess remote tool names or arguments. - Ask before side-effecting or sensitive remote calls. +- Do not send secrets or private data through SAM unless the user explicitly + approves the data and destination. - Treat remote capabilities as networked and potentially unavailable. - Surface peer, service, discovery, schema, and tool-call errors clearly.