Skills: guides and programs
kcode runs a skill for one useful result that different workflows reuse, either as a guide the agent follows or as a program kcode runs itself.
Start with a task and a result
A video-frame skill accepts a local video, an interval, and an output directory. It returns screenshots with timestamps. It does not also summarize the video, critique the UI, or write a storyboard. Those are workflows that can use this capability.
The bundle is one cooperating unit
SKILL.md tells the agent when the capability fits, what it needs, and how to run it. Bundled code performs mechanical work. Templates and assets can support that method. For video extraction, the guide supplies the method, the script produces the images, and the tests check the expected frames and failure cases.
The agent drives a guide-based skill
The loader discovers the guide, and run_skill prepares its environment and returns instructions with bundle paths substituted. The current agent then follows the method using its tools. A guide can direct the agent to run Python or other bundled code through the shell; that is different from declaring an executable entrypoint.
Script skills have typed contracts
A SKILL.md that names an entry file, run.lua, makes a script skill. kcode checks inputs against input_schema before the run and the result against output_schema after it, so each call behaves like a typed function.
Script skills run in a sandbox
kcode runs the entry once per call. Lua gets the table, string and math libraries with memory and time limits. A Lua skill reaches files, hosts, notifications or other tools only through its capabilities. Each tool it calls must be listed in tool-dependencies and passes the same permissions and plugin hooks as the agent’s own calls. A script with no capabilities is a pure function of its inputs.
State, and one run at a time
Each skill has a state folder in the main checkout of the project, so every worktree of it shares one, and the state outlives a removed worktree. kcode runs one copy of a script skill per project at a time and refuses a second run while the first holds the lock, unless the skill is marked parallelizable. Script skills are written by people: the agent’s own skill_manage writes guide skills only.
Reuse the result in different workflows
A video summary uses the extracted frames to identify important moments. A visual review inspects them for UI defects. A storyboard arranges them into a sequence. Each workflow uses the same extraction capability instead of carrying its own version of that code.