Janitor Swipe Agent Skill

Janitor Swipe — interactive skill triage

A bash TUI that puts every installed skill into a sorted deck and lets the user swipe keep / delete / skip on each card.

Overview

The deck is sorted "most likely waste first" — heavy, never-used skills appear at the top, so most users hit ← delete a few times and quit before reviewing the whole list. The swipe is scope-aware and honest about what it can delete: user-scope skills are actually removed (after confirmation), plugin skills are flagged for review instead.

Prerequisites

• Claude Code with the skills-janitor plugin installed (provides scripts/swipe.sh and swipe-build-deck.sh)
• bash 3.2+ (the stock macOS bash works; no external dependencies)
• An interactive terminal at least 50 columns x 22 rows — the TUI reads single keypresses

Instructions

Step 1: Tell the user to run it via !

Inside Claude Code, the Bash tool's stdin is non-interactive, so the keypress reader can't work. The user must invoke it via the ! prefix so the command runs in their actual shell:

!bash ~/.claude/skills/skills-janitor/scripts/swipe.sh

When the user asks for /janitor-swipe, tell them to run that command in their terminal. Do NOT try to run it yourself via the Bash tool — it will error with "needs an interactive terminal".

Step 2: Explain the card and controls

Each card shows:

• Skill name + position in deck (e.g. [3 / 47])
• Context cost split: X always · Y on trigger (description tokens are permanent; body loads only when the skill fires)
• Usage count and last invoked date
• Scope (user, project, plugin · <plugin-name>, etc.)
• 3-line truncated description
• Verdict label (e.g. *"Unused + heavy on trigger — prime delete candidate"*)

Controls:

• ← / h / d — stage for delete
• → / l / k — keep
• ↓ / j / s / space — skip
• u — undo (back up one card, clear its decision)
• i — inspect (show full SKILL.md description)
• q / Esc — quit (still shows summary for decisions made so far)

Step 3: Scope-aware deletion (the critical correctness point)

| Scope | What happens on swipe left |

|---|---|

| user, project, codex-user, codex-project | Path is staged for rm -rf (or unlink if symlink) |

| plugin, plugin-source | NOT deleted — flagged under "Plugins to review" at the apply screen, with a hint to run /plugin uninstall <plugin> if enough skills from that plugin were swiped |

| mcp-user, mcp-project (v1.7) | Server entry is removed from its config file (~/.claude.json / .mcp.json) with a timestamped .bak backup — reversible |

| mcp-plugin | NOT edited — flagged for plugin review like plugin skills |

MCP server cards show real call counts from session transcripts instead of token guesses (schemas live server-side). An unused connected server ranks high — its tool schemas load into context for nothing.

Output

After the last card (or q), an apply screen shows keep/skip/delete counts, the deletion list with paths, the "frees X always-loaded + Y on-trigger" token summary, the plugin review breakdown, and a prompt:

• y — apply deletions immediately (logged to ~/.skills-janitor/log.jsonl with path and frontmatter snapshot)
• N — cancel
• save — write decisions to ~/.skills-janitor/swipe-<timestamp>.json for later application via swipe.sh --apply <file>

Error Handling

• Error: "Swipe needs an interactive terminal"

Solution: The command was run through the Bash tool. Have the user run it with the ! prefix in their own terminal.

• Error: "Swipe needs at least 50 columns / 22 rows"

Solution: The terminal window is too small — resize and retry.

• Error: No skills to swipe

Solution: Nothing is installed (exits 0 with a message) — suggest /janitor-discover to find skills.

• Error: The user wants a non-interactive view instead

Solution: Point them at /janitor-report or /janitor-value for the same data in list form.

Edge cases handled by the script: Ctrl-C mid-swipe restores the terminal; symlinks are unlinked, never followed; old saved decks without the v1.5 token-split fields still load.

Examples

Example 1: Standard triage

Input: "/janitor-swipe" or "help me clean up my skills interactively"

Output: Explain the flow in two sentences, then give the exact command to run: !bash ~/.claude/skills/skills-janitor/scripts/swipe.sh — and offer to review the results afterwards.

Example 2: Resume saved decisions

Input: "I saved my swipe decisions yesterday — apply them."

Output: !bash ~/.claude/skills/skills-janitor/scripts/swipe.sh --apply ~/.skills-janitor/swipe-<timestamp>.json (list the files in ~/.skills-janitor/ to find the right one).

Resources

• TUI script (plugin-relative): {baseDir}/../../scripts/swipe.sh; deck builder: {baseDir}/../../scripts/swipe-build-deck.sh
• Deletion log: ~/.skills-janitor/log.jsonl
• /janitor-report — same data as a non-interactive list
• /janitor-value — the token + usage data underneath the swipe deck
• /janitor-fix --prune — automated broken-symlink cleanup, no interactive review