Skill: tool-tracer

Purpose

Runs any user task normally, then produces a structured JSON run summary (tool_trace.json) capturing every tool, action, connector, knowledge query, and sub-skill call made during the run — inputs, outputs, error codes, retries, and sequence. Built as an admin / debug tool: on a live channel a normal user never sees what the agent did behind the scenes, so this lets a maker or admin see it and triage an interaction without reproducing it in the test pane.

Trigger

This skill activates only when the user's message contains the exact debug command:

/special-debug tool-trace

The command may be followed by (or precede) the task to run — e.g. /special-debug tool-trace look up order 4471 and email the customer. If the command is present, run the task and produce the trace; if it is not present, this skill does not apply — even for casual phrasings like "trace this", "log this run", "debug this", or "what did you just do". Requiring the explicit command keeps a trace a deliberate act, not something a channel user triggers by accident.

Two capture modes. By default the trace runs in redacted mode — values that look like secrets, tokens, credentials, or PII/PHI are masked so the trace is safe to share for triage while still showing what ran. An authorized admin can append --full (/special-debug tool-trace --full …) to capture every value verbatim for deep debugging. Restrict who can use --full at deployment — a skill can't enforce it.

Scope & sensitivity. This is an admin / debug tool. In the default redacted mode, values that look like secrets, tokens, credentials, or PII/PHI are masked (e.g. "<redacted:token>") so the trace shows what ran without leaking sensitive data. In --full mode nothing is masked, so tool_trace.json can contain secrets, tokens, or PHI verbatim. A skill cannot enforce access control; the maker deploying this is responsible for restricting --full (and the agent) to authorized admin/maker users and for handling the file within that trust boundary. Prefer not to expose --full on agents published to untrusted end-user channels.

Behavior

Step 1 — Execute normally

Carry out the user's request exactly as you would without this skill. Use whatever tools are needed. Do not alter your reasoning or tool usage because tracing is active.

Step 2 — Compile the trace

After the task is complete (or if it fails), compile a tool_trace.json file capturing every tool call made during the run.

Step 3 — Save the trace file

Write tool_trace.json using your file-writing tool so it is returned to the user as a download. Default path: /app/created/tool_trace.json (the download folder in the Agent Skills sandbox). If that path or a create tool is unavailable in your runtime, use whatever file-writing tool exists and save to the runtime's user-download location.

Output Schema

{
  "trace_metadata": {
    "task_description": "<what the user asked for>",
    "agent_name": "<agent name if known, else null>",
    "timestamp_utc": "<ISO 8601 timestamp of when the task completed, or null if no clock is available>",
    "total_tool_calls": 0,
    "mode": "redacted | full",
    "status": "success | partial | failed"
  },
  "tool_calls": [
    {
      "step": 1,
      "tool_name": "<exact tool name>",
      "purpose": "<one sentence: why this tool was called at this step>",
      "input": {
        "<param_name>": "<param_value>"
      },
      "output_summary": "<concise summary of what the tool returned>",
      "output_raw": "<full raw output if ≤ ~2000 chars, else 'truncated — see output_summary'>",
      "status": "success | error",
      "error_message": null
    }
  ],
  "final_answer_summary": "<brief description of what was ultimately delivered to the user>"
}

Rules

…