Ken
85 lines
2.6 KiB
Markdown
85 lines
2.6 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
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:
|
|
|
|
1. **H1 title** — Clear, specific heading
|
|
2. **Date and scope summary** — When the research was done and what it covers
|
|
3. **Markdown tables** for side-by-side comparisons (price, features, ratings)
|
|
4. **Bullet points** for recommendations, pros/cons, and key takeaways
|
|
5. **Source URLs** — Link to each page or listing referenced
|
|
6. **Closing section** — End with "Next Steps" or "Summary"
|
|
|
|
```markdown
|
|
# 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
|