specstory-organize
Organize SpecStory AI coding sessions in .specstory/history into year/month folders. Run when user says "organize my history", "clean up specstory", "sort my sessions", or "organize specstory files".
Best use case
specstory-organize is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Organize SpecStory AI coding sessions in .specstory/history into year/month folders. Run when user says "organize my history", "clean up specstory", "sort my sessions", or "organize specstory files".
Teams using specstory-organize should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/specstory-organize/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How specstory-organize Compares
| Feature / Agent | specstory-organize | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Organize SpecStory AI coding sessions in .specstory/history into year/month folders. Run when user says "organize my history", "clean up specstory", "sort my sessions", or "organize specstory files".
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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 1. **Scans** `.specstory/history/` for markdown files 2. **Extracts** the date from filenames (e.g., `2026-01-22_19-20-56Z-fix-bug.md`) 3. **Creates** year/month folders (e.g., `2026/01/`) 4. **Moves** files into the appropriate subdirectory 5. **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 ```bash # 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: 1. **Confirm success** - Tell the user how many files were organized 2. **Show the breakdown** - List how many files went to each month 3. **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
Related Skills
specstory-yak
Analyze your SpecStory AI coding sessions in .specstory/history for yak shaving - when your initial goal got derailed into rabbit holes. Run when user says "analyze my yak shaving", "check for rabbit holes", "how distracted was I", or "yak shave score".
specstory-session-summary
Summarize recent SpecStory AI coding sessions in standup format. Use when the user wants to review sessions from .specstory/history, prepare for standups, track work progress, or understand what was accomplished.
specstory-project-stats
Fetch project statistics from SpecStory Cloud. Run when user says "get project stats", "show SpecStory stats", "project statistics", "how many sessions", or "SpecStory metrics".
specstory-link-trail
Track all URLs fetched during SpecStory AI coding sessions. Run when user says "show my link trail", "what URLs did I visit", "list fetched links", or "show web fetches".
specstory-guard
Install a pre-commit hook that scans .specstory/history for secrets before commits. Run when user says "set up secret scanning", "install specstory guard", "protect my history", or "check for secrets".
taxonomy-modeling-design
Phase 2 of the pentaphase structural-overhaul protocol. Classifies entities, standardizes attributes, establishes relationships, and designs the access framework. Use when the user invokes phase 2 of an overhaul, asks to "design the taxonomy" or "model the structure", or has completed a landscape audit and is ready to redesign. Consumes phase-1-landscape-report.md; produces phase-2-taxonomy-model.md.
systemic-ingestion-normalization
Phase 4 of the pentaphase structural-overhaul protocol. Purges redundancies, enriches and aligns legacy entities to the new schema, executes phased ingestion into the new environment, and audits integrity. Use when the user invokes phase 4 of an overhaul, asks to "migrate the data" or "ingest into the new system", or has a configured environment ready to accept legacy entities. Consumes phase-3-environment-spec.md; produces phase-4-ingestion-report.md.
system-environment-configuration
Phase 3 of the pentaphase structural-overhaul protocol. Translates the taxonomy model into objective technical criteria, evaluates candidate mechanisms or frameworks, instantiates the chosen architecture, and programs validation rules. Use when the user invokes phase 3 of an overhaul, asks to "select a system" or "configure the environment", or has a taxonomy model and is ready to choose technology. Consumes phase-2-taxonomy-model.md; produces phase-3-environment-spec.md.
pentaphase-orchestrator
Threads the full five-phase structural-overhaul protocol — landscape discovery, taxonomy design, environment configuration, systemic ingestion, governance evolution — for any substrate the user names. Use when the user requests a structural overhaul, system redesign, or end-to-end restructuring of a documentation system, asset registry, code monorepo, knowledge base, or operational workflow; or when they explicitly invoke the pentaphase methodology. Coordinates handoffs between phase-skills and seats validation gates between phases.
landscape-discovery-audit
Phase 1 of the pentaphase structural-overhaul protocol. Inventories assets, maps current flow, identifies friction, and defines value metrics for any substrate. Use when the user invokes phase 1 of an overhaul, requests a baseline audit, asks to "discover the landscape" of a system, or wants to understand current state before redesigning. Produces phase-1-landscape-report.md.
governance-evolution-protocol
Phase 5 of the pentaphase structural-overhaul protocol. Codifies operational protocols, onboards the ecosystem of participants, programs behavior monitoring, and establishes an iteration cadence so the substrate evolves rather than calcifies. Use when the user invokes phase 5 of an overhaul, asks to "establish governance" or "lock in the protocols", or has completed ingestion and is ready to declare the substrate operational. Consumes phase-4-ingestion-report.md; produces phase-5-governance-charter.md, which closes the protocol.
dimension-surfacing
Surfaces the parallel domain dimensions implicit in a dense or minimal prompt. Use when a user prompt is small on the surface but plainly implies multiple independent domains needing different expertise; when explicitly invoked by the coliseum-orchestrator skill as Phase 1; or when the user asks "what dimensions does this prompt encode" or "what axes does this break into." Produces a named dimension set where each dimension is independently executable and not a paraphrase of another.