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

title, type, status, date

title	type	status	date
feat: Auto-save research results to ~/Documents/Last30Days/	feat	completed	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:

# {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

• Running /last30days {topic} creates ~/Documents/Last30Days/{topic-slug}.md automatically
• File contains: title, date, query metadata, full synthesis, stats block, follow-up suggestions
• Filename is kebab-case slug of the topic (e.g., claude-code-skills-guide.md)
• Duplicate topics get a date suffix instead of overwriting
• Directory ~/Documents/Last30Days/ is created automatically if it doesn't exist
• A brief confirmation line appears after the stats (e.g., "Saved to ~/Documents/Last30Days/claude-code-skills-guide.md")
• Agent mode (--agent) also saves the file
• 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:

## 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())