LuaSkills

Documentation hub | Skill template | CodeKit example

LuaSkills is a Rust-powered runtime for loading, running, and managing Lua-based skills. It gives host applications a compact way to add scriptable tools, structured help, runtime capabilities, dependency paths, and database-aware skill execution without turning every host into its own plugin runtime.

In one sentence: LuaSkills runs skills; the host decides how those skills become product features.

What It Is

LuaSkills is the core runtime layer for the LuaSkills ecosystem. It is designed for applications that want a controlled skill system instead of one-off embedded scripts.

It provides:

Skill discovery, loading, entry enumeration, and invocation.
Strict help trees that hosts can render as docs, command palettes, tools, or UI panels.
Standard Lua capability namespaces under vulcan.* and system-side helpers under vulcan.runtime.*.
Runtime context injection for current requests, skill directories, resources, dependency roots, and client metadata.
Optional SQLite and LanceDB bindings for stateful or memory-oriented skills.
Rust API integration for Rust hosts.
Standard C ABI and public _json FFI for non-Rust hosts.
SDK-oriented integration paths for TypeScript, Python, and Go.

What It Is Not

LuaSkills intentionally does not own the whole product surface.

It is not:

An MCP server by itself.
A host configuration file reader.
A client budget calculator.
A product UI renderer.
A sandbox boundary for untrusted Lua code.

Hosts stay in charge of policy, authentication, user experience, budgeting, permission prompts, storage placement, and how skills are exposed to users.

Why Use It

Use LuaSkills when you want skills to feel like a product capability instead of loose scripts.

Good fits include:

AI agents that need reusable local tools.
IDEs and developer tools that want scriptable workflows.
Desktop or server hosts that need first-party and user-installed skills.
Products that want a stable runtime contract across Rust, C ABI, TypeScript, Python, and Go.
Memory, database, search, or automation skills that need a clear host ownership model.

LuaSkills is especially useful when you need a split between runtime truth and host presentation:

The runtime knows how to load and execute skills.
The host knows what the user is allowed to do.
The skill author gets stable vulcan.* APIs instead of guessing host internals.

Core Capabilities

Area	What LuaSkills Provides
Skill runtime	Load skills, list entries, call entries, reload roots, and manage lifecycle operations.
Lua API	Inject `vulcan.call`, `vulcan.fs`, `vulcan.path`, `vulcan.process`, `vulcan.os`, `vulcan.json`, `vulcan.cache`, `vulcan.context`, `vulcan.deps`, `vulcan.sqlite`, `vulcan.lancedb`, and `vulcan.runtime`.
Help model	Parse strict skill help trees and expose structured help for host rendering.
Host boundary	Keep product policy, UI, budgets, and permissions outside the runtime.
Database providers	Support dynamic-library, host-callback, and space-controller modes for SQLite and LanceDB.
Multi-language integration	Expose Rust APIs, standard C ABI, and public `_json` FFI for SDKs and host bridges.
Skill roots	Support layered roots such as `ROOT`, `PROJECT`, and `USER` with host-controlled management authority.

Ecosystem

LuaSkills is most useful when read together with its ecosystem repositories.

vulcan-codekit: a production-grade LuaSkills example that exposes source-code navigation, AST inspection, structural search, Markdown navigation, and safe patching workflows.
vulcan-curl: an HTTP request skill built around structured GET / POST entries and curl-style request execution.
vulcan-file: a focused file operation skill for ignored-aware listing, exact text reads, and preview-first small edits.
vulcan-lua: a controlled Lua execution skill for bounded inline code or file-based Lua tasks.
vulcan-testkit: a validation router that turns build, test, lint, and typecheck output into compact diagnostics.
vulcan-workmem: a project-scoped working-memory skill for durable task checkpoints and handoff context.
demo-skill: a minimal skill repository template for learning package layout, skill.yaml, runtime entries, and help files.
luaskills-sdk-typescript: TypeScript and Node.js SDK for the public _json FFI path.
luaskills-sdk-python: Python SDK for ctypes-based public _json FFI integration.
luaskills-sdk-go: Go SDK for cgo-backed public _json FFI integration.
vulcan-mcp: MCP host and protocol adaptation layer.

Documentation

Start here:

