# noviadi/sikil architecture

> Architecture diagram of the GitHub repository noviadi/sikil, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noviadi/sikil
- Repository: https://github.com/noviadi/sikil

## Overview

Sikil is a Rust CLI for discovering and managing Agent Skills across several coding agents. The main workflow is to scan configured agent locations, parse skill metadata, report installations and conflicts, then install, synchronize, adopt, unmanage, validate, or remove skills. Commands coordinate domain logic and filesystem operations, with shared configuration, cache, manifest/provenance, and output support. The README documents the overall layering and capabilities; source relationships below are limited to those visible in excerpts or the source index.

Main entry points: [`src/core/scanner.rs`](https://github.com/noviadi/sikil/blob/main/src/core/scanner.rs) (Skill scanner), [`src/cli/app.rs`](https://github.com/noviadi/sikil/blob/main/src/cli/app.rs) (CLI dispatch), [`src/commands/install.rs`](https://github.com/noviadi/sikil/blob/main/src/commands/install.rs) (Install), [`src/utils/atomic.rs`](https://github.com/noviadi/sikil/blob/main/src/utils/atomic.rs) (Atomic operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and commands"]
  node_cli["CLI dispatch<br/>[app.rs]"]
  node_install["Install<br/>[install.rs]"]
  node_list["List and conflicts<br/>[list.rs]"]
  node_show["Show details<br/>[show.rs]"]
  node_adopt["Adopt skills<br/>[adopt.rs]"]
  node_sync["Synchronize<br/>[sync.rs]"]
  node_validate["Validate<br/>[validate.rs]"]
  node_remove["Remove<br/>[remove.rs]"]
  node_unmanage["Unmanage<br/>[unmanage.rs]"]
end

subgraph group_domain["Skill domain"]
  node_scanner["Skill scanner<br/>[scanner.rs]"]
  node_parser["Metadata parser<br/>[parser.rs]"]
  node_skill["Skill model<br/>[skill.rs]"]
  node_conflicts["Conflict detection<br/>[conflicts.rs]"]
  node_manifest["Project manifest<br/>[manifest.rs]"]
  node_provenance["Skill provenance<br/>[provenance.rs]"]
end

subgraph group_storage["Filesystem operations"]
  node_git["Git acquisition<br/>[git.rs]"]
  node_symlink["Symlink manager<br/>[symlink.rs]"]
  node_atomic["Atomic operations<br/>[atomic.rs]"]
  node_paths["Path utilities<br/>[paths.rs]"]
end

subgraph group_support["Shared support"]
  node_config["Agent configuration<br/>[config.rs]"]
  node_cache[("Scan cache<br/>[cache.rs]")]
  node_output["CLI output<br/>[output.rs]"]
end

node_user(("CLI user"))

node_user -->|"invokes"| node_cli
node_cli -.->|"dispatches"| node_install
node_cli -.->|"dispatches"| node_list
node_cli -.->|"dispatches"| node_show
node_cli -.->|"dispatches"| node_adopt
node_cli -.->|"dispatches"| node_sync
node_cli -.->|"dispatches"| node_validate
node_cli -.->|"dispatches"| node_remove
node_cli -.->|"dispatches"| node_unmanage
node_install -->|"fetches from"| node_git
node_install -->|"parses skill"| node_parser
node_install -->|"writes safely"| node_atomic
node_install -->|"links installs"| node_symlink
node_install -->|"reads settings"| node_config
node_list -->|"scans locations"| node_scanner
node_list -->|"checks conflicts"| node_conflicts
node_list -->|"reads settings"| node_config
node_list -->|"formats results"| node_output
node_scanner -->|"parses entries"| node_parser
node_scanner -->|"reads and writes"| node_cache
node_scanner -->|"builds models"| node_skill
node_scanner -->|"uses settings"| node_config
node_scanner -->|"checks links"| node_symlink
node_show -->|"finds installation"| node_scanner
node_show -->|"uses model"| node_skill
node_adopt -->|"locates skills"| node_scanner
node_adopt -->|"moves safely"| node_atomic
node_adopt -->|"links installs"| node_symlink
node_sync -->|"updates links"| node_symlink
node_sync -->|"reads settings"| node_config
node_validate -->|"validates metadata"| node_parser
node_validate -->|"finds installed skill"| node_scanner
node_remove -->|"locates installs"| node_scanner
node_remove -->|"removes safely"| node_atomic
node_unmanage -->|"locates installs"| node_scanner
node_unmanage -->|"updates safely"| node_atomic
node_manifest -->|"writes atomically"| node_atomic
node_provenance -->|"uses manifest"| node_manifest
node_provenance -->|"writes safely"| node_atomic

click node_cli "https://github.com/noviadi/sikil/blob/main/src/cli/app.rs"
click node_install "https://github.com/noviadi/sikil/blob/main/src/commands/install.rs"
click node_list "https://github.com/noviadi/sikil/blob/main/src/commands/list.rs"
click node_show "https://github.com/noviadi/sikil/blob/main/src/commands/show.rs"
click node_adopt "https://github.com/noviadi/sikil/blob/main/src/commands/adopt.rs"
click node_sync "https://github.com/noviadi/sikil/blob/main/src/commands/sync.rs"
click node_validate "https://github.com/noviadi/sikil/blob/main/src/commands/validate.rs"
click node_remove "https://github.com/noviadi/sikil/blob/main/src/commands/remove.rs"
click node_unmanage "https://github.com/noviadi/sikil/blob/main/src/commands/unmanage.rs"
click node_scanner "https://github.com/noviadi/sikil/blob/main/src/core/scanner.rs"
click node_parser "https://github.com/noviadi/sikil/blob/main/src/core/parser.rs"
click node_skill "https://github.com/noviadi/sikil/blob/main/src/core/skill.rs"
click node_conflicts "https://github.com/noviadi/sikil/blob/main/src/core/conflicts.rs"
click node_manifest "https://github.com/noviadi/sikil/blob/main/src/core/manifest.rs"
click node_provenance "https://github.com/noviadi/sikil/blob/main/src/core/provenance.rs"
click node_git "https://github.com/noviadi/sikil/blob/main/src/utils/git.rs"
click node_symlink "https://github.com/noviadi/sikil/blob/main/src/utils/symlink.rs"
click node_atomic "https://github.com/noviadi/sikil/blob/main/src/utils/atomic.rs"
click node_paths "https://github.com/noviadi/sikil/blob/main/src/utils/paths.rs"
click node_config "https://github.com/noviadi/sikil/blob/main/src/core/config.rs"
click node_cache "https://github.com/noviadi/sikil/blob/main/src/core/cache.rs"
click node_output "https://github.com/noviadi/sikil/blob/main/src/cli/output.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_install,node_list,node_show,node_adopt,node_sync,node_validate,node_remove,node_unmanage,node_user toneBlue
class node_scanner,node_parser,node_skill,node_conflicts,node_manifest,node_provenance toneAmber
class node_git,node_symlink,node_atomic,node_paths toneMint
class node_config,node_cache,node_output toneRose
```

## Components

### CLI and commands

- [CLI dispatch](https://github.com/noviadi/sikil/blob/main/src/cli/app.rs): `src/cli/app.rs`
- [Install](https://github.com/noviadi/sikil/blob/main/src/commands/install.rs): `src/commands/install.rs`
- [List and conflicts](https://github.com/noviadi/sikil/blob/main/src/commands/list.rs): `src/commands/list.rs`
- [Show details](https://github.com/noviadi/sikil/blob/main/src/commands/show.rs): `src/commands/show.rs`
- [Adopt skills](https://github.com/noviadi/sikil/blob/main/src/commands/adopt.rs): `src/commands/adopt.rs`
- [Synchronize](https://github.com/noviadi/sikil/blob/main/src/commands/sync.rs): `src/commands/sync.rs`
- [Validate](https://github.com/noviadi/sikil/blob/main/src/commands/validate.rs): `src/commands/validate.rs`
- [Remove](https://github.com/noviadi/sikil/blob/main/src/commands/remove.rs): `src/commands/remove.rs`
- [Unmanage](https://github.com/noviadi/sikil/blob/main/src/commands/unmanage.rs): `src/commands/unmanage.rs`

### Skill domain

- [Skill scanner](https://github.com/noviadi/sikil/blob/main/src/core/scanner.rs): `src/core/scanner.rs`
- [Metadata parser](https://github.com/noviadi/sikil/blob/main/src/core/parser.rs): `src/core/parser.rs`
- [Skill model](https://github.com/noviadi/sikil/blob/main/src/core/skill.rs): `src/core/skill.rs`
- [Conflict detection](https://github.com/noviadi/sikil/blob/main/src/core/conflicts.rs): `src/core/conflicts.rs`
- [Project manifest](https://github.com/noviadi/sikil/blob/main/src/core/manifest.rs): `src/core/manifest.rs`
- [Skill provenance](https://github.com/noviadi/sikil/blob/main/src/core/provenance.rs): `src/core/provenance.rs`

### Filesystem operations

- [Git acquisition](https://github.com/noviadi/sikil/blob/main/src/utils/git.rs): `src/utils/git.rs`
- [Symlink manager](https://github.com/noviadi/sikil/blob/main/src/utils/symlink.rs): `src/utils/symlink.rs`
- [Atomic operations](https://github.com/noviadi/sikil/blob/main/src/utils/atomic.rs): `src/utils/atomic.rs`
- [Path utilities](https://github.com/noviadi/sikil/blob/main/src/utils/paths.rs): `src/utils/paths.rs`

### Shared support

- [Agent configuration](https://github.com/noviadi/sikil/blob/main/src/core/config.rs): `src/core/config.rs`
- [Scan cache](https://github.com/noviadi/sikil/blob/main/src/core/cache.rs): `src/core/cache.rs`
- [CLI output](https://github.com/noviadi/sikil/blob/main/src/cli/output.rs): `src/cli/output.rs`

### Other components

- **CLI user**

## Connections

- CLI user → CLI dispatch: invokes (evidence: `README.md`)
- CLI dispatch → Install: dispatches
- CLI dispatch → List and conflicts: dispatches
- CLI dispatch → Show details: dispatches
- CLI dispatch → Adopt skills: dispatches
- CLI dispatch → Synchronize: dispatches
- CLI dispatch → Validate: dispatches
- CLI dispatch → Remove: dispatches
- CLI dispatch → Unmanage: dispatches
- Install → Git acquisition: fetches from (evidence: `src/commands/install.rs`)
- Install → Metadata parser: parses skill (evidence: `src/commands/install.rs`)
- Install → Atomic operations: writes safely (evidence: `src/commands/install.rs`)
- Install → Symlink manager: links installs (evidence: `src/commands/install.rs`)
- Install → Agent configuration: reads settings (evidence: `src/commands/install.rs`)
- List and conflicts → Skill scanner: scans locations (evidence: `src/commands/list.rs`)
- List and conflicts → Conflict detection: checks conflicts (evidence: `src/commands/list.rs`)
- List and conflicts → Agent configuration: reads settings (evidence: `src/commands/list.rs`)
- List and conflicts → CLI output: formats results (evidence: `src/commands/list.rs`)
- Skill scanner → Metadata parser: parses entries (evidence: `src/core/scanner.rs`)
- Skill scanner → Scan cache: reads and writes (evidence: `src/core/scanner.rs`)
- Skill scanner → Skill model: builds models (evidence: `src/core/scanner.rs`)
- Skill scanner → Agent configuration: uses settings (evidence: `src/core/scanner.rs`)
- Skill scanner → Symlink manager: checks links (evidence: `src/core/scanner.rs`)
- Show details → Skill scanner: finds installation (evidence: `src/commands/show.rs`)
- Show details → Skill model: uses model (evidence: `src/commands/show.rs`)
- Adopt skills → Skill scanner: locates skills (evidence: `src/commands/adopt.rs`)
- Adopt skills → Atomic operations: moves safely (evidence: `src/commands/adopt.rs`)
- Adopt skills → Symlink manager: links installs (evidence: `src/commands/adopt.rs`)
- Synchronize → Symlink manager: updates links (evidence: `src/commands/sync.rs`)
- Synchronize → Agent configuration: reads settings (evidence: `src/commands/sync.rs`)
- Validate → Metadata parser: validates metadata (evidence: `src/commands/validate.rs`)
- Validate → Skill scanner: finds installed skill (evidence: `src/commands/validate.rs`)
- Remove → Skill scanner: locates installs (evidence: `src/commands/remove.rs`)
- Remove → Atomic operations: removes safely (evidence: `src/commands/remove.rs`)
- Unmanage → Skill scanner: locates installs (evidence: `src/commands/unmanage.rs`)
- Unmanage → Atomic operations: updates safely (evidence: `src/commands/unmanage.rs`)
- Project manifest → Atomic operations: writes atomically (evidence: `src/core/manifest.rs`)
- Skill provenance → Project manifest: uses manifest (evidence: `src/core/provenance.rs`)
- Skill provenance → Atomic operations: writes safely (evidence: `src/core/provenance.rs`)
