Skills-Graph

A canonical graph of skills, capabilities, and workflows -- assembled from external evidence under explicit authority, then projected to an Obsidian vault for human review.

Skills-Graph is the substrate underneath an autonomous skill-building loop: it ingests research, decomposes scopes into atomic units, builds skills in isolation, validates them, and emits a versioned, auditable graph you can read, edit, or hand off to another system.

Why this exists

The premise: build a persistent skill graph by recursively decomposing scope specifications through deep research.

Most "agent skill" libraries treat skills as flat prompt files written by hand. They fail at scale: capabilities duplicate, provenance vanishes, you can't tell an LLM hypothesis from a real source, and you can't validate one skill independently of another.

Skills-Graph takes a different approach. A scope spec ("comprehensive coverage of X domain") is recursively decomposed via deep research — at each node, the system gathers evidence and decides: is this atomic (build a skill), compound (decompose further), or under-evidenced (re-query)? The output is a typed, persistent skill graph with provenance on every node, mutations gated by an authority service, and a deterministic projection to Obsidian for human review.

What's novel about the combination: ROMA-style recursive decomposition (arXiv:2602.01848, Feb 2026) was designed for ephemeral task execution. Recent skill-graph research (Graph-of-Skills, GraSP, SkillDAG) takes pre-existing skills and organises them. Skills-Graph sits at the intersection — building a skill graph from the decomposition output, with explicit authority and validation gates governing what enters canonical state. We are not aware of another open-source project that combines deep-research decomposition with a typed, governed skill graph.

The architecture is pinned by ten ADRs you can read, disagree with, and challenge.

Why now?

The project sits at the intersection of seven maturing threads:

• The Agent Skills open standard (SKILL.md, adopted by Anthropic, OpenAI Codex, Microsoft, LangChain, OpenHands)
• Recursive decomposition for agents (ROMA, Feb 2026)
• Persistent knowledge graphs for AI (Neo4j Agent Memory, Cognee, Mem0)
• Deep research as a first-class agent primitive (Onyx, DeerFlow, DeepVerifier)
• Provenance and authority for agent systems (PROV-AGENT, ACP, ActiveGraph)
• Two-stage validation and async quality gates for AI output
• Codex and the broader agentic-coding direction

Each thread has real momentum. None of them combine to address the lifecycle of agent skills as versioned, validated, and auditable graph state. That is the gap Skills-Graph fills. Citations and adjacent work in RELATED-WORK.md.

Pipeline at a glance

Scope spec
   │
   ▼
[ingestion]  ─►  ResearchBundle + EvidenceFinding
   │
   ▼
[retrieval]  ─►  NormalizedCandidate (rank-fused, deduped)
   │
   ▼
[decomposition]  ─►  ROMA: atom | decompose | re-query
   │
   ▼
[arbitration]  ─►  ReconciliationDecision
   │
   ▼
[builder]      ─►  BuildJob + BuildReport (isolated)
   │
   ▼
[validation]   ─►  AdmissionGate ─► EventualValidation
   │
   ├──►  [optimization]  (variants + rubric + promotion)
   │
   └──►  [projection]    (Obsidian vault)

Plus a non-destructive import flow for absorbing existing graphs under three lifecycle modes (pristine | adopted | fork).

60-second quickstart

git clone https://github.com/SynapticSolutionsAI/Skills-Graph.git
cd Skills-Graph
npm ci
npm test                  # full test suite, in-memory backend
npm start -- --help       # see CLI subcommands

To drive a real research run end-to-end:

cp .env.example .env      # add your provider keys
npm run research -- "modern TypeScript async patterns" \
  --provider llm \
  --output ./skills-vault \
  --max-depth 4

The CLI walks the full pipeline (research → decomposition → projection) and writes the resulting Obsidian vault to ./skills-vault/ (gitignored). Open it in Obsidian and follow the graph view.

Other subcommands: import, ingest, retrieve, optimize, validate, reconcile, migrate, project, status. Run npm start -- help for the full list and per-command flags.

For Postgres-backed contract tests:

docker --version          # required
npm run test:postgres

See USER-GUIDE.md for the full operating manual.

A note on running costs

The pipeline is built around recursive deep research, so a real run issues many LLM calls. A modest research run at depth 4 with all stages enabled can plausibly issue several hundred calls. This is the central constraint the project is engineered around — see COST-MODEL.md and ADR-010.

The defaults are picked accordingly:

• The default model tier is gpt-5-nano or equivalent. Production-grade Gemini / Claude / DeerFlow / Onyx are explicit opt-ins.
• The default builder is a deterministic stub. Pass --adk --real-build to switch in the real ADK-backed builder.
• An LLM-call budget cap (planned for v0.2.0; tracked in ADR-010) will stop a run cleanly at a configurable ceiling.
• A record/replay cassette layer (planned for v0.1.1; tracked in ADR-010) will let you record one real run and replay it deterministically forever, free.

