Skill Discovery & Pre-Install Check

Combined entry point for finding skills on GitHub and for evaluating a specific skill (URL or local path) before installing it.

Overview

Replaces the v1.2 split between /janitor-search and /janitor-precheck. The dispatcher picks the right mode from the argument shape. Search results are relevance-gated (a repo must carry a skill signal in its name/description/topics) and ranked by relevance before stars, so generic mega-repos don't crowd out actual skills.

Prerequisites

• Claude Code with the skills-janitor plugin installed (provides scripts/discover.sh, search.sh, precheck.sh, compare.sh)
• bash 3.2+ and curl
• Network access to api.github.com (anonymous OK; set GITHUB_TOKEN for higher rate limits and code search)

Instructions

Step 1: Dispatch on argument shape

bash ~/.claude/skills/skills-janitor/scripts/discover.sh <query-or-url> [options]

Examples:

• discover.sh seo — search for SEO-related skills
• discover.sh n8n --limit 20 — top 20 n8n skills
• discover.sh --compare marketing-seo-audit — alternatives to a local skill
• discover.sh https://github.com/user/my-skill — check before installing
• discover.sh user/my-skill — same, short form

Step 2: Present results per mode

Discovery mode — ranked list of GitHub repos with skill name, description, stars, last updated, and a one-line verdict.

Pre-install mode — overlap analysis: which of the user's existing skills (including plugin skills) overlap with the candidate by description, and a recommendation to install / skip / replace.

Output

Discovery: a numbered table (repository, stars, updated, INSTALLED/AVAILABLE status). Pre-install: overlap buckets (…

Auto-Fix

Automatically fix common skill issues. Dry-run by default — shows what would change without modifying files.

Overview

Repairs frontmatter problems (missing delimiters, empty descriptions, missing version fields) across user, project, and codex-scope skills, and — in --prune mode — removes broken symlinks and empty skill directories. Plugin/marketplace skills are never modified (changes would be overwritten on update).

Prerequisites

• Claude Code with the skills-janitor plugin installed (provides scripts/fix.sh)
• bash 3.2+ (the stock macOS bash works; no external dependencies)
• Write access to the user's own skill directories (~/.claude/skills, ./.claude/skills, ~/.agents/skills)

Instructions

Step 1: Preview first (always)

bash ~/.claude/skills/skills-janitor/scripts/fix.sh            # preview fixes
bash ~/.claude/skills/skills-janitor/scripts/fix.sh --prune    # preview broken/orphaned removals

Step 2: Show the user the preview and confirm

Never jump straight to --apply. Present the [DRY RUN] lines and ask before writing.

Step 3: Apply

bash ~/.claude/skills/skills-janitor/scripts/fix.sh --apply           # apply fixes
bash ~/.claude/skills/skills-janitor/scripts/fix.sh --prune --apply   # remove broken skills

What it fixes:

• Adds missing frontmatter delimiters (---)
• Fills empty description fields with a template
• Adds missing version field (defaults to "1.0.0")
• Generates template descriptions using the skill folder name

Prune mode finds and removes:

• Broken symlinks — skill folder points to deleted source
• Empty directories — skill folder with no SKILL.md
• Orphaned skills — user-scope copies of plugin skills

Safety model: dry-run by default (must pass --apply to write), skips plugin/marketplace skills, logs ALL changes with timestamps to data/changelog.log, always asks for confirmation before removing.

Output

Per-skill action lines ([DRY RUN] / [FIXED] / [PRUNED] / [SKIP]) followed by a summary of fixable issues, skipped items, and prunable entries. In dry-run mode the summary ends with "Run with --apply to make these changes."

Error Handling

1. Error: A fix produced an unexpected result in a SKILL.md Solution: Every applied change is logged in data/changelog.log with a timestamp — show the log entry and restore the affected field manually; template descriptions are meant …

Health Report

Generate a comprehensive health report combining inventory, quality checks, duplicate detection, and broken skill findings.

Overview

One report covering every place a skill lives: user, project, codex, plugin, and source scopes. Plugin skills appear with their full invocation name (e.g. marketing-skills:image, figma:figma-use) — these were invisible to the v1.2 report. The scan JSON also includes an agents array (subagents from ~/.claude/agents — their descriptions are always-loaded too) and per-plugin update_available (installed commit vs marketplace HEAD) — surface stale plugins and heavy agents in the report.

Modes:

• /janitor-report (default) — full health check: inventory + lint + duplicates + broken
• /janitor-report --brief — inventory only (replaces the old /janitor-audit)

Prerequisites

• Claude Code with the skills-janitor plugin installed (provides scripts/scan.sh, lint.sh, detect_dupes.sh)
• bash 3.2+ (the stock macOS bash works; no external dependencies)
• Read access to ~/.claude/skills, ~/.claude/agents, and installed plugin metadata
• No authentication or API keys required — the scripts read local files only

Instructions

Step 1: Run the scripts

Full report:

bash ~/.claude/skills/skills-janitor/scripts/scan.sh
bash ~/.claude/skills/skills-janitor/scripts/lint.sh
bash ~/.claude/skills/skills-janitor/scripts/detect_dupes.sh

Brief mode (inventory only):

bash ~/.claude/skills/skills-janitor/scripts/scan.sh

Step 2: What each script covers

• Inventory (scan.sh) — all skills across scopes, symlink status, frontmatter fields, line counts; agents and plugins (with update_available) arrays; broken_symlinks count.
• Quality checks (lint.sh) — Critical: broken symlinks, missing SKILL.md, missing frontmatter. Warning: missing/empty name or description, description too short/long, missing version. Info: no body content, no Gotchas section, large files.
• Duplicate detection (detect_dupes.sh) — name collisions (two distinct skills with the same qualified name at different paths) and description overlap (Jaccard similarity >30%), with cross-scope user-vs-plugin pairs explicitly surfaced (e.g. marketing-seo-audit (user) ↔ marketing-skills:seo-audit (plugin)).

Step 3: Present a unified report

Merge the three outputs into one table with severity levels, then recommend actions.

Output

| 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)

