Configuration

1. substrate — which SkillStore, DataStore, LocalModel, and AgentConnector the runtime hosts (MCP server + web dashboard) use.
2. Named MCP connector instances — youtrack, github, etc. — invoked via $ <name> in skill source.

​

SKILLSCRIPT_HOME — the root override

# Adopter instance with fully isolated state
export SKILLSCRIPT_HOME=~/.skillscript-adopter
skillfile dashboard --host 127.0.0.1 --port 7879

Why this matters for adopter setups. Without SKILLSCRIPT_HOME isolation, two daemons running side-by-side would share triggers.json, skillsDir (filesystem default), and any other $HOME/<thing> default — even if their sqlite dbPaths were explicitly distinct. SKILLSCRIPT_HOME is the architectural primitive; everything else derives from it.

​

Environment variables + .env file

​

Direct env-var reads — the runtime checks process.env for these

​

Indirect via ${VAR} substitution in config files

• skillscript.config.json — any string field. Examples: dashboard.host: "${BIND_HOST}", triggersFilePath: "${TRIGGERS_PATH}".
• connectors.json — the big one for adopter wiring. Endpoints, auth tokens, child-process env blocks. Example:
  {
    "memory": {
      "class": "HttpMcpConnector",
      "config": {
        "endpoint": "${MEMORY_ENDPOINT}",
        "headers": { "Authorization": "Bearer ${MEMORY_TOKEN}" },
        "identityHeader": "X-Agent-Id"
      }
    }
  }
  
  MEMORY_ENDPOINT and MEMORY_TOKEN in .env; declarative shape committed to connectors.json.

​

.env file format

# comment lines start with #
KEY=value
KEY_WITH_SPACES="value with spaces"
URL=https://example.com/path?key=value

​

Precedence summary (most-specific wins)

1. CLI flag (e.g., --port 8080)
2. Shell-set env var (export SKILLSCRIPT_PORT=8080)
3. .env file in $SKILLSCRIPT_HOME
4. skillscript.config.json field
5. Built-in default

​

skillfile init seeds .env.example

​

Adopter credential discipline

• Commit connectors.json with ${VAR} references; never literal secrets.
• .gitignore .env (the file with real values); commit .env.example (the template).
• See Credential discipline below for the broader pattern.

​

Quick start

{
  "substrate": {
    "skill_store": "filesystem",
    "data_store": "sqlite",
    "local_model": null,
    "agent_connector": null
  }
}

{
  "substrate": {
    "skill_store": "sqlite"
  }
}

Heads up on startup logs. Sqlite-backed substrates use the built-in node:sqlite module, which is still flagged experimental in Node 22. Expect this line on every launch until Node de-experimentalizes it: ExperimentalWarning: SQLite is an experimental feature and might change at any time. Harmless; can be silenced per-process with NODE_OPTIONS="--disable-warning=ExperimentalWarning" if it clutters your logs.

​

The substrate section

​

Short form — bare string

"skill_store": "sqlite"

​

Null — explicit “no substrate”

"local_model": null,
"agent_connector": null

​

Object form — override defaults

"skill_store": {
  "type": "sqlite",
  "config": {
    "dbPath": "/var/skillscript/skills.db"
  }
}

SqliteDataStore feature surface. The bundled sqlite data_store is a deliberately minimal reference implementation: supports_writes + supports_tag_filter are true; supports_semantic, supports_pinning, supports_decay_model, supports_thread_status_filter are all false. Rich features (semantic retrieval, pinning, decay scoring, thread-status workflow) come from substrate impls — adopters fork examples/connectors/DataStoreTemplate/ and wire their backing system (memory broker, vector DB, AMP, etc.). The bundled impl exists so the runtime works out-of-box; adopters with richer query semantics write their own.

{
  "substrate": {
    "local_model": {
      "type": "ollama",
      "config": {
        "defaultModelTag": "gemma2:9b"
      }
    }
  }
}

​

Custom form — adopter-written impl

"skill_store": {
  "type": "custom",
  "module": "./my-skill-store.js",
  "export": "MySkillStore",
  "config": {
    "vault": "team"
  }
}

"agent_connector": {
  "type": "custom",
  "module": "./my-agent-connector.js",
  "export": "MyHttpWebhookAgentConnector",
  "config": {
    "endpoint": "${AGENT_ENDPOINT}"
  }
}

