khendzelkhendzel/skills-janitor/skills/janitor-discover/SKILL.md

janitor-discover

Skill123 starsChanged 3 months agoMITView on GitHub

Find new skills on GitHub or check a specific skill before installing. Use when the user wants to search for skills, evaluate a skill URL, check overlap and security risk before installing, or compare a local skill against alternatives. Trigger with '/janitor-discover'.

Reads credentials

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

juanmackie/juanskillsedited, first seen Oct 20, 2026

Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
juanmackie/juanskills★ 196% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- janitor-fixSkill
- janitor-reportSkill
- janitor-securitySkill
- janitor-swipeSkill
- janitor-valueSkill

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Error: No results for a valid topic
line 90
Very specific:
Output: Run discover.sh n8n, present the ranked table, and flag any result already installed.
line 102
Very specific:
Output: Run discover.sh https://github.com/user/seo-helper, then summarize: overlap with existing skills, the verdict (e.g.
line 108
Very specific:
Search cache: data/search-cache.json (24h TTL)
line 119

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free