Skills layout

A skill is a directory that holds a SKILL.md, plus whatever scripts and references sit next to it. A source is a git repository that holds several skills under one path. Organization skills reach a worker through one generated script, buildSkillsScript. It runs as the skills phase of the first setup (after dotfiles, before the project's clones), and again as a refresh before each delegated task, because a recycled worker never replays its setup.

The script runs twice on the same disk, possibly from two different package versions. On its second run, it has to recognize what its first run left. The layout below is therefore a format: the script's earlier self, the harness and the people reading the log all depend on it. Module reference: script.

On diskCopy Anchor Link

Discovery directoriesCopy Anchor Link

Discovery directories are where the harness looks for user-level skills. The caller passes them as shell expressions, which are evaluated inside the worker, because only the worker knows its environment. A member can set CLAUDE_CONFIG_DIR as a secret. For Claude Code, the expression is:

"${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills"

Spunto Cloud gets this from each harness pack's declaration and sends the union of all packs' directories. Every retained skill is linked into each discovery directory.

What a run doesCopy Anchor Link

The ledger is what makes refresh safe. The script never infers from the filesystem what it owns. A symlink is only removed if the script recorded it, so nothing that a person put in a discovery directory is ever touched, even if it looks like one of ours.

The [skills] log prefixCopy Anchor Link

The script never fails. A skill that could not be fetched makes for a worse worker, not a broken one. Every problem is printed on stdout with a [skills] prefix, and the script ends with exit 0. The setup phase that runs it adds its own fallback: … || echo "[skills] ✗ skills script exited with $?".

These are the lines it prints, verbatim, with shell variables in place:

[skills] <label> @ <ref|default branch> → <full commit sha>
[skills] linked <name> → <discovery dir>/<name>
[skills] unlinked <name>
[skills] removed source <id>
[skills] <label>: ref changed to '<ref|default branch>' — cloning again

[skills] ⚠ <label>: fetch failed — keeping <short sha>
[skills] ⚠ <label>: cannot fast-forward (local changes?) — keeping <short sha>
[skills] ⚠ <id>: no directory '<path>' in the source
[skills] ⚠ <name>: already linked from another source — skipped
[skills] ⚠ <name>: <discovery dir>/<name> already exists — kept, not linked

[skills] ✗ cannot write <home>/.spunto/skills
[skills] ✗ <label>: nothing to clone from
[skills] ✗ <label>: clone failed — its skills are not linked

<label> is the source's human label (owner/name) and is never a URL, so that a credential cannot end up in the log. The @ … → <sha> line logs the exact commit that was materialized, for the audit trail: these scripts run with the worker's secrets.

CredentialsCopy Anchor Link

• Each source's fetchUrl may carry a credential. It can be overridden at run time by the environment variable SPUNTO_SKILL_FETCH_URL_<index> (skillFetchUrlEnv(index)), so that a caller whose command text is kept in a history can pass the credential out of band.
• After a clone, origin points at originUrl, which is credential-free. Anything that happens later in the worker (an agent fixing a skill and pushing a branch) goes through the credential helper as the member, not with the organization's clone token.
• The script runs as the workspace user, never as root, so every file it creates belongs to that user. It sets GIT_TERMINAL_PROMPT=0, so a missing credential fails instead of hanging.

CompatibilityCopy Anchor Link

Changing SKILLS_DIR or the .links filename would make the next refresh on an existing worker treat its own earlier links as foreign. They would be kept and reported as "already exists — kept, not linked" on every run, and under a new SKILLS_DIR the old clones would be orphaned. Renaming spunto-ref is milder, but it still has an effect: every clone made from a non-empty ref would look like a ref change and be cloned again once. Treat these names the way you treat names and paths.