haydenull/skills-manager

1. What this app is

- skills-manager is an Electron desktop app that manages local “skills” for two external agents: Claude Code and Codex.

- The core job is to install, update, debug-toggle, and remove skills from the user’s local filesystem and from the agents’ configured skills directories.

2. Top-level process split

- The repository is clearly divided into Electron’s three-part architecture:

- src/main: privileged backend/runtime process

- src/preload: typed IPC bridge

- src/renderer: React UI

- This boundary matters because the renderer handles user interaction only, while filesystem, network, and OS integration live in the main process.

3. Main-process domain layer

- src/main/skills-service.ts is the likely core domain service for skill management.

- It appears to own the business logic for:

- discovering skills from GitHub, GitLab, or local directories

- reading update metadata

- installing/removing skills into managed storage

- switching debug mode between managed storage and a user-selected local directory

- syncing entries into Claude Code / Codex skill locations

- This is the main architectural boundary where repository-independent skill logic lives.

4. Renderer UI structure

- The renderer is a single-page React app with route-based screens under src/renderer/src/routes.

- Main screens are:

- install.tsx for previewing and installing skills from a source

- settings.tsx for theme, GitLab tokens, update checks, and directory shortcuts

- index.tsx as the installed-skills view

- __root.tsx and routeTree.gen.ts indicate TanStack Router-style routing with generated route metadata.

5. Renderer-to-main data flow

- The renderer never directly touches the filesystem or external APIs.

- Instead, UI actions call typed query/helper modules such as:

- src/renderer/src/skills-queries.ts

- likely IPC-backed data access from the preload bridge

- That gives the architecture a clean flow: user action in React UI → IPC call → main-process service → filesystem/network result → UI state update.

6. Preload as the trust boundary

- src/preload/index.ts and its declarations in src/preload/index.d.ts provide the secure bridge between renderer and main.

- The existence of explicit typings suggests the app exposes a limited API surface rather than enabling arbitrary Node access in the UI.

- This is the key security boundary for a desktop app that manages local files and tokens.

7. Shared types and UI/domain consistency

- src/shared/skills-types.ts contains shared TypeScript contracts used by both sides.

- This likely includes the shape of a skill record, install/update metadata, source descriptors, and agent targets.

- Shared types keep renderer views and main-process operations aligned, which is important because the app’s data model crosses process boundaries.

8. External source and update model

- The README shows three source classes the architecture must support:

- GitHub repositories

- self-hosted GitLab repositories

- local directories

- Update detection differs by source:

- GitHub uses directory tree SHA comparison

- GitLab and local sources use sha256 file-hash-based tracking

- This implies the main service needs source-specific adapters and metadata normalization before the UI can present “updatable” status.

9. Filesystem integration and agent directories

- The app manages two external filesystem targets:

- Claude Code skills directory

- Codex skills directory

- Default locations are user-home based, but can be overridden via environment variables (CLAUDE_CONFIG_DIR, CODEX_HOME).

- The app also stores its own managed copy of skills in an application data directory, which acts as the authoritative local cache for installed skills and debug state.

10. GitLab token storage and authenticated access

- Settings include per-host GitLab Personal Access Tokens.

- The token is associated with a GitLab host, not globally, which implies the main process persists host-scoped credentials and injects them only when calling the matching GitLab API.

- This is a separate infrastructure concern from skill storage and affects source fetching only.

11. Update and distribution layer

- App self-update is part of the settings screen, so the main process likely integrates with Electron update or release mechanics.

- Build and packaging are handled by:

- electron-vite for development/build bundling

- electron-builder.yml for packaging/distribution

- GitHub Actions release workflow under .github/workflows/release.yml

- This makes the repo both an app and a distributable desktop product.

12. UI composition and styling

- The renderer uses React components plus local CSS assets:

- src/renderer/src/assets/base.css

- src/renderer/src/assets/main.css

- src/renderer/src/components/Versions.tsx

- The UI appears lightweight and route-driven rather than using a heavy global state framework.

- Styling and component structure are secondary to the app’s main concern: presenting skill inventory and actions.

13. Architecture diagram emphasis

- If drawing the system, the most important boxes are:

- React renderer screens

- preload IPC bridge

- main-process skill service

- managed app-data skill store

- external agent directories for Claude Code and Codex

- remote skill sources: GitHub/GitLab/local filesystem

- The primary arrows are:

- UI requests → IPC → skill service

- skill service ↔ remote source

- skill service ↔ managed store

- skill service → agent directories

- settings ↔ persisted app config/token store

14. Repo shape summary

- This is not a server-client app; it is a desktop orchestration tool with a thin UI and a centralized main-process domain service.

- The architecture is optimized for safe local automation around filesystem state, source fetching, and agent-specific integration rather than for network serving or background distributed compute.