[mrgoonie]

Closes #166. Follows #120. Overlaps with #163 in git-source.ts, add-source.ts and the docs line saying commit SHAs are not accepted, so whichever PR merges second has to resolve those files.

What changes

Lock, update, sync

• A skill that skillx add reads from git is now pinned as an added entry in the packages lock (skillx.lock.json). The entry records the repository URL (with no credentials), the directory, the ref to follow, the commit and the agentkit.skill-tree/v1 tree digest.
  • The contract lives in packages/contracts/src/install-lock-added.ts and is validated with the rest of the lock.
  • Packages scope only, at most 256 entries, sorted, and an alias may not also appear in packages.
• skillx update re-reads each added skill from its recorded source.
  • It installs the skill from the directory it was installed from. If that directory is gone, it takes the only skill with that name. Two skills with that name elsewhere is a conflict.
  • A source that fails does not stop the others. They are installed and locked, then the command fails and lists every failed source in details.failures.
• skillx sync --locked fetches each locked commit and installs the skill only if its tree digest matches the lock. Any other digest is an integrity_error.
• Uninstalling add:<name> also drops its lock entry.
• A local add over a skill that target had from git drops that pin. Any other local add leaves the lock alone.

Scope and runtimes

• --runtime can be repeated or comma-separated. The source is read once, and every runtime is planned before any is written.
  • If a later runtime fails, the error reports the runtimes already installed (details.installed, details.lockPath).
• --project installs into ./.claude/skills (Claude Code) or ./.agents/skills (Codex). It is also accepted by install, update, uninstall, list and sync.
  • Project state is kept separately under $SKILLX_HOME/projects/<hash of the real path>.
  • If .claude, .agents, the skills directory or the staging directory is a symlink or junction, the command fails with conflict. This is checked when the context is created and again under the install lock.

Commit refs

• @<sha> and /tree/<sha> accept a full 40- or 64-hex commit. It is fetched with git init and then git fetch --depth 1 <url> <sha>.
• The commit is read only if a branch or tag of the named repository contains it. This refuses "imposter" commits that exist only in a fork. The check tries, in order: the recorded ref, then the default branch, then every branch and tag. It fetches commits only, using --filter=tree:0.

Docs: docs/cli-reference.md (the skillx add section, lock, update and sync, runtimes and scope, the installer usage lines, and the lockfile added field).

Decisions

• The lock is written by default, the same as install. --no-lock skips it.
  • CLIs older than this change will reject a lock that contains added entries. The docs say so.
• Uninstalling for one runtime drops the lock entry, which matches how registry packages already behave.

Review

I ran two isolated subagent reviews.

• The first found 1 blocker, 3 major and several minor issues. All are fixed:
  • project symlink escape;
  • update picking the skill by name;
  • imposter commits;
  • update stopping at the first failing source;
  • plus the minors.
• The second found 1 major issue (a local add removed lock pins it had not replaced) and some minor issues. All are fixed.

Verification

• pnpm typecheck passes for every workspace.
• pnpm test: 156 files, 2884 passed, 3 skipped.
  • One timing test in apps/web, proposal-detector-cost, failed once while another test run was using the CPU. It passes when run alone and is unrelated to this change.
• New tests are in add-lock-refresh.test.ts, add-update-safety.test.ts and install-lock.test.ts. They cover:
  • commits behind the tip, on a side branch, and on an annotated tag;
  • a loose (fork-like) commit being refused;
  • a remote with no HEAD;
  • symlinked .claude and skills directories;
  • partial update;
  • pin handling.
• Live end-to-end runs of the built CLI against anthropics/skills:
  • add at a non-tip commit with --project into claude-code and codex;
  • an added entry written to the lock;
  • sync --locked restoring the skill after its state was wiped, including through a followed @main ref;
  • update --project;
  • list --project;
  • a symlinked .claude refused with conflict;
  • an unknown commit reported as not_found;
  • a tampered digest reported as integrity_error.

---

Generated by Claude Code