Skills Janitor

Product Introduction

1. Definition: Skills Janitor is an open-source, zero-dependency plugin suite designed specifically for the Claude Code CLI environment. It functions as a comprehensive management layer for Claude Code skills, providing nine specialized commands to audit, deduplicate, lint, fix, and monitor the lifecycle of AI agent capabilities. Technically, it is a collection of Bash and Python-driven scripts that interface with the .claude-plugin architecture to optimize the local skill ecosystem.

2. Core Value Proposition: As developers increasingly adopt Claude Code for autonomous programming, the local "skills" directory often becomes cluttered with redundant, broken, or unused commands. Skills Janitor exists to solve the "skill bloat" problem by offering automated maintenance and discovery. It enables users to maintain high-performance AI agents through periodic auditing, usage analytics, and GitHub-based skill comparison, ensuring that the LLM only interacts with high-quality, relevant tools.

Main Features

1. Automated Skill Auditing and Reporting (/janitor-audit & /janitor-report): These commands perform a deep scan of the installed skills directory (~/.claude/skills/). The audit functionality generates a complete inventory of every available command, while the report feature provides a high-level health check. This includes metadata validation, file structure integrity, and a summary of the overall health of the skill ecosystem.

2. Usage Tracking and Lifecycle Analytics (/janitor-usage): By parsing local conversation history, Skills Janitor identifies which skills are frequently invoked and which remain dormant. This feature calculates percentage-based activity metrics over specific time periods (e.g., last 4 weeks), allowing developers to prune unused assets and reduce the cognitive load on the Claude model.

3. Redundancy and Error Detection (/janitor-duplicates & /janitor-check): The /janitor-duplicates command identifies skills with overlapping functionality or identical command triggers, preventing execution conflicts. The /janitor-check command acts as a linter for skill definitions, flagging syntax errors, missing metadata, or malformed SKILL.md files that could cause the Claude Code agent to fail during tool selection.

4. Safe Automated Resolution (/janitor-fix & /janitor-cleanup): These utilities provide the "Janitor" service by automatically correcting common skill errors. The /janitor-fix command employs a "safe preview" or dry-run mode by default, allowing users to review proposed changes to skill configurations before they are committed. /janitor-cleanup facilitates the removal of verified broken skills that cannot be salvaged.

5. Global Skill Discovery and Comparison (/janitor-search & /janitor-compare): Extending beyond the local environment, these commands interface with the GitHub API to search for new Claude Code skills by keyword. The /janitor-compare feature allows users to perform a market analysis of their local skills against public alternatives, evaluating stars, maintenance activity, and feature sets to determine if a superior community-driven version exists.

Problems Solved

1. Pain Point: Skill Bloat and Performance Degradation. When an AI agent has access to dozens of redundant or low-quality skills, the context window is filled with unnecessary documentation, which can lead to "hallucinations" or incorrect tool selection. Skills Janitor mitigates this by enforcing a "lean" skill directory.

2. Target Audience: This tool is essential for Power Users of Claude Code, AI Engineers building custom agentic workflows, and DevOps teams managing standardized developer environments where Claude Code is a primary CLI tool.

3. Use Cases: A developer who has experimented with various n8n or AWS skills can use Skills Janitor to identify which specific implementation they actually use in daily work. Another scenario involves a team lead auditing a shared repository of internal skills to ensure every team member is using the most up-to-date and functional versions without manual verification.

Unique Advantages

1. Differentiation: Unlike manual file management, Skills Janitor treats "skills" as first-class objects. It provides a structured CLI interface for maintenance that feels native to the Claude Code environment. While other tools focus on the creation of skills, Skills Janitor is the first dedicated utility for the post-installation maintenance and optimization phase.

2. Key Innovation: The zero-dependency architecture is a significant technical advantage. By relying solely on Bash, Python 3, and curl, it bypasses the "dependency hell" often associated with node_modules or pip-heavy plugins. This ensures it can be installed and executed instantly in any environment where Claude Code is running, including restricted or containerized dev environments.

Frequently Asked Questions (FAQ)

1. How do I install Skills Janitor into my Claude Code environment? The most efficient way to install Skills Janitor is via the Claude Code plugin marketplace using the command: /plugin marketplace add khendzel/skills-janitor. Alternatively, you can clone the repository directly into your local skills directory using git clone.

2. Is it safe to use the /janitor-fix command on my custom skills? Yes, safety is a core design principle. Skills Janitor operates with a dry-run default for all potentially destructive or additive operations. The /janitor-fix command provides a preview of changes, and the tool never deletes skills without explicit user confirmation.

3. Does Skills Janitor require a GitHub API token for searching? While /janitor-search and /janitor-compare function with basic curl requests, setting a GITHUB_TOKEN environment variable is highly recommended. This allows for higher rate limits and more detailed repository data when discovering and comparing new Claude Code skills from the global community.