octoflow-skill-runner

Framework-agnostic SKILL.md loader, validator, catalog renderer, and activation runner for agent runtimes.

octoflow-skill-runner implements the agentskills.io open standard for portable agent skills — without requiring octoflow-core. Use it directly in your own runtime, or let octoflow-core adapt it into Bridge actions and prompt context.

Install

npm install octoflow-skill-runner

Node.js >=20 is required.

Use It When

• You are integrating SKILL.md bundles into a custom runtime that does not use octoflow-core.
• You want to load, validate, and catalog skills from disk or parent directories.
• You need the read_skill / activate_skill tool definitions as plain objects you can map into any tool API.
• You are building a standalone CLI or script that reads and renders skill catalogs without a full agent runtime.

Most octoflow-core users do not need this package directly — skills are activated through createAgent({ skills: [...] }) in that runtime.

What Is Supported

• SKILL.md bundle loading from direct directories or parent directories.
• Full YAML frontmatter parsing for the core protocol fields: name, description, license, compatibility, metadata, and allowed-tools.
• Supported extension fields: disable-model-invocation, user-invocable, and argument-hint.
• Validation, progressive disclosure catalogs that expose each skill's name, description, folder path, and SKILL.md location.
• read_skill / activate_skill tool definitions, resource manifests, and safe resource reads.

Standalone Usage

import { createSkillRunner, loadSkillPaths } from 'octoflow-skill-runner';

const skills = await loadSkillPaths(['./skills', './vendor/skills']);
const runner = createSkillRunner({ skills });

const catalog = runner.buildCatalog();
const tools = runner.createTools();

console.log(catalog?.content);
const overview = await tools[0]!.execute({ name: 'code-review' });

Runnable Example

octoflow-skill-runner does not ship its own CLI binary; the CLI smoke path lives in the examples workspace and imports the package API directly:

yarn workspace octoflow-examples run skill-runner-standalone

That example creates a temporary skill bundle, loads it from a parent directory, renders the catalog, executes the framework-agnostic read_skill tool, and reads an adjacent resource with readSkill().

Runtime Adapter Shape

createSkillRunner() returns plain tool definitions. Any runtime can map them into its own tool API:

const runtimeTools = runner.createTools().map((tool) => ({
  name: tool.name,
  description: tool.description,
  inputSchema: tool.parameters,
  call: tool.execute,
}));

The agent prompt should include runner.buildCatalog()?.content. That catalog lists each skill by name, description, folder path, and SKILL.md location, then instructs the agent to choose a matching skill and call read_skill before acting.

Security Model

Resource reads are resolved inside the selected skill directory. ../ traversal and absolute-path escapes are rejected before the file is read.

Learn More

• ../../docs/tools.md#skills - full skills guide and SKILL.md bundle format.
• ../octoflow-examples/src/api/standalone-skill-runner - runnable example.
• ../octoflow-core - runtime that adapts this package into Bridge actions.

agentskills.io Compatibility

This package implements the agentskills.io specification and is LLM-agnostic — the same SKILL.md bundle works on any backend. Live-tested on Anthropic API, OpenAI API, and Ollama.

| Spec rule | Status | |---|---| | name — required, max 64 chars, [a-z0-9-], matches parent dir | ✅ enforced (error) | | description — required, max 1024 chars | ✅ enforced (error) | | license — optional string | ✅ loaded | | compatibility — max 500 chars if provided | ✅ reported (warning) | | metadata — key/value mapping | ✅ loaded (non-string values warned) | | allowed-tools — space-separated string | ✅ loaded (YAML arrays also accepted) | | Progressive disclosure — catalog = name + description only | ✅ | | Activation — full SKILL.md body loaded on demand | ✅ | | Resources — loaded individually via readSkill({ resource }) | ✅ | | Path traversal protection | ✅ PathTraversalError | | Prototype-pollution-safe YAML parsing | ✅ blocks __proto__, constructor |

Note on compatibility severity: the agentskills.io spec table marks > 500 chars as a hard constraint. This package currently reports it as a warning (not error) so skills are still loadable. Use strict: true in loadSkillBundle options if you want to reject such skills.

Validate

npm run -w octoflow-skill-runner lint
npm run -w octoflow-skill-runner typecheck
npm run -w octoflow-skill-runner test

Status

Preview. Pin versions and read ../../CHANGELOG.md before depending on it in production.