← Reusable skills
Extend kcode

Commit subjects in, the next version out.

kcode runs this Lua skill itself. It reads the version from package.json or Cargo.toml and returns the next version and its changelog section, checked against the shape the skill promises.

How the files work together

SKILL.md names run.lua as its entry, which makes this a script skill. Its frontmatter declares the one access the code gets, a read of package.json and Cargo.toml, and the shapes of the input and the result. run.lua defines run(args), which kcode calls with the checked inputs. test_run.lua runs run.lua under plain Lua with a stand-in for kcode.fs_read.

Install and use

Put SKILL.md and run.lua in ~/.kcode/skills/next-version/, or in <project>/.kcode/skills/next-version/ for one project. Ask the agent for the next version: it passes the subjects from git log as commits through run_skill and gets back the result with the skill's instructions. Typing /next-version followed by the inputs as JSON runs it too.

Unless a permission rule allows run_skill, kcode asks before the run. The code of a project skill also waits for your approval when it is new or changed since you trusted the project.

A real run

This is the result kcode returned for three commit subjects, in a project whose package.json holds version 1.4.2:

// commits:
//   feat(cli): add --json
//   fix(api): retry once on 503
//   docs: fix a typo
{
  "next": "1.5.0",
  "bump": "minor",
  "changelog": "## 1.5.0\n\n### Features\n- add --json\n\n### Fixes\n- retry once on 503",
  "current": "1.4.2"
}

Review the result against the project's versioning rules before changing the changelog or version or creating a tag. A bump of none means the inspected commit subjects do not indicate a version change.

And these are kcode's refusals, from three runs that break the skill's promises:

# commits as one string, not a list
skill `next-version` inputs failed validation: schema validation failed:
/commits: "feat: one string, not a list" is not of type "array"

# run.lua changed to return bump = "huge"
skill `next-version` result failed its output schema: schema validation failed:
/bump: "huge" is not one of "major", "minor" or 2 other candidates

# run.lua changed to read notes.txt first
fs_read: `notes.txt` is outside plugin `skill:next-version`'s
declared `fs.read` paths

Test it yourself

Run the tests in Lua 5.5, the Lua kcode runs the skill in. Code that passes in an older Lua or in LuaJIT can still fail to load in kcode: Lua 5.5 makes a for loop's variables read-only, for one.

lua test_run.lua

What kcode supplies, and what it does not

kcode runs run.lua in a fresh Lua 5.5 state with only the table, string, math and utf8 libraries, under a 64 MiB memory cap and a 60-second limit. Its reads, kcode.fs_read and kcode.fs_list, reach the two declared files and nothing else. The other calls a script skill can make, to run a tool, notify, fetch or write a file, raise an error that names the capability the skill lacks. kcode runs one copy at a time per project, because the skill does not set parallelizable, and creates its state folder, .kcode/skill-state/next-version/, though this skill keeps nothing there.

The skill runs no git and writes no file: the agent passes the subjects in and acts on the result, as the instructions in SKILL.md say. For the other kind of skill, a guide the agent follows with its own tools, see the video frames example.

next-version/SKILL.md

---
name: next-version
description: Work out the next release version and its
  changelog section from Conventional Commit subjects.
entry: run.lua
capabilities:
  fs.read: [package.json, Cargo.toml]
input_schema:
  type: object
  required: [commits]
  additionalProperties: false
  properties:
    commits:
      type: array
      items: {type: string}
output_schema:
  type: object
  required: [current, next, bump, changelog]
  properties:
    current: {type: string, pattern: '^\d+\.\d+\.\d+$'}
    next: {type: string, pattern: '^\d+\.\d+\.\d+$'}
    bump: {enum: [major, minor, patch, none]}
    changelog: {type: string}
---

# Next version

Run this before a release. Pass the commit subjects since
the last tag, from `git log --format=%s <last tag>..HEAD`.

Review the result against the project's versioning rules
before putting `changelog` at the top of CHANGELOG.md,
setting the version to `next` and tagging it. When `bump`
is `none`, the inspected commit subjects do not indicate
a version change.

next-version/run.lua

-- next-version: the next semantic version from Conventional Commit subjects.
-- kcode.fs_read reaches only the two files under fs.read in SKILL.md.

