# ruc-datalab/skilladam architecture

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

- Interactive diagram: https://gitdiagram.com/ruc-datalab/skilladam
- Repository: https://github.com/ruc-datalab/skilladam

## Overview

SkillAdam is an agent-facing tool for improving a skill file: a user requests an optimization, the product prepares tasks and scoring, runs the current and revised skill, and validates proposed edits before applying them. The central runtime connects product services to rollout/model execution and the SkillAdam optimization loop, then supports persisted runs and optional per-edit review. The README documents Codex, Claude Code, Cursor Agent, and Copilot support. Edges are limited to relationships shown in the README or source index/excerpts; several adapter and persistence details are unsampled.

Main entry points: [`skilladam/product/service.py`](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/service.py) (Run Service), [`skilladam/methods/skilladam.py`](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/methods/skilladam.py) (SkillAdam Runner), [`skilladam/product/patch_review.py`](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/patch_review.py) (Patch Selection), [`skilladam/execution/evaluate.py`](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/execution/evaluate.py) (Evaluation Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Agent Product"]
  node_product_api["Product Adapters<br/>[product_mcp.py]"]
  node_service["Run Service<br/>[service.py]"]
  node_task_setup["Task Setup<br/>[tasking.py]"]
  node_workflow["Product Workflow<br/>[workflow.py]"]
  node_session[("Session State<br/>[session_store.py]")]
  node_review_tools["Hunk Review"]
  node_patch_review["Patch Selection<br/>[patch_review.py]"]
  node_model["Product Model<br/>[model.py]"]
end

subgraph group_optimization["Optimization Core"]
  node_skilladam_runner["SkillAdam Runner<br/>[skilladam.py]"]
  node_feedback_loop["Feedback Loop<br/>[feedback_loop.py]"]
  node_case_sampler["Case Sampling<br/>[case_sampler.py]"]
  node_momentum["Optimization Memory<br/>[momentum.py]"]
  node_acceptance["Acceptance Gate<br/>[acceptance_gate.py]"]
  node_trajectory["Trajectory Condenser"]
  node_diff_apply["Diff Application<br/>[diff_apply.py]"]
  node_skillopt["SkillOpt Baseline<br/>[runner.py]"]
end

subgraph group_execution["Evaluation Runtime"]
  node_eval_runner["Evaluation Runner<br/>[evaluate.py]"]
  node_skill_resolver["Skill Resolver<br/>[skills.py]"]
  node_backend["Model Backend<br/>[backend.py]"]
  node_provider_backend["OpenAI-Compatible"]
  node_usage_ledger[("Usage Ledger<br/>[ledger.py]")]
end

subgraph group_research["Experiments"]
  node_experiment_planning["Experiment Planning<br/>[planning.py]"]
  node_preflight["API Preflight<br/>[api_preflight.py]"]
  node_main_results["Main Results<br/>[main_results.py]"]
end

node_user(("User"))
node_agent(("Agent Host"))
node_skill_file["Skill File"]
node_provider(("Model Provider"))

node_user -->|"requests optimization"| node_agent
node_agent -.->|"invokes workflow"| node_product_api
node_product_api -.->|"delegates"| node_service
node_service -->|"prepares tasks"| node_task_setup
node_service -.->|"runs workflow"| node_workflow
node_service -.->|"persists session"| node_session
node_service -->|"creates evaluator"| node_eval_runner
node_service -.->|"coordinates optimization"| node_skilladam_runner
node_service -->|"records rollouts"| node_model
node_model -.->|"uses backend"| node_backend
node_skilladam_runner -->|"runs loop"| node_feedback_loop
node_skilladam_runner -->|"samples cases"| node_case_sampler
node_skilladam_runner -->|"updates memory"| node_momentum
node_skilladam_runner -->|"condenses rollouts"| node_trajectory
node_skilladam_runner -->|"evaluates skill"| node_eval_runner
node_feedback_loop -->|"checks candidate"| node_acceptance
node_eval_runner -->|"resolves skill"| node_skill_resolver
node_eval_runner -->|"executes evaluation"| node_backend
node_backend -->|"selects implementation"| node_provider_backend
node_provider_backend -->|"requests completion"| node_provider
node_agent -->|"may review edits"| node_review_tools
node_review_tools -->|"submits selection"| node_patch_review
node_patch_review -->|"applies selected hunks"| node_diff_apply
node_service -->|"offers proposal review"| node_patch_review
node_skilladam_runner -->|"proposes skill changes"| node_skill_file
node_patch_review -->|"updates after validation"| node_skill_file
node_skillopt -->|"records usage"| node_usage_ledger
node_experiment_planning -->|"uses result config"| node_main_results
node_preflight -->|"validates matrix"| node_main_results

click node_product_api "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product_mcp.py"
click node_service "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/service.py"
click node_task_setup "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/tasking.py"
click node_workflow "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/workflow.py"
click node_session "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/session_store.py"
click node_review_tools "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product_review_mcp.py"
click node_patch_review "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/patch_review.py"
click node_skilladam_runner "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/methods/skilladam.py"
click node_feedback_loop "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/feedback_loop.py"
click node_case_sampler "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/case_sampler.py"
click node_momentum "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/momentum.py"
click node_acceptance "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/acceptance_gate.py"
click node_trajectory "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/trajectory_condenser.py"
click node_diff_apply "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/diff_apply.py"
click node_eval_runner "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/execution/evaluate.py"
click node_skill_resolver "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/execution/skills.py"
click node_backend "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/execution/backend.py"
click node_provider_backend "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/backends/openai_compatible.py"
click node_skillopt "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/baselines/skillopt/runner.py"
click node_experiment_planning "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/experiments/planning.py"
click node_preflight "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/experiments/api_preflight.py"
click node_main_results "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/experiments/main_results.py"
click node_usage_ledger "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/cost/ledger.py"
click node_model "https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/model.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_product_api,node_service,node_task_setup,node_workflow,node_session,node_review_tools,node_patch_review,node_model,node_user toneBlue
class node_skilladam_runner,node_feedback_loop,node_case_sampler,node_momentum,node_acceptance,node_trajectory,node_diff_apply,node_skillopt toneAmber
class node_eval_runner,node_skill_resolver,node_backend,node_provider_backend,node_usage_ledger toneMint
class node_experiment_planning,node_preflight,node_main_results toneRose
class node_agent,node_skill_file,node_provider toneIndigo
```

## Components

### Agent Product

- [Product Adapters](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product_mcp.py): `skilladam/product_mcp.py`
- [Run Service](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/service.py): `skilladam/product/service.py`
- [Task Setup](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/tasking.py): `skilladam/product/tasking.py`
- [Product Workflow](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/workflow.py): `skilladam/product/workflow.py`
- [Session State](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/session_store.py): `skilladam/product/session_store.py`
- [Hunk Review](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product_review_mcp.py): `skilladam/product_review_mcp.py`
- [Patch Selection](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/patch_review.py): `skilladam/product/patch_review.py`
- [Product Model](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/product/model.py): `skilladam/product/model.py`

### Optimization Core

- [SkillAdam Runner](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/methods/skilladam.py): `skilladam/methods/skilladam.py`
- [Feedback Loop](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/feedback_loop.py): `skilladam/core/feedback_loop.py`
- [Case Sampling](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/case_sampler.py): `skilladam/core/case_sampler.py`
- [Optimization Memory](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/momentum.py): `skilladam/core/momentum.py`
- [Acceptance Gate](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/acceptance_gate.py): `skilladam/core/acceptance_gate.py`
- [Trajectory Condenser](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/trajectory_condenser.py): `skilladam/core/trajectory_condenser.py`
- [Diff Application](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/core/diff_apply.py): `skilladam/core/diff_apply.py`
- [SkillOpt Baseline](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/baselines/skillopt/runner.py): `skilladam/baselines/skillopt/runner.py`

### Evaluation Runtime

- [Evaluation Runner](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/execution/evaluate.py): `skilladam/execution/evaluate.py`
- [Skill Resolver](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/execution/skills.py): `skilladam/execution/skills.py`
- [Model Backend](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/execution/backend.py): `skilladam/execution/backend.py`
- [OpenAI-Compatible](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/backends/openai_compatible.py): `skilladam/backends/openai_compatible.py`
- [Usage Ledger](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/cost/ledger.py): `skilladam/cost/ledger.py`

### Experiments

- [Experiment Planning](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/experiments/planning.py): `skilladam/experiments/planning.py`
- [API Preflight](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/experiments/api_preflight.py): `skilladam/experiments/api_preflight.py`
- [Main Results](https://github.com/ruc-datalab/skilladam/blob/main/skilladam/experiments/main_results.py): `skilladam/experiments/main_results.py`

### Other components

- **User**
- **Agent Host**
- **Skill File**
- **Model Provider**

## Connections

- User → Agent Host: requests optimization (evidence: `README.md`)
- Agent Host → Product Adapters: invokes workflow
- Product Adapters → Run Service: delegates
- Run Service → Task Setup: prepares tasks (evidence: `skilladam/product/service.py`)
- Run Service → Product Workflow: runs workflow (evidence: `skilladam/product/service.py`)
- Run Service → Session State: persists session (evidence: `skilladam/product/service.py`)
- Run Service → Evaluation Runner: creates evaluator (evidence: `skilladam/product/service.py`)
- Run Service → SkillAdam Runner: coordinates optimization
- Run Service → Product Model: records rollouts (evidence: `skilladam/product/service.py`)
- Product Model → Model Backend: uses backend
- SkillAdam Runner → Feedback Loop: runs loop (evidence: `skilladam/methods/skilladam.py`)
- SkillAdam Runner → Case Sampling: samples cases (evidence: `skilladam/methods/skilladam.py`)
- SkillAdam Runner → Optimization Memory: updates memory (evidence: `skilladam/methods/skilladam.py`)
- SkillAdam Runner → Trajectory Condenser: condenses rollouts (evidence: `skilladam/methods/skilladam.py`)
- SkillAdam Runner → Evaluation Runner: evaluates skill (evidence: `skilladam/methods/skilladam.py`)
- Feedback Loop → Acceptance Gate: checks candidate (evidence: `skilladam/core/feedback_loop.py`)
- Evaluation Runner → Skill Resolver: resolves skill (evidence: `skilladam/execution/evaluate.py`)
- Evaluation Runner → Model Backend: executes evaluation (evidence: `skilladam/execution/evaluate.py`)
- Model Backend → OpenAI-Compatible: selects implementation (evidence: `skilladam/execution/backend.py`)
- OpenAI-Compatible → Model Provider: requests completion (evidence: `skilladam/backends/openai_compatible.py`)
- Agent Host → Hunk Review: may review edits (evidence: `README.md`)
- Hunk Review → Patch Selection: submits selection (evidence: `skilladam/product_review_mcp.py`)
- Patch Selection → Diff Application: applies selected hunks (evidence: `skilladam/product/patch_review.py`)
- Run Service → Patch Selection: offers proposal review (evidence: `skilladam/product/service.py`)
- SkillAdam Runner → Skill File: proposes skill changes (evidence: `README.md`)
- Patch Selection → Skill File: updates after validation (evidence: `README.md`)
- SkillOpt Baseline → Usage Ledger: records usage (evidence: `skilladam/baselines/skillopt/runner.py`)
- Experiment Planning → Main Results: uses result config (evidence: `skilladam/experiments/planning.py`)
- API Preflight → Main Results: validates matrix (evidence: `skilladam/experiments/api_preflight.py`)