Skill Value Report

Show whether each installed skill is earning the context-window tokens it costs.

Overview

Combine token cost and usage tracking into a single view of every installed skill, sorted with the heaviest unused skills at the top. The report splits each skill's cost into what is permanently loaded (the description) and what only loads on demand (the body), then cross-references recent invocations so the user can see which skills are dead weight.

Replaces the v1.2 split between /janitor-tokens (cost only) and /janitor-usage (usage only).

Prerequisites

• Claude Code with the skills-janitor plugin installed (provides scripts/value.sh)
• bash 3.2+ (the stock macOS bash works; no external dependencies)
• Read access to ~/.claude/skills, ~/.claude/agents, and local Claude Code session history
• No authentication or API keys required — the script reads local files only

Instructions

Step 1: Run the value script

bash ~/.claude/skills/skills-janitor/scripts/value.sh [--weeks N] [--budget N] [--json]

• --weeks N — usage lookback window (default: 4)
• --budget N — context window size for % calculations (default: 200000)
• --json — emit raw JSON

Step 2: Present the results

Show the table and summary to the user. When explaining results, do NOT describe body tokens as permanent context cost — only descriptions are always loaded. Plugin-namespaced skills appear with their full invocation name (e.g., marketing-skills:image, figma:figma-use).

Step 3: Suggest action when waste is high

If "unused skill cost" exceeds 20% of the budget, recommend the user run /janitor-report for a full health check or (in v1.4+) /janitor-swipe to triage interactively.

Output

A table of every installed skill with:

• Always — description tokens, permanently in the system prompt (the real context rent)
• Body — the rest of SKILL.md, loaded only when the skill triggers (progressive disclosure)
• Used? — yes if invoked in the lookback window, else NO
• Last Used — date of most recent invocation

Followed by a summary:

• Total tokens loaded into context (the always-loaded TOTAL includes skills plus subagent descriptions from ~/.claude/agents, reported as % of budget)
• Active vs. unused split
• Top wasters: heavy skills with zero usage

Error Handling

1. Error: value.sh: No such file or directory Solution: The plugin is installed under …