Changes for version 0.008000 - 2026-11-21

  • One version line in two spellings: the CPAN dist Skilletor 0.008000 is the plugin's 0.8.0 (package.json, the Codex and Hermes manifests). The dist keeps both sub-levels, x.yyyzzz for the plugin's x.y.z, so the next patch is 0.008001 (0.8.1). The Perl CLI reports it. The Claude Code manifest carries no version any more, so every commit on main reaches marketplace users with auto-update.
  • The Perl distribution Skilletor lives at the root of the repository and is released with dzil; its tag is the bare version. It is now the whole tool, not a library: a `skilletor` command (script/skilletor) that behaves like the TypeScript CLI; shared conformance cases hold both to the same output. Requires Perl 5.40, Text::Nunjucks 0.001 and, on Windows, Win32::Process.
  • Standalone binaries (no Perl, no Node) for linux-x86_64, linux-arm64, macos-arm64 and windows-x86_64 are built by the house dzil-binary workflow and attached to the GitHub release. Each carries its own OpenSSL, linked statically on Linux and macOS, Strawberry Perl's OpenSSL DLLs packed in on Windows, so https url sources need no system OpenSSL.
  • The plugin's hooks and bin/skilletor start through bin/skilletor-start, which runs, first match wins: the release binary of the plugin's version, cached under <claudeConfigDir>/skilletor/bin/ and checked against the SHA256SUMS pinned in bin/skilletor-binaries.sha256; else Node.js >= 18; else Perl >= 5.40 from source. Without that pin file nothing is downloaded. It does not exist in this release: the maintainer commits it once the binaries are built, until then the plugin runs Node (or Perl) as before. A SessionStart hook fetches the binary in the background and never waits for it; a failed fetch backs off for 15 minutes. --version and -v never fetch. For now the plugin on Windows keeps starting Node through bin/skilletor.exe; the windows-x86_64 binary is there to run skilletor directly, installed from the release (install.ps1, which the release carries, does it). The bundled skill and the Hermes reference describe this order.
  • skilletor is licensed under the Artistic License 2.0 from this release, the dist (Perl 5 terms in 0.001) and the plugin (MIT up to 0.7.0) alike.
  • `install.sh` sets skilletor up from a plain shell (GitHub issue #1): `curl -fsSL https://raw.githubusercontent.com/Getty/skilletor/main/install.sh | sh` installs the plugin when `claude` is on `PATH` (or updates it) and writes a `~/.local/bin/skilletor` that survives plugin updates; without Claude Code, or with `--no-plugin`, it clones the repository and links `bin/skilletor`. Without Node.js it leaves the plugin metadata alone and links the starter after checking that it runs. `--bin-dir` picks the directory. The README has it under "From the command line".
  • A session that moves into another checkout of a skilletor project (a plain `git worktree add`, say) gets that checkout's project scope synced, so the worktree completes itself: one line names the directory, and the model is told what landed. In Claude Code a Bash `cd` is awaited (a `PostToolUse` hook), so the next tool call finds the items; other moves are seen by `CwdChanged`, which is not awaited. A Codex or Hermes session moves only between turns, and the next prompt waits for the sync. Under Hermes, when skills landed, the line names `hermes skills trust <dir>`; skilletor never reads or writes Hermes trust. After updating, trust the changed hooks again in Codex `/hooks` and run `hermes plugins update skilletor` for the Hermes plugin.
  • The Perl CLI has every command of the TypeScript one: sync, check and status (--scope, --force, --project-dir, --json), add, install, uninstall (wildcards, bundles, prompts, scope-aware removal), source list and remove, available, trust, and the Claude Code, Codex and Hermes hooks. The engine renders .njk items through Text::Nunjucks and syncs the Codex and Hermes targets as the reference does; Skilletor::Engine gains a hermes_home attribute and a hermes_opt_in_hint method. Under Windows its programs run through Skilletor::Process, the hooks' background sync through Win32::Process. A Skilletor::Error stringifies to its message, as documented, and the CLI starts faster (--version and --help load one module).
  • A project scope now installs into explicit project targets, or the harnesses that have evidence in that project (their own files, not skilletor's), instead of every machine target. A project with several such harnesses and no explicit targets is left as it is and warned about; a sole machine target stays the fallback. Claude plugin requirements in `.claude/settings.json` are skipped, without check drift, when adding them would change which targets a project infers; items still sync, and explicit project targets allow the update.
  • SessionStart gives source checking, lock waiting and source resolution a 20-second budget before anything is applied; a scope that runs out of it is named, and earlier scopes are not rolled back.
  • `CLAUDE_CONFIG_DIR` is Claude Code's config dir and now the user scope's `.claude` everywhere: the user config, the lock, the installed items, the state dir, the briefing lookup, the plugin state read for the project's `.claude/settings.json` requirement and the Claude detection markers. Default `<home>/.claude`; an empty value counts as unset.
  • A sync resolves its sources in parallel but reports what became of each (a failure, a fall back to the cache, a trust request) in the order the sources are declared, so the report and --json no longer vary from run to run.
  • Malformed input is refused instead of read loosely. A source's `skilletor.json` whose `vars` is not an object fails that source's scan; a lock entry that is not an object, whose `via` is not an array of strings or whose `files` is not a map of strings makes the lock invalid; a url tarball cut short is a corrupt archive (the cache stays), as is one with a corrupt header size, which used to hang a sync.
  • Hooks fail open more thoroughly: from a working directory that no longer exists, with null or non-object JSON, or a non-string `cwd`, a hook exits 0 with at most one warning line instead of a stack trace. Other commands from a removed directory exit 1 with a message that points to --project-dir.
  • An included template's syntax error is a warning on that item at once rather than a delayed crash; unaffected items still install. Plain items no longer look up the operating system's user, only a `.njk` file does.
  • Fixes from the Perl port's comparison: a source serving two foreign entries of one bundle asks for trust once; a `\U` escape above U+10FFFF in a bundle file is that bundle's warning, not an error that aborts the source scan; a SKILL.md, agent or rule with CRLF line ends or a BOM keeps its description in the catalog; frontmatter, Codex agent conversion and hook state keep keys named like Object.prototype members (`__proto__`, `constructor`) as data; `uninstall` no longer throws on a non-string entry in an install list; `available` matches item names without regard to case.
  • On Windows, an existing project path is spelled canonically, so its 8.3 and long names share one scope, pending report and last check. Managed `.gitignore` and `.worktreeinclude` blocks recognize CRLF files and leave every byte outside the markers unchanged. Items of a published layout are listed in UTF-8 byte order on every platform.
  • The Perl port reads a large state file (a 300 KB sources-read.json) in a quarter second instead of 10 s and more, so `check` and the SessionStart hook no longer stall on it: its JSON parser no longer copies the text for every string and number (k196).
  • A sync drops from sources-read.json the records of scopes that are gone: a removed worktree or temp checkout, or a key a relative --project-dir left (k254). A scope stays while its .claude directory exists, with or without a lock. On a machine with many removed worktrees this cut the file from 300 KB to 55 KB. A relative --project-dir is now taken from the current directory, so the scope is recorded under its absolute path.
  • A sync also drops from render-inputs.json and unreached.json the records of scopes that are gone, as from sources-read.json (k255). Marking the in-session check drops from last-check.json the marks of project directories that no longer exist, and of keys that are no absolute path; a project without .claude keeps its mark. On a machine with many removed worktrees this cut render-inputs.json from 126 KB to 23 KB and last-check.json from 16 KB to 8 KB.
  • A SessionStart reads each state record file at most twice instead of up to six times: its check once for both scopes, its sync once under the sync lock (k250). The Perl port spends a quarter second on each parse of a 300 KB sources-read.json, so its SessionStart on such a file takes 1.0 s instead of 2.0 s (the binary 1.2 s instead of 2.3 s). The files written stay byte for byte the same.
  • A run stopped while it holds the sync lock (Claude Code cancelling a hook at its time limit with SIGTERM, Ctrl+C, a closed terminal) now releases the lock and still ends by that signal, in Node, Perl and the binary. A SIGKILLed holder's lock is broken by the next run once its record missed two refreshes, and the Perl heartbeat no longer refreshes a dead holder's record (k251).
  • A cached binary that fails its pinned checksum is still refused, and the starter's line now says so on every path that falls through to it (--version, -v, any hook, a failed fetch, the SessionStart backoff) instead of "the pinned binary is not cached" (k252).
  • bin/skilletor-start fetches the release binary only over https://. A SKILLETOR_BINARY_BASE_URL of another scheme (http://, file://) is refused unless SKILLETOR_STARTER_TESTING=1, as briefing's starter does; the starter's line says why, and Node or Perl run instead (k253).
  • The README and the POD of Skilletor and skilletor open with the product and its use: what it does, installing it in Claude Code, Codex and Hermes Agent, first steps and everyday use with real output, and a Status of what is released, switched on and tested where. The Perl implementation, the CPAN library and the build move to a short Develop part. New ASCII abstracts for Skilletor and skilletor. Module POD fixed where it was false: Engine (Codex skills of both scopes in .agents/skills), Targets (writes for Hermes too; the .gitignore blocks skip Hermes roots), Briefing (the Codex skill roots) (k258).

Documentation

The skilletor command: skills, agents and rules for Claude Code, Codex and Hermes Agent

Modules

Install and sync skills, agents and rules for Claude Code, Codex and Hermes Agent
The Codex rules file, the pointer block in a Codex AGENTS.md, and the checks of Codex's config.toml
Apply a build plan to disk – diff, atomic writes, conflicts, removal (spec §6.1–6.3)
Choose a source's backend (author mode) and build it – one value for trust and fetch
Are an installed agent's briefing skills there? (spec §6.7)
Bundle files (spec §15), their expansion, and name patterns
The skilletor command line – arguments, usage, exit codes (spec §7)
Where a git or url source is cached – the reference's cache naming
Scan a source tree into its installable items, bundles and source metadata
The plugin requirement in a project's committed .claude/settings.json (spec §6.8, k140)
The CLI's config commands – add, trust, source list, source remove, available, install, uninstall – after the reference's commands.ts
Load, merge and validate the user, project and local skilletor config
A Claude agent as a Codex agent role, a rule as its section of the Codex rules file
sync, check and status for Claude Code, Codex and Hermes – the reference's engine pipeline after the resolve
Install entries ([type:]name@source, patterns, bundles) and the names they hold
Exception base class of Skilletor
A lookup that would have to hide one of two items: a rule both scopes declare
A build plan that cannot be applied: an invalid item name, a path leaving its root
The skilletor markers in an AGENTS.md are malformed (the reference's BlockError)
A bundle file is broken or cannot be expanded (the reference's BundleError)
A cache that must not be served (the reference's CacheRejected)
A source tree cannot be scanned (the reference's CatalogError)
A command refused before it changed anything (the reference's CommandError)
A config file is invalid (the reference's ConfigError)
An item cannot be converted for a harness (the reference's ConvertError)
YAML frontmatter or a bundle file outside the supported subset (the reference's FrontmatterError)
A text is not JSON (JSON.parse's SyntaxError)
A scope's lock file cannot be read (the reference's LockError)
Another run held the sync lock too long (the reference's SyncLockTimeoutError)
A template cannot be rendered (the reference's RenderError)
A source backend failed to resolve or check
An add shorthand cannot be resolved (the reference's SpecError)
A value TOML cannot hold (the reference's TomlWriteError)
A url source's archive is unsafe (the reference's TarError)
No agent harness can be targeted (the reference's TargetError)
An item a lookup cannot serve: a Nunjucks template
File and path helpers that behave as the reference's Node calls do
The reference's YAML subset – agent frontmatter and bundle files
The environment of every git run – without git's repository-local variables
Managed .gitignore and .worktreeinclude blocks, skill .gitignore files, git's view (spec §6.4)
gunzip and inflate as Node's zlib binding does them, with zlib's messages
The session hooks – SessionStart, UserPromptSubmit, the background sync and the checkout moves (spec §8)
JSON read and written exactly as the reference implementation does
A tied hash that keeps a JavaScript object's property order
String operations as JavaScript performs them
A scope's lock file (skilletor.lock.json) – reading, writing, its keys
The probe of `skilletor add` for a generic host – git ls-remote, then a HEAD on the tarball
Run a program without a shell – cwd, environment, timeout, captured output
Build an item in memory – the reference's render.ts
A Nunjucks loader confined to an item's source root – the reference's makeLoader
The reports of sync, check and status – their shape, their text, their exit codes (spec §8)
What each scope resolves to – a sync's steps 1–3, stopped before anything is built
The interface of a source backend (local, git, url)
A git source: shallow fetch into the shared cache, refs, SHA pins, offline reuse
A source read straight from a local directory (author mode)
A url source: an https .tar.gz, conditional GET, staged swap into the shared cache
Resolve an add shorthand (owner/repo, a forge link, a URL, a path) to a source
Instance state under ~/.claude/skilletor – trust, the sync lock and the records a sync keeps
The reference's TOML writer – what a Codex agent role needs
The reference's minimal tar reader: safe file and dir entries only
Which agent harnesses a sync installs for (detection and the targets merge)
The parts of a URL as the WHATWG URL parser (Node's new URL) gives them