| name | maintenance |
| description | File cleanup and archiving. Tidies up bloated Plans.md, session-log.md, old logs, and state files. Trigger: /maintenance, cleanup, archive, organize, split session-log. Do NOT load for: implementation, review, release, new feature development. |
| description-en | File cleanup and archiving. Tidies up bloated Plans.md, session-log.md, old logs, and state files. Trigger: /maintenance, cleanup, archive, organize, split session-log. Do NOT load for: implementation, review, release, new feature development. |
| allowed-tools | ["Read","Write","Edit","Grep","Glob","Bash"] |
| argument-hint | [plans|session-log|logs|state|all] [--dry-run] |
| user-invocable | true |
| effort | low |
Maintenance
A single-purpose skill for tidying up messy files. Invoke when auto-cleanup-hook issues a warning,
or as routine housekeeping.
Prerequisite: Before destructive operations (archiving, line deletion), confirm that important
information in Plans.md / session-log.md has been promoted to SSOT (decisions.md / patterns.md).
If not yet synced, run /memory sync first.
Quick Reference
| Subcommand | Target | Typical Trigger |
|---|
maintenance plans | Archive completed tasks in Plans.md | "Organize Plans.md", "Move old tasks" |
maintenance session-log | Monthly split of session-log.md | "Split session-log", "Log is too long" |
maintenance logs | Delete old files in .claude/logs/ | "Clean up logs", "Delete logs older than 30 days" |
maintenance state | Trim agent-trace.jsonl / harness-usage.json | "Trace is bloated", "Compress state" |
maintenance all | Run all 4 in sequence | "Organize everything", "Full cleanup" |
Add --dry-run to only list what would be done without executing. Free-form instructions (e.g.
"delete old archives too", "keep only this session-log") are parsed in Step 1 and applied
to processing parameters in Step 2 and beyond.
Execution Steps
- Parse user instructions: Extract subcommand + free-form details (exclusions, destination, day threshold)
- SSOT sync check: If
.claude/state/.ssot-synced-this-session is absent,
prompt to run /memory sync (required only when touching Plans.md)
- Open reference file: Read
${CLAUDE_SKILL_DIR}/references/cleanup.md and execute the relevant section
- Report Before/After: Display line counts and deletion counts when done
Subcommand Details
For execution steps, thresholds, and archive destinations per target, see cleanup.md.
Integration with auto-cleanup-hook
The PostToolUse hook (scripts/auto-cleanup-hook.sh / Go version auto_cleanup_hook.go) detects
line count overruns in Plans.md, session-log.md, and CLAUDE.md and returns
Recommend archiving old tasks with /maintenance as feedback.
When you see this warning, run the relevant subcommand.
Notes
- Do not move in-progress tasks:
cc:WIP, pm:requested, cursor:requested are excluded from archiving
- Archive destination directory is fixed:
.claude/memory/archive/ — confirm with user before moving elsewhere
- Backup: Before editing files over 200 lines, take a local backup with
cp <file> <file>.bak.$(date +%s)
- CLAUDE.md is warning-only: Do not auto-edit. Only propose a split
Related Skills
memory — SSOT promotion before organizing Plans.md (updates decisions.md / patterns.md)harness-setup — Periodic maintenance after setup can also be invoked via harness-setupsession-init — Controls maintenance recommendation notifications at session start
