skill-runtime-adapter

Generic Agent Skills orchestrator + runtime adapter with SSE progress hooks.

Patterns extracted from a production developer platform where Skills own the build loop and MCP owns publish/ship only — but this repo is vendor-neutral and reusable in any SKILL.md + agent-host setup.

Architecture

POST /agent { prompt }
        │
        ▼
  skillOrchestrator.classify()  ── rule-based, no LLM
        │
        ├── workflow: agent ──► skillRuntime.run() ──► your agent engine
        │
        └── workflow: ship  ──► shipPipeline()      ──► MCP publish adapter (you implement)

Build vs ship split (recommended)

Lane	Responsibility	Typical tools
Build	Codegen, validate, sandbox shell	SKILL.md, read/write files, run_shell
Ship	Upload artifact, submit to environment	MCP: create_upload_url, PUT, submit

Keep MCP out of the coding loop when tool sprawl and trust boundaries matter.

Install

git clone https://github.com/YOUR_USER/skill-runtime-adapter.git
cd skill-runtime-adapter

No npm dependencies. Node 18+.

Usage

const { createAgentRuntime, createRuntime } = require('skill-runtime-adapter');
const events = require('./events'); // your SSE bus
const myAgentEngine = require('./my-agent-engine');

const runtime = createRuntime(myAgentEngine, events);

const agent = createAgentRuntime({
  runtime,
  ship: async (session) => myMcpPublishAdapter.ship(session),
  events,
  hooksFactory: () => ({
    emit: events.emit,
    log: (id, line) => events.emit(id, 'agent.log', { line }),
    appendMessage: sessionStore.appendMessage,
    snapshotFiles: async (s) => ({ /* ... */ }),
  }),
});

// Express route
app.post('/sessions/:id/agent', async (req, res) => {
  const session = await sessions.get(req.params.id);
  const result = await agent.run(session, req.body.prompt);
  res.json(result);
});

See examples/minimal-express.js.

Orchestrator routes

Default rule-based routes (extend ROUTES in src/orchestrator.js):

Intent	workflow	skill
ship / publish app	ship	publish
review / audit	agent	review
install / setup cli	agent	setup
scaffold + empty workspace	scaffold	app-dev
default	agent	app-dev

SSE events emitted

Event	When
agent.log	Orchestrator route line, agent stdout
agent.run.done	Agent or ship pipeline finished
analytics	skill_invoked telemetry
agent.file_changed	Your engine emits on write (optional)

Companion project

cavecrew — compressed subagent delegation to survive long sessions.

License

MIT — see LICENSE.