@rien7/skill-action-runtime-cli

CLI for the Skill Action runtime.

Install

pnpm add -g @rien7/skill-action-runtime-cli

Commands

• skill-action-runtime list-skills
• skill-action-runtime list-actions
• skill-action-runtime validate-skill-package
• skill-action-runtime resolve-action
• skill-action-runtime validate-action-input
• skill-action-runtime execute-action
• skill-action-runtime execute-skill

Protocol Transport Usage

The four core protocol commands can be used in two ways:

1. Convenience flags such as --action-id, --skill-id, --input-file, and execution options
2. Full protocol requests via:
   • --request-json <json>
   • --request-file <path>
   • stdin when no request flags are provided

Example with a full request object:

echo '{"action_id":"workflow.increment","input":{"value":4},"options":{"trace_level":"full"}}' \
  | skill-action-runtime execute-action --skill-package ./test/fixtures/sample-skill

This keeps the CLI aligned with the RFC's CLI (stdin/stdout) transport model while still allowing shorter flag-based usage.

Package Loading

Provide either:

• --skill-package <dir> one or more times
• --skills-dir <dir> to load every direct child skill package

If neither is provided, the CLI will:

1. Use the current directory if it looks like a skill package
2. Else use <cwd>/skills if it exists

Discovery And Validation

List loaded skills:

skill-action-runtime list-skills --skills-dir ./skills

List loaded actions:

skill-action-runtime list-actions --skills-dir ./skills

Validate one or more packages:

skill-action-runtime validate-skill-package --skills-dir ./skills

The validation command checks package-level consistency such as:

• entry_action resolves
• fully-qualified global action references are reported as external dependencies

Runtime-Cli Extensions

The RFC core protocol does not define package-local handler modules. This CLI provides an implementation-specific extension via --handler-module for primitive execution.

skill-action-runtime execute-skill \
  --skills-dir ./skills \
  --skill-id my.skill \
  --input-file ./input.json \
  --handler-module ./handlers.mjs

The handler module may export:

• primitiveHandlers
• or a default object containing primitiveHandlers

Troubleshooting

If the CLI binary is not installed, install the published package:

pnpm add -g @rien7/skill-action-runtime-cli

If the CLI reports that no skill packages were found, provide one of:

• --skill-package <dir>
• --skills-dir <dir>

or run the command inside a skill package or a repo root that contains skills/.

If resolve-action or validate-action-input returns ok: false, treat that as a protocol-level failure such as resolution ambiguity, missing packages, or input validation failure.

If execute-action or execute-skill returns ok: true with data.status: "failed", treat that as an execution failure after startup. Common causes include:

• missing primitive executor bindings
• reachable binding or returns resolution failures
• nested action resolution failures
• output validation failures

Only use --handler-module when you intentionally rely on this runtime-cli-specific extension. For RFC-core package validation and protocol checks, prefer flows that do not depend on handler-module wiring.

Build

pnpm install
pnpm check