Artifact Conventions

Artifacts are persistent markdown documents written to the filesystem. They appear in the right panel and survive across sessions, making them ideal for research worth saving: comparison guides, curated lists, reports, and actionable recommendations.

Writing Pattern

Use the write_file tool to create artifacts:

write_file("artifacts/<session_id>/<name>.md", content)

The session_id is available in your context. Use it to namespace files per session so multiple sessions don't overwrite each other's work.

File Naming

Format: kebab-case
Extension: .md
Style: Descriptive, specific — say what the file contains

artifacts/<session_id>/hybrid-cars-under-10k-woodinville.md
artifacts/<session_id>/project-management-tools-comparison.md
artifacts/<session_id>/seattle-tokyo-flights-may-2025.md

Content Format

Each artifact should follow this structure:

H1 title — Clear, specific heading
Date and scope summary — When the research was done and what it covers
Markdown tables for side-by-side comparisons (price, features, ratings)
Bullet points for recommendations, pros/cons, and key takeaways
Source URLs — Link to each page or listing referenced
Closing section — End with "Next Steps" or "Summary"

# Hybrid Cars Under $10K — Woodinville WA (May 2025)

**Researched:** May 2025 · **Scope:** CarGurus, Autotrader, Craigslist within 30 mi

## Comparison

| Make/Model | Year | Price | MPG | Mileage |
|---|---|---|---|---|
| Toyota Prius LE | 2019 | $8,500 | 52 | 61,000 mi |
| Honda Insight EX | 2018 | $9,200 | 49 | 55,000 mi |

## Recommendations

- **Best value**: 2019 Prius LE — lowest price/mile ratio, clean title
- **Best mileage**: Hyundai Ioniq at 55 mpg city/highway combined

## Sources

- https://www.cargurus.com/Cars/new/nl-Hybrid-d2335
- https://www.autotrader.com/cars-for-sale/hybrid

## Next Steps

- Schedule test drives for the Prius and Ioniq listings
- Verify CarFax reports before committing

When to Create an Artifact

Create an artifact when the output is:

A guide, report, or summary the user will want to reference later
A comparison table across multiple options or products
Actionable recommendations with supporting evidence
Something printable or shareable with others

When NOT to Create an Artifact

Skip artifact creation for:

Simple answers — a one-sentence reply doesn't need a file
Intermediate research steps — notes you take while browsing, not the final output
Status updates — progress messages mid-task

2.6 KiB Raw Blame History