Documentation hub: English navigation and product-level map.
Chinese documentation: Chinese product overview and full technical docs entry.
Why LuaSkills: product narrative, architecture value, and supported integration categories.
Skill development manual: full English manual for skill authors.
FFI and SDK overview: English overview for host integrators.
Database provider overview: English overview for SQLite and LanceDB ownership.
Runtime architecture overview: English overview of host/runtime boundaries.
Chinese docs index: full Chinese technical documentation map.

Important technical docs:

Integration Paths

Choose the path by host type:

Host type	Recommended path
Rust	Use the Rust crate directly.
C / C++ / low-level hosts	Use the standard C ABI.
TypeScript / Node.js	Use `luaskills-sdk-typescript` over the public `_json` FFI.
Python	Use `luaskills-sdk-python` over the public `_json` FFI.
Go	Use `luaskills-sdk-go` or the standard C ABI depending on callback and deployment needs.
Mixed host	Use standard C ABI for the stable core path and public `_json` FFI for dynamic operations or SDK-style integration.

Quick Start

Rust hosts can depend on the crate directly:

[dependencies]
luaskills = "0.3"

Repository development uses the normal Rust workflow:

cargo check
cargo test --lib

The direct Rust host example lives in examples/demo-rust and covers both call_skill and the vulcan.host.* host-tool bridge.

To learn the skill package shape before writing a host integration, start with:

For FFI hosts, begin with:

Skill Naming Rules

skill_id and every entry.name must match ^[a-z]([a-z0-9-]*[a-z0-9])?$. The physical skill directory name is the only skill_id; skill.yaml must not declare a skill_id field. Canonical entries use {skill_id}-{entry_name} and may receive a stable -N suffix on conflicts. For GitHub-managed skills, the repository-derived or explicit skill_id, release zip prefix, checksum prefix, zip top-level directory, and final installed directory must be identical. Use {skill_id}-v{version}-skill.zip, {skill_id}-v{version}-checksums.txt, and a zip containing {skill_id}/skill.yaml.

Trust Model

LuaSkills currently treats skills as trusted code by default. It does not provide a sandbox security promise for arbitrary untrusted Lua packages.

Product hosts should decide:

Which roots are enabled.
Which skills are installed or ignored.
Which management actions are exposed.
Which database provider mode is allowed.
Which user or system authority is attached to an operation.

Repository Layout

README.md        English product homepage.
README.zh-CN.md  Chinese product homepage.
README.ja.md     Japanese product homepage.
README.ko.md     Korean product homepage.
README.es.md     Spanish product homepage.
README.fr.md     French product homepage.
README.de.md     German product homepage.
README.pt-BR.md  Brazilian Portuguese product homepage.

src/
  dependency/    Skill dependency parsing, installation, and cleanup.
  download/      GitHub, URL, and archive download support.
  host/          Host callbacks and host option models.
  providers/     SQLite and LanceDB provider bindings.
  runtime/       Engine, context, help, result, logging, and cache runtime.
  skill/         Manifest, source records, and lifecycle management.
  ffi.rs         Public `_json` FFI exports.
  ffi_standard.rs Standard C ABI exports.

docs/
  index.md       English documentation hub.
  skill-development.md
                 English skill author overview.
  architecture/  English runtime architecture overview.
  ffi/           English FFI and SDK overview.
  product/       English product-level documents.
  providers/     English database provider overview.
  zh-CN/         Chinese product and deep technical documentation.
  ja/            Japanese product documentation.
  ko/            Korean product documentation.
  es/            Spanish product documentation.
  fr/            French product documentation.
  de/            German product documentation.
  pt-BR/         Brazilian Portuguese product documentation.

examples/
  demo-rust/     Rust host demo with call_skill and host-tool bridge examples.
  demo-ffi/      Packaged FFI demo entry.
  ffi/           C, Python, Go, TypeScript, runtime fixture, and provider demos.

Ecosystem Release Order

For one unified ecosystem release such as 0.3.1, publish in this order:

Release LuaSkills/luaskills-packages first so lua-runtime-packages-* and lua-deps-* already exist for the new compatible series.
Release LuaSkills/luaskills next, including the crate version plus the main-repo luaskills-ffi-sdk-* and demo assets under tag v0.3.1.
Publish the TypeScript SDK @luaskills/sdk@0.3.1.
Publish the Python SDK luaskills-sdk==0.3.1.
Publish the Go SDK module tag v0.3.1.
Run the Examples Release workflow for each SDK only after its package or module tag is already visible upstream.

This order keeps every installer and examples workflow pointed at already-published packages assets, core assets, and SDK packages.

License

MIT

luaskills 0.3.1