What happens to files without a date in the filename?

Files without a recognizable date are skipped and reported in the summary.

Does the organizer use the file's modification time?

No. It relies on the date encoded in the filename (e.g., 2026-01-15_10-30-22Z-...).

What if a file is already in a year/month subdirectory?

Already-organized files in subdirectories are not moved again to avoid duplication.

specstory-organize

Scanned

npx machina-cli add skill specstoryai/agent-skills/specstory-organize --openclaw

Files (1)

SKILL.md

3.2 KB

SpecStory Organize

Organizes your .specstory/history directory by moving session files into YYYY/MM/ subdirectories based on the timestamp in each filename.

How It Works

Scans .specstory/history/ for markdown files
Extracts the date from filenames (e.g., 2026-01-22_19-20-56Z-fix-bug.md)
Creates year/month folders (e.g., 2026/01/)
Moves files into the appropriate subdirectory
Reports what was moved

Why Organize?

Over time, your history directory can accumulate hundreds of session files. Organizing by date makes it easier to:

Find sessions from a specific time period
Archive old sessions
Keep your project directory clean

Usage

Slash Command

User says	Action
`/specstory-organize`	Organize all files (default)
`/specstory-organize dry run`	Preview changes without moving
`/specstory-organize --dry-run`	Preview changes without moving

Direct Script Usage

# From project root
python skills/specstory-organize/scripts/organize.py

# Preview what would be moved (no changes made)
python skills/specstory-organize/scripts/organize.py --dry-run

Output

SpecStory History Organizer
===========================

Found 47 files to organize in .specstory/history/

Moving files:
  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/
  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/
  2026-01-22_19-20-56Z-add-feature.md -> 2026/01/
  2025-12-28_09-15-33Z-cleanup.md -> 2025/12/
  ...

Summary:
--------
Files moved: 47
  2026/01/: 23 files
  2025/12/: 18 files
  2025/11/: 6 files

Your history is now organized!

Dry Run Output

When using --dry-run:

SpecStory History Organizer (DRY RUN)
=====================================

Would organize 47 files in .specstory/history/

Preview:
  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/
  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/
  ...

No files were moved. Run without --dry-run to apply changes.

Present Results to User

After running the organize script:

Confirm success - Tell the user how many files were organized
Show the breakdown - List how many files went to each month
Note any skips - If files couldn't be parsed (no date in filename), mention them

Example Response

Done! I organized 47 session files in your `.specstory/history/` directory:

- **2026/01/**: 23 files
- **2025/12/**: 18 files
- **2025/11/**: 6 files

Your history files are now sorted by year and month, making it much easier
to find sessions from specific time periods.

Notes

Files without a recognizable date pattern in the filename are skipped
The script uses the filename timestamp, not the file's modification time
Already-organized files (in subdirectories) are not moved again
Compatible with Python 2.7+ and Python 3.x

Source

git clone https://github.com/specstoryai/agent-skills/blob/main/skills/specstory-organize/SKILL.mdView on GitHub

Overview

This skill organizes your .specstory/history session files by date, moving them into YYYY/MM subdirectories based on the timestamp embedded in each filename (for example 2026-01-22_19-20-56Z-fix-bug.md). By keeping history neatly dated, you can more easily locate past sessions, archive older entries, and maintain a clean project directory.

How This Skill Works

It scans .specstory/history for markdown files, extracts the date from filenames like 2026-01-22_19-20-56Z-*.md, creates the YYYY/MM folders, and moves each file into the correct subdirectory. It then reports what was moved and supports a dry-run mode to preview changes without moving files.

When to Use It

You want to sort a growing .specstory/history directory into date-based folders.
You need quick access to sessions from a specific year and month.
You are archiving old sessions to reduce clutter.
You want to preview changes before applying them with a dry-run.
You want to run the organizer from the project root to ensure correct paths.

Quick Start

Step 1: From project root, run: python skills/specstory-organize/scripts/organize.py
Step 2: Preview with: python skills/specstory-organize/scripts/organize.py --dry-run
Step 3: Apply the changes by running the script again (no --dry-run)

Best Practices

Run a dry-run first with --dry-run to preview moves.
Ensure filenames include a date pattern like YYYY-MM-DD_... for reliable parsing.
Run from the project root so relative paths resolve correctly.
Avoid moving files already organized in subdirectories; they won’t be moved again.
Backup your history or commit changes to version control before reorganizing.

Example Use Cases

Moved 47 files into 2026/01 and 2025/12 during a monthly clean-up.
Files from 2025 and 2024 organized into 2025/11, 2025/12, etc.
Previewed changes with a dry-run before applying the organization.
Non-date files were skipped and reported in the summary.
After organizing, sessions are easy to retrieve by year and month.

Frequently Asked Questions

Add this skill to your agents