{"id":"e507fb0f-1781-4671-8203-1a9e280dc308","shortId":"tbf49j","kind":"skill","title":"specstory-organize","tagline":"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\".","description":"# SpecStory Organize\n\nOrganizes your `.specstory/history` directory by moving session files into `YYYY/MM/` subdirectories based on the timestamp in each filename.\n\n## How It Works\n\n1. **Scans** `.specstory/history/` for markdown files\n2. **Extracts** the date from filenames (e.g., `2026-01-22_19-20-56Z-fix-bug.md`)\n3. **Creates** year/month folders (e.g., `2026/01/`)\n4. **Moves** files into the appropriate subdirectory\n5. **Reports** what was moved\n\n## Why Organize?\n\nOver time, your history directory can accumulate hundreds of session files. Organizing by date makes it easier to:\n- Find sessions from a specific time period\n- Archive old sessions\n- Keep your project directory clean\n\n## Usage\n\n### Slash Command\n\n| User says | Action |\n|-----------|--------|\n| `/specstory-organize` | Organize all files (default) |\n| `/specstory-organize dry run` | Preview changes without moving |\n| `/specstory-organize --dry-run` | Preview changes without moving |\n\n### Direct Script Usage\n\n```bash\n# From project root\npython skills/specstory-organize/scripts/organize.py\n\n# Preview what would be moved (no changes made)\npython skills/specstory-organize/scripts/organize.py --dry-run\n```\n\n## Output\n\n```\nSpecStory History Organizer\n===========================\n\nFound 47 files to organize in .specstory/history/\n\nMoving files:\n  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/\n  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/\n  2026-01-22_19-20-56Z-add-feature.md -> 2026/01/\n  2025-12-28_09-15-33Z-cleanup.md -> 2025/12/\n  ...\n\nSummary:\n--------\nFiles moved: 47\n  2026/01/: 23 files\n  2025/12/: 18 files\n  2025/11/: 6 files\n\nYour history is now organized!\n```\n\n## Dry Run Output\n\nWhen using `--dry-run`:\n\n```\nSpecStory History Organizer (DRY RUN)\n=====================================\n\nWould organize 47 files in .specstory/history/\n\nPreview:\n  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/\n  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/\n  ...\n\nNo files were moved. Run without --dry-run to apply changes.\n```\n\n## Present Results to User\n\nAfter running the organize script:\n\n1. **Confirm success** - Tell the user how many files were organized\n2. **Show the breakdown** - List how many files went to each month\n3. **Note any skips** - If files couldn't be parsed (no date in filename), mention them\n\n### Example Response\n\n```\nDone! I organized 47 session files in your `.specstory/history/` directory:\n\n- **2026/01/**: 23 files\n- **2025/12/**: 18 files\n- **2025/11/**: 6 files\n\nYour history files are now sorted by year and month, making it much easier\nto find sessions from specific time periods.\n```\n\n## Notes\n\n- Files without a recognizable date pattern in the filename are skipped\n- The script uses the filename timestamp, not the file's modification time\n- Already-organized files (in subdirectories) are not moved again\n- Compatible with Python 2.7+ and Python 3.x","tags":["specstory","organize","agent","skills","specstoryai","agent-skills","claude-code-plugin"],"capabilities":["skill","source-specstoryai","skill-specstory-organize","topic-agent-skills","topic-claude-code-plugin","topic-skills"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/specstoryai/agent-skills/specstory-organize","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add specstoryai/agent-skills","source_repo":"https://github.com/specstoryai/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.462","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 24 github stars · SKILL.md body (2,871 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T01:01:28.751Z","embedding":null,"createdAt":"2026-04-18T22:23:46.417Z","updatedAt":"2026-04-22T01:01:28.751Z","lastSeenAt":"2026-04-22T01:01:28.751Z","tsv":"'/specstory-organize':127,132,139 '1':54,253 '18':198,308 '2':60,264 '2.7':371 '2025-12-28_09-15-33z-cleanup.md':188 '2025/11':200,310 '2025/12':189,197,307 '2026-01-15_10-30-22z-refactor-auth.md':182,228 '2026-01-15_14-22-01z-fix-tests.md':184,230 '2026-01-22_19-20-56z-add-feature.md':186 '2026-01-22_19-20-56z-fix-bug.md':67 '2026/01':73,183,185,187,194,229,231,304 '23':195,305 '3':68,276,374 '4':74 '47':174,193,223,297 '5':81 '6':201,311 'accumul':94 'action':126 'ai':6 'alreadi':359 'already-organ':358 'appli':242 'appropri':79 'archiv':113 'base':44 'bash':150 'breakdown':267 'chang':136,144,162,243 'clean':21,120 'code':7 'command':123 'compat':368 'confirm':254 'couldn':282 'creat':69 'date':63,101,287,339 'default':131 'direct':147 'directori':36,92,119,303 'done':294 'dri':133,141,167,208,214,219,239 'dry-run':140,166,213,238 'e.g':66,72 'easier':104,326 'exampl':292 'extract':61 'file':30,40,59,76,98,130,175,181,191,196,199,202,224,233,261,271,281,299,306,309,312,315,335,354,361 'filenam':50,65,289,343,350 'find':106,328 'folder':13,71 'found':173 'histori':20,91,171,204,217,314 'hundr':95 'keep':116 'list':268 'made':163 'make':102,323 'mani':260,270 'markdown':58 'mention':290 'modif':356 'month':275,322 'move':38,75,85,138,146,160,180,192,235,366 'much':325 'note':277,334 'old':114 'organ':3,4,18,28,32,33,87,99,128,172,177,207,218,222,251,263,296,360 'output':169,210 'pars':285 'pattern':340 'period':112,333 'present':244 'preview':135,143,156,227 'project':118,152 'python':154,164,370,373 'recogniz':338 'report':82 'respons':293 'result':245 'root':153 'run':14,134,142,168,209,215,220,236,240,249 'say':17,125 'scan':55 'script':148,252,347 'session':8,26,39,97,107,115,298,329 'show':265 'skill' 'skill-specstory-organize' 'skills/specstory-organize/scripts/organize.py':155,165 'skip':279,345 'slash':122 'sort':24,318 'source-specstoryai' 'specif':110,331 'specstori':2,5,23,29,31,170,216 'specstory-organ':1 'specstory/history':10,35,56,179,226,302 'subdirectori':43,80,363 'success':255 'summari':190 'tell':256 'time':89,111,332,357 'timestamp':47,351 'topic-agent-skills' 'topic-claude-code-plugin' 'topic-skills' 'usag':121,149 'use':212,348 'user':16,124,247,258 'went':272 'without':137,145,237,336 'work':53 'would':158,221 'x':375 'year':320 'year/month':12,70 'yyyy/mm':42","prices":[{"id":"50e32f3a-b69a-47bf-a495-2dc3608dd841","listingId":"e507fb0f-1781-4671-8203-1a9e280dc308","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"specstoryai","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:23:46.417Z"}],"sources":[{"listingId":"e507fb0f-1781-4671-8203-1a9e280dc308","source":"github","sourceId":"specstoryai/agent-skills/specstory-organize","sourceUrl":"https://github.com/specstoryai/agent-skills/tree/main/skills/specstory-organize","isPrimary":false,"firstSeenAt":"2026-04-18T22:23:46.417Z","lastSeenAt":"2026-04-22T01:01:28.751Z"}],"details":{"listingId":"e507fb0f-1781-4671-8203-1a9e280dc308","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"specstoryai","slug":"specstory-organize","github":{"repo":"specstoryai/agent-skills","stars":24,"topics":["agent-skills","claude-code-plugin","skills"],"license":"apache-2.0","html_url":"https://github.com/specstoryai/agent-skills","pushed_at":"2026-01-31T01:24:32Z","description":"SpecStory's official collection of agent skills. Summarize, organize and create with `.specstory/history`","skill_md_sha":"9bd60d4337ccab25656bd4e785a977fe0e9fda2e","skill_md_path":"skills/specstory-organize/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/specstoryai/agent-skills/tree/main/skills/specstory-organize"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"specstory-organize","license":"Apache-2.0","description":"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\"."},"skills_sh_url":"https://skills.sh/specstoryai/agent-skills/specstory-organize"},"updatedAt":"2026-04-22T01:01:28.751Z"}}