feat: add global-placement home-manager module (task 0002) #2

alexion · 2026-07-22T17:19:07-04:00

alexion commented

2026-07-22 17:19:07 -04:00

Task: .claude/tasks/0002-global-placement-home-manager.md

Summary

Adds the global (every-project) placement output: a home-manager module that installs an operator's selected skills into ~/.claude/skills/, plus the composition check that proves it.

homeModules.default (aliased agents-skills) exposes programs.agents.skills, a listOf package defaulting to []. Selection is by derivation, pulled from packages.<system>.
For each selected skill the module writes an individual home.file at ${claude-code.configDir}/skills/<name> with recursive = true, gated on programs.claude-code.enable, sourcing configDir from the claude-code module. The placement name is the derivation's eval-time skillName passthru (no import-from-derivation). It deliberately does not feed the single-valued programs.claude-code.skills.
agents is an umbrella namespace with no shared enable; the skills feature self-gates (empty list is a no-op, files land only with Claude Code enabled).
A new nix flake check composition check builds the home-files tree under five operator configurations and asserts placement, recursive linkage, the enable gate, configDir sourcing, and coexistence with an operator's own attribute-set and whole-directory skills.
Adds a home-manager flake input following this flake's nixpkgs, present only to drive the check.

Deviations

homeModules also exposes an agents-skills alias beside default (the criteria require only default), mirroring gitea-axi's module shape.
A non-default configDir scenario was added to the check during review, so the "configDir sourcing" leg is actually exercised rather than passing at the default .claude alongside a hardcode.

Review

Risk

Overall: Medium

Blast radius — Medium: Adds a new home-manager module, a new flake input, and a new check; touches flake.nix/flake.lock, but consumers only import the module opt-in and nothing existing is rewired.
Reversibility — Low: All additive (new files + new outputs); homeModules.default is a newly published surface but trivial to drop with no migration or deletion.
Test coverage — Low: The diff itself is a substantial composition check that builds the home-files tree under five configurations and asserts on placement, gating, and recursive linkage.
Sensitive domain — Low: No auth, secrets, payments, or data migration; only places skill files under ~/.claude/skills/, gated behind claude-code.enable.
Size & complexity — Medium: ~230 new lines; the module logic is a small mkIf/listToAttrs map, but the check harness and its store-path-vs-attr-set nuances add cognitive load.
Runtime criticality — Low: Dev-only tooling that provisions an agent's skills directory; not a production hot path.

Unaddressed findings

Standards

Duplicated runCommandLocal + printf … > SKILL.md fixture shape appears three times in checks/home-manager-module.nix (judgement call). Left as-is: each fixture plays a distinct role and a shared helper would obscure that; the reviewer rated it acceptable.

Spec

The agents-skills alias beside homeModules.default is beyond the bare task text (scope). Kept intentionally as a harmless convenience mirroring gitea-axi; the reviewer found no material creep.

Task: `.claude/tasks/0002-global-placement-home-manager.md` ## Summary Adds the global (every-project) placement output: a home-manager module that installs an operator's selected skills into `~/.claude/skills/`, plus the composition check that proves it. - `homeModules.default` (aliased `agents-skills`) exposes `programs.agents.skills`, a `listOf package` defaulting to `[]`. Selection is by derivation, pulled from `packages.<system>`. - For each selected skill the module writes an individual `home.file` at `${claude-code.configDir}/skills/<name>` with `recursive = true`, gated on `programs.claude-code.enable`, sourcing `configDir` from the claude-code module. The placement name is the derivation's eval-time `skillName` passthru (no import-from-derivation). It deliberately does not feed the single-valued `programs.claude-code.skills`. - `agents` is an umbrella namespace with no shared `enable`; the skills feature self-gates (empty list is a no-op, files land only with Claude Code enabled). - A new `nix flake check` composition check builds the home-files tree under five operator configurations and asserts placement, recursive linkage, the enable gate, `configDir` sourcing, and coexistence with an operator's own attribute-set and whole-directory skills. - Adds a `home-manager` flake input following this flake's nixpkgs, present only to drive the check. ### Deviations - `homeModules` also exposes an `agents-skills` alias beside `default` (the criteria require only `default`), mirroring gitea-axi's module shape. - A non-default `configDir` scenario was added to the check during review, so the "configDir sourcing" leg is actually exercised rather than passing at the default `.claude` alongside a hardcode. ## Review ### Risk **Overall: Medium** - Blast radius — Medium: Adds a new home-manager module, a new flake input, and a new check; touches `flake.nix`/`flake.lock`, but consumers only import the module opt-in and nothing existing is rewired. - Reversibility — Low: All additive (new files + new outputs); `homeModules.default` is a newly published surface but trivial to drop with no migration or deletion. - Test coverage — Low: The diff itself is a substantial composition check that builds the home-files tree under five configurations and asserts on placement, gating, and recursive linkage. - Sensitive domain — Low: No auth, secrets, payments, or data migration; only places skill files under `~/.claude/skills/`, gated behind `claude-code.enable`. - Size & complexity — Medium: ~230 new lines; the module logic is a small `mkIf`/`listToAttrs` map, but the check harness and its store-path-vs-attr-set nuances add cognitive load. - Runtime criticality — Low: Dev-only tooling that provisions an agent's skills directory; not a production hot path. ### Unaddressed findings **Standards** - Duplicated `runCommandLocal` + `printf … > SKILL.md` fixture shape appears three times in `checks/home-manager-module.nix` (judgement call). Left as-is: each fixture plays a distinct role and a shared helper would obscure that; the reviewer rated it acceptable. **Spec** - The `agents-skills` alias beside `homeModules.default` is beyond the bare task text (scope). Kept intentionally as a harmless convenience mirroring gitea-axi; the reviewer found no material creep.

alexion added 1 commit 2026-07-22 17:19:08 -04:00

feat: add global-placement home-manager module (task 0002) b0a763e5ce

Expose homeModules.default, a home-manager module whose programs.agents.skills
option places operator-selected skill derivations into Claude Code's skills
directory, one recursive home.file per skill, gated on programs.claude-code.enable
and sourcing configDir from the claude-code module. Add a nix flake check that
builds the home-files tree under several operator configurations and asserts
placement, recursion, the enable gate, configDir sourcing, and coexistence with
an operator's own skills.

alexion merged commit b0a763e5ce into main

2026-07-22 22:09:28 -04:00

alexion deleted branch task-0002-global-placement-home-manager

2026-07-22 22:09:28 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: alexion/skills#2