We've shipped the orchestration shape with strong test coverage on the control flow. Calibrating it on real research output at depth is the first thing the next slice tackles.

Architecture, in three layers

Layer	What lives there	Path
Domain	Canonical entities, identity rules, invariants, authority commands. The contracts every other layer depends on.	src/domain/
Application	Pipeline orchestrators, one per stage. Pure logic; no I/O, no graph mutation outside the authority service.	src/application/
Adapters	Backend implementations of ports. Postgres, in-memory, OpenAI, DeerFlow, Onyx, Google ADK, Obsidian. Swap freely.	src/adapters/

Tests mirror the same shape under test/contracts/, test/application/, test/adapters/, and test/integration/.

Why the architecture matters

• Authority is centralised. Only the Graph Authority Service mutates canonical entities. Adapters and orchestrators emit commands; they never write directly. ADR-001.
• Decomposition, evidence, and authority are separated. Each lives in its own layer, with explicit handoffs. ADR-002.
• Retrieval comes before arbitration. No skill is promoted on a single-source claim. ADR-003.
• The builder is isolated. A skill is built from one AtomicNodeHandoff and the rubric -- nothing else. ADR-004.
• Existing graphs are imported non-destructively. Pristine, adopted, or fork -- the lifecycle mode is explicit. ADR-005.
• Authority records and the review queue are first-class. Promotion is auditable end-to-end. ADR-006.
• Validation is eventual, not synchronous. Admission gates are cheap; deep validation accumulates evidence. ADR-007.
• Workflows are first-class canonical entities. ADR-008.
• ADK adapters never bypass the application orchestrators. The agent layer is a backend, not a controller. ADR-009.
• Cost-conscious development is a first-class commitment. Every paid-endpoint adapter wraps in a record/replay cassette; the cheap dev tier is the default; LLM-call budgets are enforced. ADR-010.

Read the ADRs in adrs/. Disagreement is welcome and is the basis of every roadmap PR.

Documentation map

Document	Purpose
USER-GUIDE.md	How to drive the CLI.
ARCHITECTURE-PROPOSAL.md	High-level architecture.
COMPREHENSIVE-PLAN.md	Stage-by-stage system map.
ROADMAP.md	What's next.
CHANGELOG.md	Versioned change log.
CONTRIBUTING.md	How to contribute.
SECURITY.md	Vulnerability disclosure.
adrs/	Architectural Decision Records.
canonical-data-model.md	Entity model in full.
COST-MODEL.md	Why a real run is expensive and how the project is engineered around that.
RESEARCH-REPORT.md	Landscape research that informed the design.
RELATED-WORK.md	How we relate to ROMA, Agent Skills, GoS, LangGraph, etc.

Status

v0.1.0 -- first public release.

What this release actually contains, in plain terms:

• The contracts (entities, identity rules, invariants, authority commands) are stable and the contract test suite pins them.
• The in-memory pipeline runs end-to-end and is exercised by an integration test that walks all stages.
• The Postgres backend is fully implemented and contract-tested; the contract suite runs against it under npm run test:postgres (requires Docker).
• The ADK adapter family is fully implemented and runs against a real @google/adk LlmAgent when GOOGLE_API_KEY is set. The default CLI build path uses a deterministic stub; pass --adk --real-build to switch to the real backend.
• The CLI is the supported entry point and exposes the full pipeline through the research, import, ingest, retrieve, optimize, validate, reconcile, migrate, project, and status subcommands.

What this release does not claim:

• Production-scale throughput. We have not yet run the system at production traffic.
• Calibrated retrieval weights. The rank-fusion weights in ranking-formula.md are sensible defaults awaiting empirical tuning.
• A "build skill from any input" capability. Real skill generation requires --adk --real-build AND a working GOOGLE_API_KEY (or an OpenAI-compatible endpoint); the default path uses a stub.

What is next: see ROADMAP.md and the filed issues.

License

Apache License 2.0 © 2026 Synaptic Solutions AI.

Acknowledgements

Built on top of the work behind ROMA-style recursive decomposition, and on the LLM platforms that make this kind of system possible:

• OpenAI — Chat Completions API as the default LLM transport. Points at OpenAI directly, or at any OpenAI-compatible endpoint (local Ollama, LM Studio, hosted alternatives). gpt-5-nano is the default cheap-tier model.
• Google Gemini via the Agent Development Kit — backs the agent-mediated arbitration, build, and optimization paths. gemini-2.5-flash and gemini-2.5-pro are the default ADK models.
• Anthropic Claude — first-class through ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL in the env. The OpenAI-compatible pathway also routes Claude via OpenRouter or LiteLLM proxies.
• DeerFlow and Onyx — deep-research providers for the ingestion stage.
• Obsidian — the projection target for the canonical graph.

Plus the broader open-source agent tooling community. Citations live in RELATED-WORK.md.

The roadmap explicitly includes a Codex research provider (#1), a Codex builder backend (#2), and a Codex-driven PR-review GitHub Action (#3) as the v0.2.0 slice — see ROADMAP.md.