Contract-checked orchestration for agent skills, scientific workflows, and reproducible outputs.
Quick start · Workflow guide · Skill library · MCP integration · Report an issue
Languages: English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Español
Turn a long agent conversation into an inspectable workflow — with explicit inputs, real files, and bounded feedback.
| 🧩 Compose | 🔒 Validate | 🔄 Recover |
|---|---|---|
Combine one or more SKILL.md packages in each YAML stage. |
Check declared artifacts, path boundaries, hashes, and optional JSON Schemas. | Persist visits and checkpoints; pause, resume, retry, and loop within budgets. |
| 🔬 Research workflows | 🔌 Agent integration | 📦 Clone and build |
| Five paper workflow families covering empirical research, ML, medicine, bioinformatics, and surveys. | Use the CLI, MCP stdio server, or a custom host agent. | All 31 registered skills are bundled in skills/; no separate .vendor checkout needed. |
Important
SkillGraph is an orchestration engine, not a scientific certification service or an OS sandbox. Artifact checks, passing tests, and a compiled PDF do not establish scientific validity, ethics approval, or publication readiness. Host tools retain their own permissions; external models, data, Python packages, and TeX tooling must be configured separately.
📚 Explore the documentation
SkillGraph is an orchestration layer between an AI agent and the skills that the agent uses.
An agent is good at reasoning and making decisions, but a long task becomes fragile when every step is only an informal prompt. SkillGraph turns those steps into a typed, bounded, resumable graph:
User prompt
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Agent stage │ ───▶ │ Skill stage │ ───▶ │ Artifact │
│ task + input │ │ SKILL.md │ │ contract │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
Next stage / loop
The graph is the source of truth for what happens next, while the host agent remains responsible for the actual scientific or engineering work. This makes a workflow portable across Pi, an MCP client, a CLI agent, or a custom runtime.
flowchart LR
A["YAML workflow"] --> B["Resolve inputs + skills"]
B --> C["Host agent + tools"]
C --> D["Files + node_result.json"]
D --> E{"Contract checks"}
E -->|accepted| F["Persist state + route"]
E -->|invalid| G["Reject submission"]
F --> H["Next stage / bounded repair"]
H --> B
The host agent executes tools; the engine validates submissions and routes the graph.
SkillGraph does not ask an agent to complete a long task in one unstructured conversation. It turns the task into a sequence of explicit state transitions. Each transition has four parts:
- Stage definition — a YAML node declares the task, active skill bundle, inputs, required outputs, visit limit and optional decision fields.
- Context resolution — before activation, the engine resolves input and artifact references to the exact files produced by earlier visits. Missing required inputs stop the run; branch-specific inputs can be marked optional.
- Agent execution — the host agent loads the active
SKILL.mdfiles, performs the stage using its tools, and writes files into the stage output directory. - Contracted commit — the agent submits
node_result.json; the engine verifies the declared files, hashes them, records them in run state, evaluates the next edge, and only then activates the next stage.
YAML node
→ resolve inputs and skill pins
→ load one or more SKILL.md contracts
→ agent writes declared files
→ node_result.json
→ artifact/path/schema/hash validation
→ deterministic edge selection
→ next node or bounded loop
This separation is the central design principle: the agent produces content; the graph decides whether that content is admissible and what happens next.
Every run records a manifest containing the workflow version, graph hash, active
skill hashes, session, inputs and timestamps. Every stage receives a unique
visit_id. Every accepted artifact records its producing node, visit, relative
path, byte size, SHA-256 hash and validation time.
As a result, a downstream stage does not receive an ambiguous label such as "the latest manuscript". It receives a concrete path such as:
runs/<run>/stages/review/visits/<visit>/outputs/manuscript_under_review.md
A graph or skill change invalidates the corresponding run instead of silently mixing old and new instructions.
A prompt can ask for a paper, but it cannot reliably prove that the paper contains a methods section, that a figure exists, or that a number came from an experiment. SkillGraph makes those expectations explicit:
inputsdefine what a stage is allowed to consume;outputsdefine which files it must produce;- artifact validation checks path boundaries, file existence, size and schemas;
decisionfields drive declared branches;priorityresolves competing edges deterministically;- loop edges impose iteration limits and require changing inputs;
- terminal release gates can validate PDF pages, figures, references and reproducibility before completion.
Some tasks need a coordinated set of methods. A node can expose a primary skill and additional complementary skills:
- id: methods
type: agent
skill: experimental-design
skills:
- experimental-design
- statistical-powerThe runner loads every listed SKILL.md into the stage context. This allows a
single stage to combine, for example, experimental design with power analysis,
or scientific writing with diagram construction, without merging unrelated
instructions into one oversized skill.
Branches represent real alternatives, not prose instructions. A medical workflow can select clinical-cohort analysis or meta-analysis; a bioinformatics workflow can select bulk RNA-seq, single-cell, or microbiome analysis. Each branch produces its own artifacts and converges through explicitly bound inputs.
Loops declare feedback paths with provenance. Paper release workflows distinguish figure, citation, formatting, and substantive manuscript repairs, rather than sending every failure back to drafting. Revision bindings and downstream content inheritance still require end-to-end validation; a completed stage alone does not prove that every later consumer used the revised manuscript.
A skill is a bounded instruction package whose entry point is SKILL.md.
SkillGraph pins the skill file with SHA-256 at run start. If the skill changes
while a run is paused, the run refuses to continue silently.
skills:
- id: literature-review
version: 1
path: skills/literature-review
produces: [literature-review]A stage can use one skill or a coordinated skill bundle:
- id: methods
type: agent
skill: experimental-design
skills:
- experimental-design
- statistical-powerThe primary skill field remains backward-compatible; skills declares all
active skill contracts for the stage.
Stages do not merely return text. They declare files that must exist in the stage output directory:
outputs:
- name: methods
required: true
- name: figures
required: falseThe engine checks file boundaries, relative paths, size limits, SHA-256 hashes, and optional JSON Schemas before accepting the stage.
A downstream stage receives a path to a validated upstream artifact:
inputs:
research_plan: "{{artifact:scope:research_plan}}"
dataset:
value: "{{artifact:eda:dataset.csv}}"
required: falserequired: false is important for branch-specific artifacts. For example, a
bioinformatics draft can receive differential-expression results on a bulk
RNA-seq path and cell-marker results on a single-cell path without making either
branch pretend the other artifact exists.
Edges use explicit conditions and priorities:
- from: methods
to: eda
when: 'result.decision == "quantitative"'
priority: 20
- from: methods
to: draft
when: 'result.decision != "quantitative"'
priority: 10Ambiguous routes, missing routes, invalid references, and implicit cycles are rejected before or during execution.
A review loop is a real graph loop, not a vague instruction:
- from: revise
to: review
bind:
manuscript: "{{artifact:revise:revised_manuscript}}"
loop:
id: revision-cycle
max_iterations: 3This declares that the revised manuscript should be used by the next review; it is not proof of end-to-end manuscript inheritance. Scientific workflows also declare release checks for native LaTeX/PDF compilation, venue-specific formatting, figures, references, and reproducibility. Missing scientific evidence or human approval must remain unresolved, not be closed by repeated rewriting.
- YAML workflow graphs with deterministic routing and bounded execution.
- One or multiple active
SKILL.mdcontracts per stage. - SHA-256 skill pinning so a run cannot silently continue after a skill changes.
- Required and optional artifact contracts with path and size validation.
- JSON Schema checks for machine-readable artifacts.
- Atomic state writes, per-run file locks, manifests, and event logs.
- Checkpoint, pause, resume, retry, and bounded loop execution.
- CLI and MCP stdio adapters.
- A structured question protocol for missing or ambiguous user input.
- Scientific workflow bundles for algorithms, medical research, bioinformatics, surveys, experiments, LaTeX papers, figures, and PDF release gates.
The repository includes five workflow families under
.skill-workflows/workflows/:
| Workflow | Purpose | Main stages |
|---|---|---|
paper |
General empirical research | question → literature → methods → data → statistics → figures → paper → review → LaTeX/PDF gate |
paper-algo |
Algorithm and ML innovation | problem → related work → method → protocol → implementation → ablation → statistics → paper |
paper-medical |
Clinical and evidence-synthesis studies | PICO → literature → clinical/meta branch → cohort/statistics/survival → paper |
paper-bioinfo |
Omics and computational biology | assay design → bulk/single-cell/microbiome branch → enrichment → figures → paper |
paper-survey |
Literature surveys | scope → corpus → evidence → taxonomy → synthesis → paper |
Each family is assembled from specialized skills such as:
hypothesis-generationliterature-reviewexperimental-designstatistical-powerexploratory-data-analysisstatistical-analysisscientific-visualizationscientific-writingpeer-reviewcitation-managementvenue-templatesscanpy,scvi-tools,pydeseq2,bulk-rnaseqclinical-decision-support,pyhealth,scikit-survival
The paper release path is designed to produce:
real data / code
→ measured analysis
→ scientific figures and captions
→ long-form manuscript
→ peer review and revision loop
→ bibliography audit
→ final_paper.tex
→ Tectonic-compiled final_paper.pdf
→ release manifest
Requires Node.js 22+ and npm. Clone the repository to include both workflows and their bundled skills:
git clone https://github.com/Akun-python/Skigraph.git
cd Skigraph
npm install
npm run buildList available workflows:
node dist/cli.js list --cwd /path/to/projectStart a workflow and pass the returned stage context to an agent:
node dist/cli.js run research '{"topic":"agent reliability"}' --cwd /path/to/projectFor the included scientific workflows:
node dist/cli.js run paper-algo \
'{"prompt":"A reproducible algorithmic study of streaming heavy hitters"}'The agent then:
- loads the active skill bundle from the returned
StageContext; - reads upstream artifact paths from
inputs; - performs the stage work and writes declared files;
- writes
node_result.json; - submits the stage without guessing or fabricating missing outputs.
Submit a completed stage:
node dist/cli.js submit <run-id> <node-id> <visit-id>Do not pass a result path from another visit. The current visit's
node_result.json is the canonical submission.
For the included scientific workflows, scripts/agent-run.mjs connects the
stage graph to an OpenAI-compatible model configured in
~/.pi/agent/models.json:
node scripts/agent-run.mjs \
--plan paper \
--model glm-5.3 \
--prompt "Does temperature scaling reduce overconfidence in small neural networks?"The driver loads every active SKILL.md, exposes bounded file and shell tools,
requires real artifacts, and routes the graph stage by stage. It never accepts
undeclared artifacts.
Tectonic is the lightweight LaTeX engine used by the paper release path:
export PATH="$HOME/.local/bin:$PATH"
npm run compile-paper -- path/to/final_paper.texThe compiler:
- downloads only the TeX resources required by the document;
- compiles the
.texsource; - emits a PDF and compilation log;
- reads the page count with
pdfinfo; - fails if the long-form paper is below the configured page threshold.
The final release gate also checks word count, scientific figure count, verified references, methods/results/limitations sections, data/code availability, and whether the page count was padded with duplicated text.
.skill-workflows/
graph/skills.yaml # skill contracts, versions, and paths
workflows/*.yaml # graph definitions
README.md # scientific workflow documentation
runs/ # generated state and artifacts, ignored by git
scripts/
agent-run.mjs # real model-driven stage runner
audit-workflows.mjs # static contract audit
compile-paper.mjs # Tectonic + PDF page gate
smoke-paper.mjs # content-aware graph smoke test
validate-workflows.cjs # routing/branch/loop validation
src/
core/ # graph engine, loader, state, artifacts, expressions
adapters/ # MCP and host-agent adapters
tests/ # regression and workflow-contract tests
skills/
<id>/SKILL.md # bundled workflow skill contracts
.vendor/
scientific-agent-skills/ # optional upstream checkout, git-ignored
The loader also accepts .skill-graph as a project root. Configure roots with:
SKILL_GRAPH_PROJECT_ROOTS=path1:path2
SKILL_GRAPH_USER_ROOTS=path1:path2
SKILL_GRAPH_HOME=path
SKILL_GRAPH_SKILL_PATHS=path1:path2
On Windows, use ; instead of : in multi-path variables.
schema_version: 1
id: research
version: 1
mode: agent
required_inputs: [topic]
entry: topic_selection
nodes:
- id: topic_selection
type: agent
skill: topic-selection
task: Create a focused research topic plan.
inputs:
topic: "{{input:topic}}"
outputs:
- name: topic_plan
required: true
terminal: trueA stage result follows one stable shape:
{
"schema_version": 1,
"node_id": "topic_selection",
"visit_id": "v-123",
"status": "success",
"summary": "Created the research plan",
"artifacts": [{ "name": "topic_plan", "path": "topic-plan.md" }],
"issues": []
}skill-graph list
skill-graph run <workflow-id> <json-input>
skill-graph context <run-id>
skill-graph submit <run-id> <node-id> <visit-id> [result-path]
skill-graph resume <run-id>
Build the package and configure an MCP client to run the stdio server:
{
"mcpServers": {
"skill-graph": {
"command": "node",
"args": ["/path/to/skill-graph/dist/adapters/mcp/server.js"],
"env": {
"SKILL_GRAPH_CWD": "/path/to/your-project",
"SKILL_GRAPH_PROJECT_ROOTS": "/path/to/your-project/.skill-workflows",
"SKILL_GRAPH_USER_ROOTS": "/home/you/.skill-graph"
}
}
}
}The MCP server exposes:
workflow_listworkflow_executeworkflow_submit_stageworkflow_resumequestion
The host agent remains responsible for reading the active skill bundle, doing the work, writing artifacts, and submitting the result. The graph engine never pretends to execute an LLM stage itself.
Build first, then run the static and graph checks (tests execute built files):
npm run build
npm run qaThis performs:
TypeScript check
→ unit tests
→ skill/workflow contract audit
→ branch and loop validation
Additional commands:
npm run audit
npm run smoke
npm testThe smoke harness validates routing and artifact data flow. It is not a substitute for a real scientific run. A real paper must pass the release gate with real data, real figures, real references, a complete LaTeX source, and a compiled PDF.
- Workflow and skill paths are bounded to configured roots.
- A run records the graph hash and every active skill hash.
- Changed graphs or skills refuse to resume an existing run.
- Run state updates use atomic files and per-run locks.
- Budgets cap visits, agent turns, loops, stage time, and model/tool activity.
- The expression language is deliberately small and does not execute code.
- Artifact paths cannot escape the run output directory.
- API keys are read from the host environment/configuration and are never stored in workflow files or committed to the repository.
Bug reports, workflow examples, documentation improvements, and focused pull requests are welcome.
- Open an issue describing the problem or proposed change. Include a minimal reproduction for bugs.
- Keep changes scoped; add regression tests when engine or routing behavior changes.
- Run
npm run build && npm run qabefore submitting a pull request. - Never include credentials, private datasets, or unpublished manuscripts without authorization. Preserve third-party license notices.
Useful starting points: engine, tests, workflow definitions, skill library.
This is an evolving project (0.1.0 in package.json). Static audits and routing
tests cover engineering contracts, not the scientific correctness of generated
research. Content-level convergence, revision inheritance, and real model-driven
end-to-end workflows need further validation. Reports of reproducible failures
are especially valuable.
The bundled scientific skill library derives from K-Dense scientific-agent-skills. See skill provenance and the retained upstream license. Additional notices embedded in third-party assets remain applicable.
Copyright 2026 Akun-python. Licensed under the Apache License, Version 2.0. Third-party skills and dependencies retain their respective licenses.
