artifact

Artifact — Share Documents and Files via Persistent Links

Publish a document or file to the Artifacts server and hand back the returned URL. Artifacts are immutable: once published, an artifact never changes. A revision or variation is a new artifact in the same collection, so every earlier version keeps its own working link.

Why This Skill Exists

Documents produced mid-task — a plan, a design doc, a status update, a diagram — are easiest to review as a rendered page with a link, especially when working with the user remotely. Artifacts gives every such document a stable URL; this skill teaches the decisions an agent has to make before writing one: which collection it belongs to, and which template and metadata to use.

Core Workflow

Step 1: Look for an existing artifact or collection first

Before creating anything, call list_collections and list_artifacts (pass project if you know it) to find earlier versions of the same document or file.

• A revision is a new artifact. There is no update. To revise a plan, status report, or design doc, publish the full new version with add_artifact and give it the same collection as the earlier versions. Share the new link; the old links keep showing the old versions.
• Start from the latest version when editing. Call get_artifact with includeContent: true on the newest artifact in the collection, edit the result, and publish the complete document as a new artifact.
• Offer variations side by side. When the user should choose between alternatives, publish one artifact per variation in one collection.
• Do not republish unchanged content. If an existing artifact already says what the user needs, share its link.

Step 2: Choose metadata

• title — short and human-scannable; it's what shows up in list views. ("Q3 Migration Plan", not "Plan for migrating the thing we discussed.")
• project — a stable string per repo or initiative, reused across every artifact in that body of work (matches what list_artifacts filters on in Step 1). Pick it once and keep it consistent so Step 1 keeps finding the right artifacts.
• description — one line, written for the list view, not the document body.
• collection — shared metadata for related independent artifacts. Set one on any document that may be revised later, because an artifact cannot be moved into a collection after it is published. Reuse one value for a document, its revisions, and its images so another agent can rediscover the set. A collection does not own its members.