skill-deployment

Skill Deployment via chezmoi

Authored skills (ONE tree): repo src/personal_os_setup/config/chezmoi/dot_claude/skills/ → ~/.claude/skills (Claude Code + Hermes external_dirs). Desktops: TUI dotfiles tab. Container/CLI:

REPO=/config/workspace/personal-os-setup
cd ~ && chezmoi apply -v --force --source "$REPO" .claude    # deploy ONLY the skills

Scope: repo-specific skills are NOT deployed here — they live in .claude/skills/ + .agents/skills/ (make skills-link / make skills-check; see the skill-layout skill).

Repo-scoped skills (<repo>/.hermes/skills + .agents/skills) load only when the session's working dir resolves to the repo's git root and that root is in skills.trusted_project_dirs. A session rooted at HOME (global terminal.cwd) resolves no repo, so nothing loads — upstream Hermes bug #103423, fix in review as PR #103424. Never park repo skills in external_dirs (N repos × M skills doesn't scale): promote a repo's skills to the global tree if they must be always-on, otherwise they're read on demand.

Loading internals: agent-skills-architecture → "What actually loads".

No chezmoi (HA container/CLI): cd <repo> && make skills-deploy — copies the same source to ~/.claude/skills. The make target lives in makefiles/skills.mk (same file as skills-link/skills-check).

Rules: --source = repo ROOT (git-backed, .chezmoiroot points at the nested dir — never the nested dir); run from HOME (targets resolve against CWD).

⚠️ The nested config/chezmoi dir must never contain its own .chezmoiroot: the app (src/personal_os_setup/tasks/system/chezmoi.py) passes that dir directly as --source, so a nested .chezmoiroot would double-redirect and break the app's deploy path.

Refresh after git pull. On the container deploy only .claude: the package source also holds the desktop config (dot_config/hypr, ghostty, mpv, OpenRGB, coolercontrol, mimeapps…), and /config/.claude/ also holds Claude Code's own credentials/sessions — deploy into the skills/ subdir only.

File-level fallback (source dir is not a git repo): --source-path with ABSOLUTE source paths works on any dir.

S=/config/workspace/personal-os-setup/src/personal_os_setup/config/chezmoi
chezmoi --source "$S" apply -v --force --parent-dirs --refresh-externals=never \
  --source-path "$S/dot_claude/skills/<name>/SKILL.md"

• If it hangs mid-apply with --parent-dirs, retry the missing file alone without it (the dirs already exist).
• chezmoi managed --source "$S" lists entries (live scan); chezmoi cat/apply <target> use target resolution, which is what fails on a non-git source. Idempotent: re-run for the skills a git pull changed.
• The TUI (tasks/system/chezmoi.py) runs the same flags with chezmoi_source_dir() as --source.

Pin the deployed names against the Curator per machine after each deploy: hermes curator pin <skill> (unpin/status/run/pause/list-unmanaged also exist).

Sync direction — repo → live, one way. The repo copy is the truth; make skills-deploy is copy-only: it overwrites whatever is live and deletes nothing.

• Never deploy a skill that already lives elsewhere in the repo and is symlinked into the store (e.g. a docs/...-hosted one): cp -R follows the symlink and writes through it into the tracked source. Keep the symlink, don't duplicate the directory.

Drift: make skills-diff (read-only; non-zero on MISSING/DIFFERS), make skills-status, make skills-drift (the deploy's gate: only a DIFFERS aborts). Override with make skills-deploy SKILLS_FORCE=1 only after porting the live edit into the repo — see references/deploy-drift-and-reconciliation.md. Save a live skill: make skills-keep NAME=<name>.