janitor-fix
Automatically fix skill problems (safe preview first). Also use with --prune to find and remove broken symlinks, empty directories, and orphaned skills. Trigger with '/janitor-fix'.
How do I install this agent skill?
npx skills add https://github.com/khendzel/skills-janitor --skill janitor-fixIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a maintenance utility designed to audit and repair AI agent skill files. It identifies formatting issues, fixes metadata, and cleans up broken symlinks or empty directories. It follows safety best practices by defaulting to dry-run mode and requiring explicit user confirmation before applying any changes.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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
descriptionfields with a template - Adds missing
versionfield (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
-
Error: A fix produced an unexpected result in a SKILL.md Solution: Every applied change is logged in
data/changelog.logwith a timestamp — show the log entry and restore the affected field manually; template descriptions are meant to be replaced by the author. -
Error:
[SKIP] Plugin/marketplace skill - don't modifySolution: Expected behavior, not an error. Plugin content is fixed upstream — suggest the user report the issue to the plugin author instead. -
Error: Prune lists a skill the user wants to keep Solution: Do not run
--apply. A "broken symlink" that should be kept means its target moved — recreate the link (ln -sfn <new-target> <link>) instead of pruning.
Examples
Example 1: Safe fix cycle
Input: "Fix my skills."
Output: Run the dry-run, present the [DRY RUN] list ("3 fixable: 2 missing descriptions, 1 missing version"), ask for confirmation, then run --apply and report the [FIXED] lines.
Example 2: Cleanup of broken leftovers
Input: "Remove broken skills."
Output: Run --prune (dry-run), show what would be removed and why (broken symlink targets, empty dirs), confirm, then --prune --apply and report the [PRUNED] lines.
Resources
- Fix script (plugin-relative):
{baseDir}/../../scripts/fix.sh - Change log of applied fixes:
data/changelog.login the plugin directory - For finding issues:
/janitor-report - For usage + token cost:
/janitor-value
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/khendzel/skills-janitor/janitor-fix">View janitor-fix on skillZs</a>