local function current_version()
  local ok, text = pcall(kcode.fs_read, "package.json")
  if ok then return text:match('"version"%s*:%s*"(%d+%.%d+%.%d+)"') end
  ok, text = pcall(kcode.fs_read, "Cargo.toml")
  if ok then return text:match('\nversion%s*=%s*"(%d+%.%d+%.%d+)"') end
end

local SECTIONS = {
  { key = "breaking", title = "Breaking changes" },
  { key = "feat", title = "Features" },
  { key = "fix", title = "Fixes" },
}

function run(args)
  local current = current_version()
  if not current then error("no version in package.json or Cargo.toml") end
  local major, minor, patch = current:match("(%d+)%.(%d+)%.(%d+)")
  major, minor, patch = tonumber(major), tonumber(minor), tonumber(patch)

  local found = { breaking = {}, feat = {}, fix = {} }
  for _, subject in ipairs(args.commits) do
    local kind, rest, text = subject:match("^(%a+)([^:]*):%s*(.+)$")
    if kind and rest:sub(-1) == "!" then
      table.insert(found.breaking, text)
    elseif found[kind] then
      table.insert(found[kind], text)
    end
  end

  local bump = (#found.breaking > 0 and "major")
    or (#found.feat > 0 and "minor")
    or (#found.fix > 0 and "patch")
    or "none"
  -- Before 1.0.0, a breaking change moves the minor number.
  if bump == "major" and major == 0 then bump = "minor" end

  local next_version = ({
    major = (major + 1) .. ".0.0",
    minor = major .. "." .. (minor + 1) .. ".0",
    patch = major .. "." .. minor .. "." .. (patch + 1),
    none = current,
  })[bump]

  local lines = { "## " .. next_version }
  for _, section in ipairs(SECTIONS) do
    if #found[section.key] > 0 then
      table.insert(lines, "\n### " .. section.title)
      for _, text in ipairs(found[section.key]) do table.insert(lines, "- " .. text) end
    end
  end

  return { current = current, next = next_version, bump = bump, changelog = table.concat(lines, "\n") }
end

next-version/test_run.lua

-- Tests for run.lua with a stand-in for kcode.fs_read. Run from this folder in Lua 5.5,
-- the Lua kcode runs skills in: lua test_run.lua

local files = {}
kcode = {
  fs_read = function(path)
    return files[path] or error("fs_read: `" .. path .. "` does not exist")
  end,
}
dofile("run.lua")

local failures = 0
local function check(name, got, want)
  if got ~= want then
    failures = failures + 1
    print("FAIL " .. name .. "\n  got:  " .. tostring(got) .. "\n  want: " .. tostring(want))
  else
    print("ok   " .. name)
  end
end

files = { ["package.json"] = '{ "name": "app", "version": "1.4.2" }' }
local r = run({ commits = { "fix(api): retry once on 503", "docs: typo", "feat: add --json" } })
check("should bump the minor when a feature landed", r.next, "1.5.0")
check("should list features before fixes", r.changelog,
  "## 1.5.0\n\n### Features\n- add --json\n\n### Fixes\n- retry once on 503")

r = run({ commits = { "feat(cli)!: drop --legacy", "fix: tidy" } })
check("should bump the major when a subject ends its type with !", r.next, "2.0.0")

r = run({ commits = { "fix: tidy" } })
check("should bump the patch when only fixes landed", r.next, "1.4.3")

r = run({ commits = { "docs: typo", "Merge branch 'main'" } })
check("should return bump none when no subject is a feature or a fix", r.bump, "none")
check("should keep the version when bump is none", r.next, "1.4.2")

files = { ["Cargo.toml"] = '[package]\nname = "app"\nversion = "0.9.1"\n' }
r = run({ commits = { "feat!: new config format" } })
check("should move the minor for a breaking change before 1.0.0", r.next, "0.10.0")

files = {}
local ok, err = pcall(run, { commits = { "fix: x" } })
check("should fail when neither file holds a version", ok, false)
check("should say where it looked", tostring(err):find("no version in package.json or Cargo.toml", 1, true) ~= nil, true)

if failures > 0 then os.exit(1) end