feat: link agent skills into environments on activation

[joahg]

What

Environments can declare agent skills — SKILL.md directories used by AI coding agents (the .agents/skills / .claude/skills ecosystem conventions) — in bin/hermit.hcl, and Hermit provides them to the project the same way it provides toolchains:

skill-repo "https://github.com/org/repo.git" {
  path   = "skills"
  skills = ["my-skill"]
  # ref  = "<full commit sha>"   # optional security pin
}

On activation (both the activate command and hermit env --activate) each repository is resolved to a commit — the pinned SHA, or the remote HEAD re-checked at most every 15 minutes — and each declared skill is materialised as an immutable, content-addressed snapshot under the Hermit state directory, then symlinked into .agents/skills/<name> and .claude/skills/<name>.

Why

Today skills must be copied into every repository that wants them, and they drift. Declaring them in the environment gives every workflow that enters the project — humans, CI, coding agents — the same skills, with one committed line of provenance and no vendored content.

Design notes

• Snapshots, not live checkouts. Project symlinks only ever point at immutable <state>/agent-skills/snapshots/<name>@<sha12>/ directories, never at a mutable checkout, so an update can never swap content under a running agent. Snapshot creation is atomic (temp dir + rename) and serialized by a file lock.
• Persistent, activation-reconciled links. Like bin/ toolchain links, skill links persist; discovery is cwd-scoped so leaving the project "unloads" them. Reconciliation uses a per-environment ownership ledger: links Hermit created are updated/removed to match the declaration; repo-committed skill directories and foreign symlinks are never touched.
• Never blocks the shell. Remote resolution is bounded by a 10s timeout and a 15-minute freshness window; when offline, activation degrades to the last good snapshot with a warning. Skill failures warn rather than fail activation.
• Trust posture. Skill names are validated (^[a-z0-9][a-z0-9-]{0,63}$), path cannot escape the repository, symlinked skill paths that resolve outside the checkout are rejected, symlinks inside skill content are not copied, and ref pins must be full commit SHAs. Skill content never enters the project's version control; Hermit warns when the link directories are not gitignored.

Testing

• go test ./... green; new agentskills package has unit coverage for linking, reconciliation, precedence (repo-committed skills win), pinned refs, HEAD updates, freshness window, offline fallback, failed-repo link preservation, and symlink-escape rejection.

[alecthomas]

This is definitely too specific to be in Hermit, but I'm interested in generalised solutions for the same pattern.

I think you could do the same by using on activate. You'd create an agent-skills package pointing at a git repo (already supported), with an on activate {...}  block that copies/symlinks the skills into the repo.

So I think all the pieces are already there, but give it a shot and see how it goes.

[joahg]

Gave the composition a shot with stock Hermit built from master — it works end to end: an env-local packages/agent-skills.hcl (git channel source with update = "15m", on activate symlinks) plus install-on-activate, and a fresh machine gets skills in one activation, channel refresh keeps them current, and offline degrades gracefully.

Five rough edges surfaced, all generic rather than skills-specific:

1. validation rejects content-only packages (no binaries or apps provided), so a skills package needs a noop binary on PATH
2. the symlink action isn't idempotent — second activation fails with file exists (its String() already advertises ln -sf); worked around with a recursive delete first, which relies on the undocumented action-type ordering in Trigger.Ordered
3. channel update is only checked on stub exec, and a content package's binary is never exec'd, so it never refreshes — checking channels for install-on-activate packages during activation would fix it
4. hermit env --activate doesn't run install-on-activate or activate triggers, so CI/non-shell flows don't get the links
5. #ref maps to git clone --branch, so tags/branches can be pinned but not commit SHAs

Sending these as separate small PRs.

[joahg]

🤖 Sent by Joah's AI agent:

Follow-up PRs from the composition experiment above, each a small generic fix rather than anything skills-specific:

• Allow packages without binaries or apps when they provide trigger actions or env vars #598 — allow content-only packages (trigger actions or env vars instead of a mandatory binary)
• Make the symlink action idempotent, matching its advertised ln -sf semantics #599 — make the symlink action idempotent (ln -sf semantics, as advertised)
• Check channel freshness for install-on-activate packages during activation #600 — check channel freshness for install-on-activate packages during activation
• Run the full activation lifecycle in 'hermit env --activate' #601 — run the full activation lifecycle in hermit env --activate
• Support pinning git package sources to a full commit SHA #602 — support pinning git sources to a full commit SHA

With those five, the agent-skills pattern works as a pure manifest convention on stock Hermit: a content-only package with a git channel source (update = "15m"), on activate symlinks into .agents/skills/.claude/skills, and install-on-activate.

[joahg]

🤖 Sent by Joah's AI agent:

@alecthomas the five PRs above (#598–#602) are ready for your review whenever you have a chance — each is small, independent, and generic (no skills-specific behavior).