How It Works
Skills Janitor is a runtime defense tool designed to manage and secure the skills, subagents, and MCP servers used within Claude Code environments. It operates as a lightweight, dependency-free utility that integrates directly with Claude Code and OpenAI Codex. The tool functions through a set of six core commands, each addressing specific aspects of skill and server management, from inventory checks to security audits.
The tool scans every location where skills reside, including user-installed, project-specific, Codex-hosted, and plugin-installed skills, as well as subagents and MCP servers. It cross-references these against real usage data derived from session transcripts, ensuring that only actively utilized skills and servers remain in the context. This approach minimizes unnecessary context bloat, which can degrade performance and introduce security risks.
The scanner evaluates skills for known bad shapes, such as instruction-override phrases, hidden directives in HTML comments, zero-width Unicode characters, and base64-encoded payloads.
A RISK verdict indicates that further review is recommended before trusting the skill, rather than implying the presence of malware. This calibration ensures low false positives, as demonstrated by tests on a real 178-skill environment, where only two skills were flagged as RISK, both of which required review.
For MCP servers, Skills Janitor inventories all configured servers—whether user-defined, project-specific, or bundled with plugins—and cross-references their usage against session transcripts. Servers that are connected but never called are prioritized for removal, as their tool schemas load into context unnecessarily. The tool provides a clear breakdown of server usage, including the number of distinct tools called, frequency of calls, and the last date of use.
The tool’s interactive TUI (Text User Interface) allows users to swipe through their skill and server collections in a Tinder-like interface. Skills and servers are sorted by likelihood of being unused or redundant, enabling users to quickly delete or retain them. The swipe interface supports actions such as deletion, retention, skipping, undoing, and inspecting full descriptions. Plugin-installed skills are flagged for review rather than direct deletion, as they belong to the plugin ecosystem.
Skills Janitor also includes a duplicate detection mechanism that identifies overlapping skills across different scopes, such as user-installed and plugin-bundled skills. Overlaps are scored using the Jaccard similarity index, which measures the similarity between skill descriptions. This helps users avoid redundant implementations that consume unnecessary context and resources.
The tool is implemented in Shell and requires only Bash, Python 3, and curl, with no additional dependencies or pip installations. It is designed to be self-contained, with each command operating independently. Users can install it via the Claude Code plugin marketplace, using skills.sh, or by cloning the repository directly into their ~/.claude/skills/ directory.
Use Cases
Skills Janitor is primarily used to maintain the efficiency and security of Claude Code environments by reducing context bloat and identifying potential vulnerabilities. One of its key use cases is the management of unused or redundant skills, which can clutter the context and degrade performance. By scanning for skills that are installed but never used, the tool helps users clean up their environments, ensuring that only relevant skills remain active.
Given that skills are essentially text instructions executed by an agent, they can introduce significant risks if compromised. For example, it can identify skills that contain instructions to ignore previous directives or hide information from users, which are common tactics in prompt injection attacks.
The tool also addresses the challenge of managing MCP servers, which can consume context even when unused. By cross-referencing server configurations with actual usage data from session transcripts, Skills Janitor identifies servers that are connected but never called. Users can then remove these servers from their configurations, reducing unnecessary context load and improving efficiency. This is particularly useful in environments with numerous MCP servers, where manual tracking would be impractical.
For developers and users who frequently install new skills, Skills Janitor provides a pre-install security scan through the /janitor-discover command. This allows users to audit a skill’s security before installation, whether it is hosted on GitHub or accessed via a URL.
The tool’s interactive swipe interface is designed for quick triage of skills and servers. Users can efficiently review their collections and remove unused items in seconds, making it ideal for regular maintenance tasks. This is particularly useful in dynamic environments where skills and servers are frequently added or removed. The swipe interface also supports natural language queries, allowing users to ask questions like ‘check my skills’ or ‘which skills are wasting context?’ for a more intuitive experience.
Key Features & Capabilities
- Comprehensive Inventory and Usage Tracking: Skills Janitor scans all installed skills, subagents, and MCP servers, cross-referencing them with real usage data from session transcripts. This ensures that only actively used skills and servers remain in the context, reducing unnecessary bloat and improving performance.
- It evaluates skills for known bad shapes, such as instruction-override phrases, hidden directives, and dangerous scripts, providing verdicts (PASS, REVIEW, RISK) to guide users on whether to trust a skill.
- MCP Server Management: Skills Janitor inventories all configured MCP servers and cross-references their usage with session transcripts. Servers that are connected but never called are prioritized for removal, as their tool schemas load into context unnecessarily. The tool provides detailed usage statistics, including the number of distinct tools called, frequency of calls, and the last date of use.
- Duplicate Detection: The tool identifies overlapping skills across different scopes using the Jaccard similarity index. This helps users avoid redundant implementations that consume unnecessary context and resources, ensuring a leaner and more efficient environment.
- Interactive Swipe Interface: Users can interactively review and manage their skills and servers using a Tinder-like swipe interface. The interface sorts items by likelihood of being unused or redundant, allowing users to quickly delete or retain them. It supports actions such as deletion, retention, skipping, undoing, and inspecting full descriptions.
- Pre-Install Security Checks: The /janitor-discover command allows users to audit a skill’s security before installation.
- Zero Dependencies and Lightweight Design: Skills Janitor requires only Bash, Python 3, and curl, with no additional dependencies or pip installations. This makes it easy to install and use across different environments, including via the Claude Code plugin marketplace, skills.sh, or direct repository cloning.
- Backup and Reversibility: When removing skills or MCP servers, Skills Janitor creates timestamped backup files (.bak), allowing users to revert changes if needed. This ensures that deletions are safe and reversible, reducing the risk of accidental data loss.
- Natural Language Queries: Users can interact with Skills Janitor using natural language commands, such as ‘check my skills’ or ‘which skills are wasting context?’ This makes the tool more accessible and intuitive for users who may not be familiar with command-line interfaces.
- Calibrated Security Alerts: The tool’s security scanner is calibrated to minimize false positives. In tests on a real 178-skill environment, only two skills were flagged as RISK, both of which required review.
- Support for Plugin Skills: While plugin-installed skills cannot be deleted individually, Skills Janitor flags them for review, ensuring that users are aware of potential issues without disrupting the plugin ecosystem.
- It includes fixes for parsing issues related to YAML block-scalar headers, apostrophes, and CRLF files, ensuring robust operation in real-world scenarios.