use-artifacts

Using Artifacts

Artifacts are public HTML pages you upload to a hosting service. They have stable URLs that you can share with the user or open in a browser. Use them to surface work-in-progress, summaries, and reports.

When to use artifacts

Good artifact content:

• Progress panels / kanbans (task list with status)
• Research reports and analysis (data + findings + recommendations)
• Design docs / decision records (with context and rationale)
• Data visualizations (tables, SVG charts, flow diagrams)
• Final deliverables (the "thing the user asked for" rendered as HTML)

Do NOT use artifacts for:

• Code snippets — use files directly
• One-line answers — keep them in chat
• Internal debug logs — keep them in chat
• Large data dumps — link to source files instead

Cadence — when to upload

• Task start: if the task is complex (multi-step, research, deliverable), upload a skeleton artifact first as scaffolding (placeholder sections).
• Milestones: when you complete a phase (research done / implementation done / tests pass), update the artifact.
• User asks: upload immediately.
• Task end: ship the final artifact as the deliverable.

Do NOT upload:

• After every tool call (noise)
• Mid-step with no meaningful change (e.g. fixed a typo)

How to invoke (deferred tool)

artifact is a deferred tool. The first call requires two steps; subsequent calls one step.

First upload (creates a new artifact):

1. Use the Write tool to write HTML (.html) or Markdown (.md) to a local file (location is your choice).
2. SearchExtraTools({ query: "select:artifact" })   // loads the tool schema
3. ExecuteExtraTool({ tool_name: "artifact", params: { file_path: "<absolute-path>.html|.md" } })
4. Save the returned `id` from the tool result — this is the hash.

Subsequent updates (overwrites in place, URL stays stable):

1. Update the local file.
2. ExecuteExtraTool({ tool_name: "artifact", params: { file_path: "<absolute-path>.html|.md", hash: "<id-from-first-call>" } })