Skip to content
Akun-pythonPublic

About

Skigraph 是基于 DAG 的通用可控 Agent Skill 编排框架。它解耦原子 Skill 逻辑与流程协调,负责调度顺序、依赖解析、跨 Skill 产物传递、全局状态与断点续跑,不侵入 Skill 内部实现。异构 Skill 输出统一格式化并支持状态观测,领域无关,可搭建稳定可恢复的多阶段 Agent 流水线。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SkillGraph logo

SkillGraph

Contract-checked orchestration for agent skills, scientific workflows, and reproducible outputs.

License: Apache 2.0 Requires Node.js 22 or newer Built with TypeScript CLI and MCP interfaces

31 bundled workflow skills 5 scientific paper workflow families GitHub stars GitHub issues

Quick start · Workflow guide · Skill library · MCP integration · Report an issue

Languages: English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Español


✨ Why SkillGraph?

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

What SkillGraph Means

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.

How the Mechanism Works

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
Loading

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:

  1. Stage definition — a YAML node declares the task, active skill bundle, inputs, required outputs, visit limit and optional decision fields.
  2. 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.
  3. Agent execution — the host agent loads the active SKILL.md files, performs the stage using its tools, and writes files into the stage output directory.
  4. 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.

State, provenance, and reproducibility

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.

Contracts instead of prompt conventions

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:

  • inputs define what a stage is allowed to consume;
  • outputs define which files it must produce;
  • artifact validation checks path boundaries, file existence, size and schemas;
  • decision fields drive declared branches;
  • priority resolves 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.

Multiple skills in one stage

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-power

The 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, loops, and quality feedback

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.

Core Concepts

1. Skill contracts

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-power

The primary skill field remains backward-compatible; skills declares all active skill contracts for the stage.

2. Artifact contracts

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: false

The engine checks file boundaries, relative paths, size limits, SHA-256 hashes, and optional JSON Schemas before accepting the stage.

3. Explicit data flow

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: false

required: 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.

4. Deterministic routing

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: 10

Ambiguous routes, missing routes, invalid references, and implicit cycles are rejected before or during execution.

5. Loops and quality gates

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: 3

This 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.

What This Provides

  • YAML workflow graphs with deterministic routing and bounded execution.
  • One or multiple active SKILL.md contracts 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.

🔬 Scientific Paper Workflows

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-generation
  • literature-review
  • experimental-design
  • statistical-power
  • exploratory-data-analysis
  • statistical-analysis
  • scientific-visualization
  • scientific-writing
  • peer-review
  • citation-management
  • venue-templates
  • scanpy, scvi-tools, pydeseq2, bulk-rnaseq
  • clinical-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

🚀 Quick Start

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 build

List available workflows:

node dist/cli.js list --cwd /path/to/project

Start a workflow and pass the returned stage context to an agent:

node dist/cli.js run research '{"topic":"agent reliability"}' --cwd /path/to/project

For the included scientific workflows:

node dist/cli.js run paper-algo \
  '{"prompt":"A reproducible algorithmic study of streaming heavy hitters"}'

The agent then:

  1. loads the active skill bundle from the returned StageContext;
  2. reads upstream artifact paths from inputs;
  3. performs the stage work and writes declared files;
  4. writes node_result.json;
  5. 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.

🤖 Real Agent Driver

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.

LaTeX and PDF Compilation

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.tex

The compiler:

  • downloads only the TeX resources required by the document;
  • compiles the .tex source;
  • 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.

Project Layout

.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.

Workflow Contract

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: true

A 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": []
}

CLI Commands

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>

🔌 MCP Adapter

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_list
  • workflow_execute
  • workflow_submit_stage
  • workflow_resume
  • question

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.

✅ Validation and Quality Gates

Build first, then run the static and graph checks (tests execute built files):

npm run build
npm run qa

This performs:

TypeScript check
→ unit tests
→ skill/workflow contract audit
→ branch and loop validation

Additional commands:

npm run audit
npm run smoke
npm test

The 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.

Security and Stability

  • 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.

🤝 Contributing

Bug reports, workflow examples, documentation improvements, and focused pull requests are welcome.

  1. Open an issue describing the problem or proposed change. Include a minimal reproduction for bugs.
  2. Keep changes scoped; add regression tests when engine or routing behavior changes.
  3. Run npm run build && npm run qa before submitting a pull request.
  4. Never include credentials, private datasets, or unpublished manuscripts without authorization. Preserve third-party license notices.

Useful starting points: engine, tests, workflow definitions, skill library.

🧭 Project Status & Scope

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.

🙏 Acknowledgments

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.

📄 License

Copyright 2026 Akun-python. Licensed under the Apache License, Version 2.0. Third-party skills and dependencies retain their respective licenses.

About

Skigraph 是基于 DAG 的通用可控 Agent Skill 编排框架。它解耦原子 Skill 逻辑与流程协调,负责调度顺序、依赖解析、跨 Skill 产物传递、全局状态与断点续跑,不侵入 Skill 内部实现。异构 Skill 输出统一格式化并支持状态观测,领域无关,可搭建稳定可恢复的多阶段 Agent 流水线。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages