Agent Skill Runtime

@lunarmoon26/agent-skill-runtime turns skill-owned JSON-in/JSON-out scripts into tools for MCP, OpenCode, and DeepSeek Harness. A versioned skill-runtime.json file supplies the portable tool description; thin host adapters preserve each harness's native lifecycle and cancellation behavior.

Status

This repository contains the version 1 contract and its reference TypeScript implementation. Version 0.1.1 is the current pre-release.

Related MCP server: Skillz

Quick Start

Place a manifest beside a skill's SKILL.md:

{
  "$schema": "https://raw.githubusercontent.com/lunarmoon26/agent-skill-runtime/main/skill-runtime.schema.json",
  "manifestVersion": 1,
  "name": "example-skill",
  "tools": [
    {
      "title": "Run Example",
      "name": "example_run",
      "description": "Run the example workflow.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "message": { "type": "string" }
        },
        "required": ["message"],
        "additionalProperties": false
      },
      "entrypoint": {
        "engine": "node",
        "path": "scripts/main.mjs"
      }
    }
  ]
}

The entrypoint reads one JSON value from stdin, writes one JSON value followed by a newline to stdout, writes diagnostics to stderr, and exits nonzero on failure.

npx @lunarmoon26/agent-skill-runtime validate --root .
npx @lunarmoon26/agent-skill-runtime list --root .
printf '{"message":"hello"}' | npx @lunarmoon26/agent-skill-runtime run example_run --root .
npx @lunarmoon26/agent-skill-runtime mcp --root .

python-uv entrypoints declare exact PEP 723 dependencies in their script. Run prepare before invoking them; normal tool execution uses uv --offline and never downloads packages.

Package Exports

• @lunarmoon26/agent-skill-runtime: discovery, validation, preparation, and execution.

• @lunarmoon26/agent-skill-runtime/opencode: OpenCode tool adapter.

• @lunarmoon26/agent-skill-runtime/deepseek: DeepSeek Harness tool adapter.

• @lunarmoon26/agent-skill-runtime/mcp: MCP stdio server.

See docs/contract.md for the execution and security rules and docs/integrations.md for host examples.

Development

npm install
npm test
npm run verify

Pull requests and pushes to main run the full verification suite on Node.js 22.20 and 24, plus the runtime tests on Bun 1.4.

Releases

npm releases use trusted publishing from GitHub Actions. The release workflow accepts only a vX.Y.Z tag that matches the committed package.json version and points to a commit contained in main. It repeats the Node and Bun verification before publishing. npm uses the workflow's short-lived OIDC identity and adds provenance automatically; no long-lived npm token is stored in GitHub.

Configure the npm package's GitHub Actions trusted publisher once with these exact values:

• Organization or user: lunarmoon26

• Repository: agent-skill-runtime

• Workflow filename: npm-publish.yml

• Environment: none

• Allowed action: direct npm publish

For each release:

1. Update package.json and package-lock.json to the same new version in a reviewed change, then merge it to main.

2. Tag the merged main commit and push the tag:

   git tag vX.Y.Z
   git push origin vX.Y.Z

The tag starts .github/workflows/npm-publish.yml. Branch pushes and pull requests never publish. After the first trusted release succeeds, configure the npm package to require two-factor authentication and disallow traditional publish tokens.

Version 0.1.0 was published manually before release automation existed. Do not create a retrospective v0.1.0 tag after this workflow reaches main; the first automated release must use a new package version and matching tag.