$ show scottcwy/skill-kits
Skill-kits is a local-first, single-binary desktop utility for managing AI agent skill directories across multiple coding agents (Codex, Claude Code, Gemini CLI, and custom agents). It operates by observing the filesystem: skills are directories containing a SKILL.md (or SKILL.md.disabled) file that agents read directly. The tool provides both a CLI (via clap) and a native GUI (via egui/eframe) that share a common core library. It does not move skills to the cloud, run a server, or require Node.js/Python runtimes. Architecturally, the system is a Rust monolith with three layers: a core library (src/core/) containing all business logic (agent space scanning, skill installation, project deployment, registry management, health checks, risk scanning), a CLI layer (src/cli/) for argument parsing and output formatting, and a GUI layer (src/gui/) for the desktop workbench. Persistent state is stored in TOML files under ~/.skill-kits/, including registries for managed skills, deployments, and a skill instance index cache. The system uses content hashing (SHA-256) for identity and drift detection, and atomic file writes for all state mutations. Key entry points include the CLI commands (status, scan, list, enable, disable, install, uninstall, doctor, adopt, project, plugin) and the GUI application launched with --gui. The core data flow involves scanning agent skill directories (global and project-level), building a normalized index of skill instances, comparing against managed copies and project deployments, and presenting the user with actionable status (drift, outdated, missing, etc.). The doctor module performs comprehensive health checks and can auto-fix certain issues. External dependencies are minimal: the Rust standard library plus crates for CLI parsing (clap), GUI (egui/eframe), serialization (serde, toml), hashing (sha2), filesystem walking (walkdir), and TOML editing (toml_edit). The system is designed to be offline-first and respects the filesystem as the source of truth for skill enablement.
The LLM identified 6 files worth highlighting for reuse:
Provides atomic file write operations using a temporary file and rename, with cleanup on failure. This pattern ensures that state files (TOML registries, config) are never left in a partially written state, which is critical for a local-first tool that may be interrupted. The implementation is self-contained and could be extracted into any Rust project requiring safe file writes.
Implements a PID-based lock file (StateLock) to prevent concurrent access to the skill-kits state directory. Includes stale lock detection by checking if the owning process is still alive (via /proc or kill -0). This is a reusable pattern for any CLI tool that needs to serialize access to shared resources.
Computes SHA-256 hashes over skill directories with normalization: ignores noise files (.DS_Store, temp files, .skill-kits dirs) and treats SKILL.md and SKILL.md.disabled as equivalent so that toggling does not change the hash. This enables stable identity and drift detection. The normalization logic is well-encapsulated and could be adapted for other content-addressed systems.
Defines the AgentAdapter trait that abstracts per-agent skill directory resolution. Built-in adapters for Codex, Claude, and Gemini CLI provide default global and project skill paths. Custom agents can be configured via config.toml. This trait-based design allows easy extension to new agents without modifying core logic, and the pattern is reusable for any multi-backend configuration system.
Manages atomic read-modify-write cycles for TOML-based registries (skills, deployments, skill instances). Uses a lock guard to ensure consistency across multiple registry files. The update_registry_files helper allows atomic multi-registry writes under a single lock. This pattern is reusable for any application needing safe, concurrent state persistence.
Implements the GuiModel and GuiController pattern for the desktop GUI. The model holds UI state, selections, and filters, while the controller executes user intents via an mpsc channel queue with background worker. This decouples UI rendering from action execution and supports inline confirmation for destructive operations. The pattern is a clean example of state management in egui applications.