Limitation: sync bootstrap() can’t dynamic-import. Custom-via-connectors.json surfaces a clear error and falls back to the default. Adopters wanting custom impls today write a programmatic bootstrap that calls registry.registerSkillStore("primary", new MySkillStore(...)) (or registry.registerAgentConnector(...)) directly — same pattern as the runtime’s reference bootstrap(). Async-bootstrap with dynamic-import support is planned.

​

Precedence

1. Programmatic opts (opts.skillStore / opts.dataStore / opts.localModel / opts.agentConnector passed to bootstrap()) — explicit, highest priority
2. connectors.json substrate section — declarative, deployment-durable
3. Built-in default — fallback (filesystem skill_store; conditional sqlite data_store; no local_model; NoOpAgentConnector)

​

Which surfaces honor substrate config?

​

Named MCP connector instances

{
  "substrate": { "skill_store": "sqlite" },

  "youtrack": {
    "class": "RemoteMcpConnector",
    "config": {
      "command": "npx",
      "args": ["mcp-remote", "https://example.youtrack.cloud/mcp"],
      "framing": "newline",
      "env": { "AUTH_HEADER": "Bearer ${YOUTRACK_TOKEN}" }
    },
    "allowed_tools": ["list_issues", "get_issue", "create_comment"]
  },

  "github": {
    "class": "RemoteMcpConnector",
    "config": { /* ... */ },
    "allowed_tools": ["search_repos", "get_issue"]
  }
}

• class — a class from the closed-set registry. Today: RemoteMcpConnector (stdio-bridged remote MCP). Adopters can register custom classes via registerConnectorClass() from their bootstrap.
• config — passed to the class’s fromConfig() factory. Schema is class-specific.
• allowed_tools (optional) — per-connector tool allowlist at the entry top-level (sibling to class / config, NOT inside config). undefined = allow all; [] = allow none; listed array = exactly those. Placing allowed_tools inside the config: block is a hard parse error — the loader refuses to load to prevent a silent allow-all bypass (a security control quietly doing nothing on misplacement is the worst-case failure mode).

​

RemoteMcpConnector config — stdio framing

• "newline" — one JSON-RPC message per line, newline-delimited. This is what mcp-remote (the npm package) and most spec-compliant MCP stdio servers use. Recommended for almost all adopters.
• "lsp" (legacy default) — Content-Length: N\r\n\r\n<body> per the LSP convention. Only set this if your specific MCP server explicitly uses LSP-style framing.

​

Credential discipline

​

${VAR} substitution

"env": { "AUTH_HEADER": "Bearer ${YOUTRACK_TOKEN}" }

"config": {
  "env": { "AUTH_HEADER": "Bearer ${YOUTRACK_TOKEN}" },
  "args": ["--header", "Authorization:${AUTH_HEADER}"]
}

​

Inline comments

{
  "_comment": "Last edited 2026-05-28 — switched skill_store to sqlite for local dogfooding",
  "substrate": { "skill_store": "sqlite" }
}

​

Adopter-custom substrate impls

import { Registry, McpServer, Scheduler } from "skillscript-runtime";
import { FooSkillStore } from "./foo-skill-store.js";

const registry = new Registry();
registry.registerSkillStore("primary", new FooSkillStore({ /* config */ }));
// ... register other substrates, then construct Scheduler + McpServer + DashboardServer

"skill_store": {
  "type": "custom",
  "module": "./foo-skill-store.js",
  "export": "FooSkillStore",
  "config": { ... }
}

​

Operational tips

​

Switching substrates without losing data

1. Read each .skill.md file from ~/.skillscript/skills/ (or your skillsDir)
2. Call skill_write MCP tool (or store.store(name, source) programmatically) to land them in the new substrate

​

Multi-instance posture

# Dev — filesystem skills, port 7878
skillfile dashboard --host 127.0.0.1 --port 7878

# Adopter — sqlite skills, port 7879
skillfile dashboard --host 127.0.0.1 --port 7879 --connectors ~/.skillscript/adopter-connectors.json

​

Verifying which substrate is wired

curl -s -X POST http://localhost:7878/rpc \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"runtime_capabilities","arguments":{"include":["skillStores"]}}}' | jq