janitor-discover

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.

Argument	Mode	What runs
Keyword(s) like seo or n8n workflows	Discovery	search.sh — find matching skills on GitHub
--compare <skill-name>	Comparison	search.sh --compare — find alternatives to a local skill
Full URL: https://github.com/user/skill	Pre-install check	precheck.sh — analyze before installing
Short repo: user/skill	Pre-install check	precheck.sh (auto-expanded to URL)
Local path: ~/path/to/skill	Pre-install check	precheck.sh (local folder)

Pre-install mode runs two checks, not one: overlap against what's already installed, and (since v1.6) a security scan of the candidate via security.sh — the same heuristics /janitor-security uses on installed 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 — two sections. First, 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. Second, a --- Security (<scope>) --- block.

Always report the security scope back to the user, because it differs by source:

Source	Scanned
Local path	Full directory — SKILL.md and bundled scripts
URL / user/repo	Fetched SKILL.md only — scripts are never downloaded, so re-check after cloning

A PASS on a remote URL therefore means "nothing suspicious in the text we could see", not "this repo is safe". Say so when the candidate ships scripts.

Output

Discovery: a numbered table (repository, stars, updated, INSTALLED/AVAILABLE status).

Pre-install: overlap buckets (HIGH ≥60%, MODERATE 30–59%, LOW <30%) with shared keywords and a final verdict line (HIGH_OVERLAP / MODERATE_OVERLAP / SAFE), plus a security block that prints either No suspicious patterns found. (PASS), Security scan unavailable. (UNKNOWN), or VERDICT: REVIEW|RISK followed by one severity + title + evidence line per finding. With --json, the same data lands under a security key (verdict, scope, findings).

Error Handling

1. Error: GitHub API rate limit exceeded Solution: Set the GITHUB_TOKEN environment variable (any classic token, no scopes needed) and re-run; anonymous search allows only a few requests per minute.

2. Error: Could not fetch SKILL.md from <url> Solution: The repo keeps its SKILL.md at a non-standard path — pass a direct URL to the SKILL.md file, or a local clone path instead.

3. Error: No results for a valid topic Solution: The relevance gate drops repos without any skill signal. Broaden the keyword (e.g. n8n skill → n8n) or check the cached results note — results are cached for 24h in data/search-cache.json.

4. Error: Security scan unavailable. (verdict UNKNOWN) Solution: security.sh failed or returned no parseable JSON — the overlap result is still valid, but do not present the candidate as security-checked. Re-run, or scan after cloning with /janitor-security.

Examples

Example 1: Find skills by topic

Input: "Find me an n8n skill."

Output: Run discover.sh n8n, present the ranked table, and flag any result already installed.

Example 2: Check before installing

Input: "Is github.com/user/seo-helper worth installing?"

Output: Run discover.sh https://github.com/user/seo-helper, then summarize: overlap with existing skills, the verdict (e.g. "MODERATE_OVERLAP — 45% with marketing-skills:seo-audit"), the security verdict, and a recommendation. Note that only the fetched SKILL.md was scanned.

Example 3: Candidate trips the security scan

Input: "Check user/handy-helper before I install it."

Output: Run discover.sh user/handy-helper. If the security block reports VERDICT: RISK, lead with that rather than the overlap number — quote the finding's severity, title and evidence, explain that RISK means "read this before trusting it" (not "malware"), and remind the user that bundled scripts were not fetched.

Resources

• Dispatcher (plugin-relative): {baseDir}/../../scripts/discover.sh
• Search cache: data/search-cache.json (24h TTL)
• /janitor-security — same scan, run across everything already installed
• /janitor-report — health check of currently installed skills
• /janitor-value — are existing skills earning their context cost
• /janitor-fix — fix issues with installed skills