Back to Details

janitor-swipe

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Janitor Swipe — interactive skill triage

Janitor Swipe — 交互式技能筛选

A bash TUI that puts every installed skill into a sorted deck and lets the user swipe keep / delete / skip on each card.
一款Bash TUI工具，将所有已安装技能整理为排序列表，让用户通过滑动操作对每个技能卡片执行保留/删除/跳过操作。

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
  • 已安装skills-janitor插件的Claude Code（提供
    scripts/swipe.sh
    和
    swipe-build-deck.sh
    脚本）
  • bash 3.2+（macOS自带的bash即可；无外部依赖）
  • 至少50列×22行的交互式终端——TUI需要读取单次按键输入

Instructions

使用说明

Step 1: Tell the user to run it via 
!

步骤1：告知用户通过
!
前缀运行

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".
在Claude Code中，Bash工具的标准输入是非交互式的，因此按键读取功能无法正常工作。用户必须通过
!
前缀调用命令，使其在本地实际终端中运行：
!bash ~/.claude/skills/skills-janitor/scripts/swipe.sh
当用户请求
/janitor-swipe
时，告知他们在终端中运行上述命令。请勿尝试通过Bash工具自行运行——会出现「需要交互式终端」的错误。

Step 2: Explain the card and controls

步骤2：说明卡片信息与操作控件

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)
每张卡片会展示：
  • 技能名称 + 在列表中的位置（例如
    [3 / 47]
    ）
  • 上下文成本拆分：
    X always · Y on trigger
    （描述令牌是永久加载的；技能本体仅在触发时加载）
  • 使用次数与最后调用日期
  • 作用域（
    user
    、
    project
    、
    plugin · <plugin-name>
    等）
  • 3行截断的描述内容
  • 评估标签（例如*"未使用 + 触发时占用资源多 — 优先删除候选"*）
操作控件：
  • ←
    / 
    h
    / 
    d
    — 标记为待删除
  • →
    / 
    l
    / 
    k
    — 保留
  • ↓
    / 
    j
    / 
    s
    / 空格 — 跳过
  • u
    — 撤销（返回上一张卡片，清除已做的决策）
  • i
    — 查看详情（显示完整的SKILL.md描述）
  • q
    / Esc — 退出（仍会展示已做决策的汇总）

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

步骤3：作用域感知的删除（关键正确性要点）

ScopeWhat 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
作用域左滑时的操作
user
、
project
、
codex-user
、
codex-project
路径被标记为待执行
rm -rf
（如果是符号链接则执行unlink）
plugin
、
plugin-source
不会被删除 — 在确认界面的"需审核插件"下标记，若该插件下有足够多技能被左滑，会提示运行
/plugin uninstall <plugin>

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>
浏览完最后一张卡片（或按下
q
）后，会显示确认界面，包含保留/跳过/删除的数量、待删除列表及路径、释放的「永久加载令牌数 + 触发时加载令牌数」汇总、插件审核明细，以及以下提示：
  • y
    — 立即执行删除操作（操作记录会保存至
    ~/.skills-janitor/log.jsonl
    ，包含路径和元数据快照）
  • N
    — 取消操作
  • save
    — 将决策写入
    ~/.skills-janitor/swipe-<timestamp>.json
    ，之后可通过
    swipe.sh --apply <file>
    执行

Error Handling

错误处理

  1. 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.
  2. Error: "Swipe needs at least 50 columns / 22 rows" Solution: The terminal window is too small — resize and retry.
  3. Error: No skills to swipe Solution: Nothing is installed (exits 0 with a message) — suggest 
    /janitor-discover
    to find skills.
  4. 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.
  1. 错误："Swipe needs an interactive terminal" 解决方案：命令是通过Bash工具运行的。请用户在自己的终端中通过
    !
    前缀运行。
  2. 错误："Swipe needs at least 50 columns / 22 rows" 解决方案：终端窗口过小——调整窗口大小后重试。
  3. 错误：No skills to swipe 解决方案：未安装任何技能（程序会退出并显示提示信息）——建议使用
    /janitor-discover
    查找技能。
  4. 错误：用户想要非交互式视图 解决方案：引导他们使用
    /janitor-report
    或
    /janitor-value
    ，以列表形式查看相同数据。
脚本已处理的边缘情况：滑动过程中按Ctrl-C会恢复终端状态；符号链接会被解除，不会被追踪；没有v1.5令牌拆分字段的旧保存列表仍可加载。

Examples

示例

Example 1: Standard triage

示例1：标准筛选流程

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.
输入：
/janitor-swipe
或 "帮我交互式清理我的技能"
输出：用两句话解释流程，然后给出确切的运行命令：
!bash ~/.claude/skills/skills-janitor/scripts/swipe.sh
——并表示之后可以协助查看结果。

Example 2: Resume saved decisions

示例2：恢复已保存的决策

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).
输入："我昨天保存了滑动决策——请执行它们。"
输出：
!bash ~/.claude/skills/skills-janitor/scripts/swipe.sh --apply ~/.skills-janitor/swipe-<timestamp>.json
（列出
~/.skills-janitor/
下的文件以找到正确的文件）。

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
  • TUI脚本（插件相对路径）：
    {baseDir}/../../scripts/swipe.sh
    ；列表构建脚本：
    {baseDir}/../../scripts/swipe-build-deck.sh
  • 删除日志：
    ~/.skills-janitor/log.jsonl
  • /janitor-report
    ——以非交互式列表形式展示相同数据
  • /janitor-value
    ——滑动列表背后的令牌+使用数据
  • /janitor-fix --prune
    ——自动清理损坏的符号链接，无需交互式审核 ",