# davidliuk/graph-of-skills architecture

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

- Interactive diagram: https://gitdiagram.com/davidliuk/graph-of-skills
- Repository: https://github.com/davidliuk/graph-of-skills

## Overview

GoS turns a library of skill documents into a dependency-aware graph offline, then retrieves a small ranked bundle for an agent’s task. The engine is the central runtime: it coordinates parsing, graph construction and relinking, and online candidate retrieval/reranking. CLI, Claude Code, MCP, and evaluation-facing integrations expose that runtime. The README documents semantic and lexical seeding, merging, graph-aware reranking, and capped bundle output; sampled excerpts do not expose every internal call, so uncertain links are omitted.

Main entry points: [`gos/core/engine.py`](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/engine.py) (Graph engine), [`gos/interfaces/cli.py`](https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/cli.py) (Command-line interface), [`gos/interfaces/claude_code.py`](https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/claude_code.py) (Claude Code interface), [`gos/interfaces/mcp.py`](https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/mcp.py) (MCP interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Skill inputs"]
  node_skill_library["Skill library"]
end

subgraph group_runtime["Graph runtime"]
  node_document_parser["Document parsing<br/>[parsing.py]"]
  node_skill_schema["Skill schema<br/>[schema.py]"]
  node_graph_engine["Graph engine<br/>[engine.py]"]
  node_graph_storage[("Directed graph storage<br/>[storage.py]")]
  node_dependency_relinking["Dependency relinking<br/>[relink.py]"]
  node_retrieval["Skill retrieval<br/>[retrieval.py]"]
  node_prompts["Extraction prompts<br/>[prompts.py]"]
  node_llm_services["LLM services"]
  node_construction_report["Construction report"]
  node_configuration["Runtime configuration<br/>[config.py]"]
end

subgraph group_interfaces["Agent interfaces"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_claude_code["Claude Code interface<br/>[claude_code.py]"]
  node_mcp["MCP interface<br/>[mcp.py]"]
  node_skill_runtime["Agent skill runtime<br/>[skill.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_skillsbench_query["SkillsBench retrieval<br/>[query.py]"]
  node_retrieval_evaluation["Retrieval ablations"]
end

node_agent(("Agent"))

node_skill_library -->|"builds graph from"| node_graph_engine
node_agent -.->|"requests skills"| node_cli
node_agent -.->|"requests skills"| node_claude_code
node_agent -.->|"requests skills"| node_mcp
node_cli -->|"invokes"| node_graph_engine
node_claude_code -->|"invokes"| node_graph_engine
node_mcp -.->|"invokes"| node_graph_engine
node_skill_runtime -->|"uses"| node_graph_engine
node_graph_engine -->|"parses skills"| node_document_parser
node_graph_engine -->|"creates skill nodes"| node_skill_schema
node_graph_engine -->|"scores graph"| node_graph_storage
node_graph_engine -->|"relinks dependencies"| node_dependency_relinking
node_graph_engine -.->|"retrieves candidates"| node_retrieval
node_graph_engine -.->|"uses prompts"| node_prompts
node_graph_engine -.->|"uses LLM services"| node_llm_services
node_graph_engine -.->|"creates report"| node_construction_report
node_graph_engine -.->|"reads settings"| node_configuration
node_agent -.->|"task query"| node_skillsbench_query
node_skillsbench_query -->|"is evaluated by"| node_retrieval_evaluation

click node_document_parser "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/parsing.py"
click node_skill_schema "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/schema.py"
click node_graph_engine "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/engine.py"
click node_graph_storage "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/storage.py"
click node_dependency_relinking "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/relink.py"
click node_retrieval "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/retrieval.py"
click node_prompts "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/prompts.py"
click node_llm_services "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/litellm_services.py"
click node_construction_report "https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/construction_report.py"
click node_configuration "https://github.com/davidliuk/graph-of-skills/blob/main/gos/utils/config.py"
click node_cli "https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/cli.py"
click node_claude_code "https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/claude_code.py"
click node_mcp "https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/mcp.py"
click node_skill_runtime "https://github.com/davidliuk/graph-of-skills/blob/main/evaluation/skill.py"
click node_skillsbench_query "https://github.com/davidliuk/graph-of-skills/blob/main/evaluation/skillsbench/graphskills_assets/query.py"
click node_retrieval_evaluation "https://github.com/davidliuk/graph-of-skills/blob/main/evaluation/analysis/run_retrieval_ablation.py"

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_skill_library toneBlue
class node_document_parser,node_skill_schema,node_graph_engine,node_graph_storage,node_dependency_relinking,node_retrieval,node_prompts,node_llm_services,node_construction_report,node_configuration toneAmber
class node_cli,node_claude_code,node_mcp,node_skill_runtime toneMint
class node_skillsbench_query,node_retrieval_evaluation toneRose
class node_agent toneIndigo
```

## Components

### Skill inputs

- **Skill library**

### Graph runtime

- [Document parsing](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/parsing.py): `gos/core/parsing.py`
- [Skill schema](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/schema.py): `gos/core/schema.py`
- [Graph engine](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/engine.py): `gos/core/engine.py`
- [Directed graph storage](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/storage.py): `gos/core/storage.py`
- [Dependency relinking](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/relink.py): `gos/core/relink.py`
- [Skill retrieval](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/retrieval.py): `gos/core/retrieval.py`
- [Extraction prompts](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/prompts.py): `gos/core/prompts.py`
- [LLM services](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/litellm_services.py): `gos/core/litellm_services.py`
- [Construction report](https://github.com/davidliuk/graph-of-skills/blob/main/gos/core/construction_report.py): `gos/core/construction_report.py`
- [Runtime configuration](https://github.com/davidliuk/graph-of-skills/blob/main/gos/utils/config.py): `gos/utils/config.py`

### Agent interfaces

- [Command-line interface](https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/cli.py): `gos/interfaces/cli.py`
- [Claude Code interface](https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/claude_code.py): `gos/interfaces/claude_code.py`
- [MCP interface](https://github.com/davidliuk/graph-of-skills/blob/main/gos/interfaces/mcp.py): `gos/interfaces/mcp.py`
- [Agent skill runtime](https://github.com/davidliuk/graph-of-skills/blob/main/evaluation/skill.py): `evaluation/skill.py`

### Evaluation

- [SkillsBench retrieval](https://github.com/davidliuk/graph-of-skills/blob/main/evaluation/skillsbench/graphskills_assets/query.py): `evaluation/skillsbench/graphskills_assets/query.py`
- [Retrieval ablations](https://github.com/davidliuk/graph-of-skills/blob/main/evaluation/analysis/run_retrieval_ablation.py): `evaluation/analysis/run_retrieval_ablation.py`

### Other components

- **Agent**

## Connections

- Skill library → Graph engine: builds graph from (evidence: `README.md`)
- Agent → Command-line interface: requests skills
- Agent → Claude Code interface: requests skills
- Agent → MCP interface: requests skills
- Command-line interface → Graph engine: invokes (evidence: `gos/interfaces/cli.py`)
- Claude Code interface → Graph engine: invokes (evidence: `gos/interfaces/claude_code.py`)
- MCP interface → Graph engine: invokes
- Agent skill runtime → Graph engine: uses (evidence: `evaluation/skill.py`)
- Graph engine → Document parsing: parses skills (evidence: `gos/core/engine.py`)
- Graph engine → Skill schema: creates skill nodes (evidence: `gos/core/engine.py`)
- Graph engine → Directed graph storage: scores graph (evidence: `gos/core/engine.py`)
- Graph engine → Dependency relinking: relinks dependencies (evidence: `gos/core/engine.py`)
- Graph engine → Skill retrieval: retrieves candidates (evidence: `gos/core/engine.py`)
- Graph engine → Extraction prompts: uses prompts (evidence: `gos/core/engine.py`)
- Graph engine → LLM services: uses LLM services (evidence: `gos/core/engine.py`)
- Graph engine → Construction report: creates report (evidence: `gos/core/engine.py`)
- Graph engine → Runtime configuration: reads settings (evidence: `gos/core/engine.py`)
- Agent → SkillsBench retrieval: task query
- SkillsBench retrieval → Retrieval ablations: is evaluated by (evidence: `evaluation/analysis/run_retrieval_ablation.py`)
