# alibaba/skill-up architecture

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

- Interactive diagram: https://gitdiagram.com/alibaba/skill-up
- Repository: https://github.com/alibaba/skill-up

## Overview

skill-up is a CLI for evaluating agent skills, agents, and workspaces. The main workflow loads and validates an evaluation, prepares a runtime and case environment, runs an agent, grades its response and workspace changes, then writes structured reports. Configuration and engine adapters support multiple built-in and custom agents; optional MCP provisioning and event logging extend runs. The bundled skill-upper plugin supports an evidence-driven improvement loop. Some branches are mapped from README claims or import references because their implementation excerpts were not provided.

Main entry points: [`internal/cli`](https://github.com/alibaba/skill-up/tree/main/internal/cli) (CLI commands), [`internal/evaluator/evaluator.go`](https://github.com/alibaba/skill-up/blob/main/internal/evaluator/evaluator.go) (Case evaluation), [`plugins/dsh-skill-up/index.js`](https://github.com/alibaba/skill-up/blob/main/plugins/dsh-skill-up/index.js) (skill-upper plugin), [`internal/runner/runner.go`](https://github.com/alibaba/skill-up/blob/main/internal/runner/runner.go) (Run orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_cli["CLI commands"]
  node_config["Eval configuration"]
  node_customengine["Custom engine config"]
end

subgraph group_execution["Evaluation execution"]
  node_runner["Run orchestration<br/>[runner.go]"]
  node_evaluator["Case evaluation<br/>[evaluator.go]"]
  node_agent["Agent engines"]
  node_transcript["Transcript model<br/>[transcript.go]"]
end

subgraph group_environment["Runtime and integrations"]
  node_runtime["Runtime providers"]
  node_mcp["MCP provisioning"]
  node_skillinstall["Skill installation<br/>[installer.go]"]
end

subgraph group_results["Judging and reporting"]
  node_judge["Judge strategies"]
  node_reports["Evaluation reports"]
  node_events["Run event log"]
end

subgraph group_evolution["Skill evolution"]
  node_skillupper["skill-upper plugin<br/>[index.js]"]
  node_plugin_core["Plugin run helpers<br/>[core.js]"]
  node_plugin_observer["Evidence comparison<br/>[observer.js]"]
end

node_user(("CLI user"))
node_sandbox["OpenSandbox service"]
node_docker["Docker runtime"]

node_user -->|"runs commands"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"selects engine"| node_agent
node_cli -->|"starts evaluation"| node_runner
node_cli -->|"streams events"| node_events
node_config -->|"configures custom engine"| node_customengine
node_runner -->|"evaluates plan"| node_evaluator
node_runner -->|"writes results"| node_reports
node_evaluator -->|"runs agent"| node_agent
node_evaluator -->|"prepares runtime"| node_runtime
node_evaluator -->|"provisions MCP"| node_mcp
node_evaluator -->|"grades outcome"| node_judge
node_agent -->|"records conversation"| node_transcript
node_runtime -->|"uses service"| node_sandbox
node_runtime -->|"uses container"| node_docker
node_skillupper -->|"uses helpers"| node_plugin_core
node_skillupper -->|"compares results"| node_plugin_observer
node_skillupper -->|"drives eval loop"| node_cli

click node_cli "https://github.com/alibaba/skill-up/tree/main/internal/cli"
click node_config "https://github.com/alibaba/skill-up/tree/main/internal/config"
click node_runner "https://github.com/alibaba/skill-up/blob/main/internal/runner/runner.go"
click node_evaluator "https://github.com/alibaba/skill-up/blob/main/internal/evaluator/evaluator.go"
click node_agent "https://github.com/alibaba/skill-up/tree/main/internal/agent"
click node_customengine "https://github.com/alibaba/skill-up/tree/main/internal/customengine"
click node_runtime "https://github.com/alibaba/skill-up/tree/main/internal/runtime"
click node_mcp "https://github.com/alibaba/skill-up/tree/main/internal/mcp"
click node_skillinstall "https://github.com/alibaba/skill-up/blob/main/internal/skill/installer.go"
click node_judge "https://github.com/alibaba/skill-up/tree/main/internal/judge"
click node_reports "https://github.com/alibaba/skill-up/tree/main/internal/report"
click node_events "https://github.com/alibaba/skill-up/tree/main/internal/evalevent"
click node_transcript "https://github.com/alibaba/skill-up/blob/main/pkg/transcript/transcript.go"
click node_skillupper "https://github.com/alibaba/skill-up/blob/main/plugins/dsh-skill-up/index.js"
click node_plugin_core "https://github.com/alibaba/skill-up/blob/main/plugins/dsh-skill-up/lib/core.js"
click node_plugin_observer "https://github.com/alibaba/skill-up/blob/main/plugins/dsh-skill-up/lib/observer.js"

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_config,node_customengine,node_user toneBlue
class node_runner,node_evaluator,node_agent,node_transcript toneAmber
class node_runtime,node_mcp,node_skillinstall toneMint
class node_judge,node_reports,node_events toneRose
class node_skillupper,node_plugin_core,node_plugin_observer,node_sandbox,node_docker toneIndigo
```

## Components

### CLI and configuration

- [CLI commands](https://github.com/alibaba/skill-up/tree/main/internal/cli): `internal/cli`
- [Eval configuration](https://github.com/alibaba/skill-up/tree/main/internal/config): `internal/config`
- [Custom engine config](https://github.com/alibaba/skill-up/tree/main/internal/customengine): `internal/customengine`

### Evaluation execution

- [Run orchestration](https://github.com/alibaba/skill-up/blob/main/internal/runner/runner.go): `internal/runner/runner.go`
- [Case evaluation](https://github.com/alibaba/skill-up/blob/main/internal/evaluator/evaluator.go): `internal/evaluator/evaluator.go`
- [Agent engines](https://github.com/alibaba/skill-up/tree/main/internal/agent): `internal/agent`
- [Transcript model](https://github.com/alibaba/skill-up/blob/main/pkg/transcript/transcript.go): `pkg/transcript/transcript.go`

### Runtime and integrations

- [Runtime providers](https://github.com/alibaba/skill-up/tree/main/internal/runtime): `internal/runtime`
- [MCP provisioning](https://github.com/alibaba/skill-up/tree/main/internal/mcp): `internal/mcp`
- [Skill installation](https://github.com/alibaba/skill-up/blob/main/internal/skill/installer.go): `internal/skill/installer.go`

### Judging and reporting

- [Judge strategies](https://github.com/alibaba/skill-up/tree/main/internal/judge): `internal/judge`
- [Evaluation reports](https://github.com/alibaba/skill-up/tree/main/internal/report): `internal/report`
- [Run event log](https://github.com/alibaba/skill-up/tree/main/internal/evalevent): `internal/evalevent`

### Skill evolution

- [skill-upper plugin](https://github.com/alibaba/skill-up/blob/main/plugins/dsh-skill-up/index.js): `plugins/dsh-skill-up/index.js`
- [Plugin run helpers](https://github.com/alibaba/skill-up/blob/main/plugins/dsh-skill-up/lib/core.js): `plugins/dsh-skill-up/lib/core.js`
- [Evidence comparison](https://github.com/alibaba/skill-up/blob/main/plugins/dsh-skill-up/lib/observer.js): `plugins/dsh-skill-up/lib/observer.js`

### Other components

- **CLI user**
- **OpenSandbox service**
- **Docker runtime**

## Connections

- CLI user → CLI commands: runs commands
- CLI commands → Eval configuration: loads config (evidence: `internal/cli/run.go`)
- CLI commands → Agent engines: selects engine (evidence: `internal/cli/run.go`)
- CLI commands → Run orchestration: starts evaluation (evidence: `internal/cli/run.go`)
- CLI commands → Run event log: streams events (evidence: `internal/cli/run_events.go`)
- Eval configuration → Custom engine config: configures custom engine (evidence: `internal/config/customengine.go`)
- Run orchestration → Case evaluation: evaluates plan (evidence: `internal/runner/runner.go`)
- Run orchestration → Evaluation reports: writes results (evidence: `internal/runner/runner.go`)
- Case evaluation → Agent engines: runs agent (evidence: `internal/evaluator/evaluator.go`)
- Case evaluation → Runtime providers: prepares runtime (evidence: `internal/evaluator/evaluator.go`)
- Case evaluation → MCP provisioning: provisions MCP (evidence: `internal/evaluator/evaluator.go`)
- Case evaluation → Judge strategies: grades outcome (evidence: `internal/evaluator/evaluator.go`)
- Agent engines → Transcript model: records conversation (evidence: `internal/agent/codex.go`)
- Runtime providers → OpenSandbox service: uses service (evidence: `internal/runtime/opensandbox.go`)
- Runtime providers → Docker runtime: uses container (evidence: `internal/runtime/docker.go`)
- skill-upper plugin → Plugin run helpers: uses helpers (evidence: `plugins/dsh-skill-up/index.js`)
- skill-upper plugin → Evidence comparison: compares results (evidence: `plugins/dsh-skill-up/index.js`)
- skill-upper plugin → CLI commands: drives eval loop (evidence: `README.md`)