last30days-skill/docs/plans/2026-03-05-feat-auto-save-results-to-documents-plan.md

---
title: "feat: Auto-save research results to ~/Documents/Last30Days/"
type: feat
status: completed
date: 2026-03-05
---

# feat: Auto-save research results to ~/Documents/Last30Days/

## Overview

Every time the last30days skill completes a research run, automatically save the full briefing - inquiry, synthesis, stats, and follow-up suggestions - as a topic-named `.md` file in `~/Documents/Last30Days/`. Inspired by how users like @devin_explores are already manually saving results to build a personal research library (see screenshot - 17 topic files in a `Last30Days` Finder folder, each 9-34 KB).

## Problem Statement / Motivation

The skill's most valuable output - the assistant's synthesized "What I learned" briefing with stats and citations - only exists in the conversation. Once the session ends, it's gone. Users like @devin_explores work around this by manually copying output into .md files. Meanwhile, the Python script already writes raw data to `~/.local/share/last30days/out/`, but:

1. It overwrites on every run (no history)
2. It only contains pre-synthesis data (scored items), not the assistant's expert briefing
3. It's in a hidden dot-directory users don't naturally browse

The feature makes saving automatic and puts files where users expect them - the Documents folder, visible in Finder/file explorer.

## Proposed Solution

Add a **Write tool step in SKILL.md** after the synthesis/stats/invitation block that saves the complete briefing to `~/Documents/Last30Days/{topic-slug}.md`. This is a SKILL.md-only change (no Python script modifications needed) because the content to save is the assistant's synthesized output, which only exists in the SKILL.md flow.

### Why SKILL.md, not the Python script

The Python script (`last30days.py`) runs first and produces raw scored items. The assistant then synthesizes these into the "What I learned" briefing, stats block, and invitation. The synthesis is the valuable part - it's what @devin_explores is saving. The script can't produce this because it runs before synthesis happens.

### File naming

Convert the TOPIC variable to a kebab-case slug for the filename:
- "Claude Code best practices" -> `claude-code-best-practices.md`
- "best rap songs 2026" -> `best-rap-songs-2026.md`
- "nano banana 2 prompting guide" -> `nano-banana-2-prompting-guide.md`

This matches the screenshot pattern exactly (e.g., `anthropic-claude-code-best-practices.md`, `seedance-video-prompting-guide.md`).

If a file with the same slug already exists, append a date suffix: `claude-code-best-practices-2026-03-05.md`. This handles re-researching the same topic without overwriting previous results.

### File content

The saved .md file should contain the complete research output in this order:

```markdown
# {TOPIC}

> Researched {date} | Query type: {QUERY_TYPE} | Target tool: {TARGET_TOOL or "general"}

## What I learned

{The full synthesis section - topics, patterns, citations}

## Stats

{The full stats box with source counts and engagement}

## Follow-up suggestions

{The 2-3 specific suggestions from the invitation block}

---
*Generated by [last30days](https://github.com/mvanhorn/last30days-skill) v2.9*
```

### Implementation location in SKILL.md

Insert a new section between the current "LAST - Invitation" display and the "WAIT FOR USER'S RESPONSE" section. The Write tool call happens silently - no user prompt, no opt-in. Just save and briefly confirm.

## Technical Considerations

- **Cross-platform paths**: `~/Documents/` exists on macOS and most Linux desktops. On systems where it doesn't exist, `mkdir -p` handles creation. Windows WSL users get it too.
- **Permissions**: The Write tool in Claude Code can write to `~/Documents/` without issues. No sandbox concerns since this is the user's own Documents folder.
- **Filename sanitization**: Strip special characters, collapse whitespace to hyphens, lowercase. Keep it simple - no need for a library, just basic string ops in the SKILL.md instructions.
- **File size**: Based on the screenshot (9-34 KB files), the synthesis output is well within reasonable bounds.
- **No opt-out flag needed initially**: This is the default behavior. If users complain, a `--no-save` flag can be added later. Start with always-on since the screenshot proves users want this.

## Acceptance Criteria

- [x] Running `/last30days {topic}` creates `~/Documents/Last30Days/{topic-slug}.md` automatically
- [x] File contains: title, date, query metadata, full synthesis, stats block, follow-up suggestions
- [x] Filename is kebab-case slug of the topic (e.g., `claude-code-skills-guide.md`)
- [x] Duplicate topics get a date suffix instead of overwriting
- [x] Directory `~/Documents/Last30Days/` is created automatically if it doesn't exist
- [x] A brief confirmation line appears after the stats (e.g., "Saved to ~/Documents/Last30Days/claude-code-skills-guide.md")
- [x] Agent mode (`--agent`) also saves the file
- [x] No changes to the Python script - this is purely a SKILL.md addition

## Implementation Steps

### Step 1: Add save instructions to SKILL.md

Insert a new section after the invitation block (after line ~496, before "WAIT FOR USER'S RESPONSE" at line ~499):

**New section in `SKILL.md`:**

```markdown
## Save Research to Documents

After displaying the invitation, save the complete research briefing:

1. Generate the filename from TOPIC:
   - Lowercase the topic
   - Replace spaces and special characters with hyphens
   - Remove consecutive hyphens
   - Trim to 60 characters max
   - Example: "Claude Code Best Practices" -> "claude-code-best-practices"

2. Check if file already exists. If so, append today's date:
   - "claude-code-best-practices.md" exists -> use "claude-code-best-practices-2026-03-05.md"

3. Use the Write tool to save to ~/Documents/Last30Days/{slug}.md with this content:
   - H1 title: the TOPIC
   - Metadata line: date, QUERY_TYPE, TARGET_TOOL
   - Full "What I learned" synthesis (everything you just displayed)
   - Full stats block
   - Follow-up suggestions from the invitation
   - Footer with skill attribution

4. Confirm briefly: "Saved to ~/Documents/Last30Days/{slug}.md"
```

### Step 2: Update agent mode section

The `--agent` mode section (line ~116) skips interactive elements but should still save. Add a note that agent mode saves the file with the same logic.

### Step 3: Update Security & Permissions section

Add to the "What this skill does" list (line ~599):
- "Saves research briefings as .md files to ~/Documents/Last30Days/"

## Success Metrics

- Users accumulate a browsable library of .md research files in their Documents folder
- No more manual copy-paste workflow to save results
- Files are immediately findable in Finder/file explorer search

## Dependencies & Risks

- **Low risk**: Write tool is already in the skill's `allowed-tools` list
- **Low risk**: ~/Documents/ is a standard, user-owned directory
- **Edge case**: If the skill is interrupted mid-run (before synthesis), no file is saved - this is correct behavior since there's nothing to save yet
- **Edge case**: Very long topics could produce unwieldy filenames - the 60-char truncation handles this

## Sources & References

- Screenshot from @devin_explores showing manual .md file library in ~/Documents/Last30Days/
- Current output pipeline: `scripts/lib/render.py:798` (`write_outputs()`) writes to `~/.local/share/last30days/out/`
- SKILL.md synthesis flow: lines 275-496 (internalize research -> show summary -> invitation)
- Existing `--emit` modes: `scripts/last30days.py:1700` (`output_result()`)