lifeich1/nixcf / .agents/skills/nixcf-flake-package
nixcf-flake-package
VerifiedSafely add, change, pin, update, or remove flake inputs and external packages in the nixcf NixOS repository. Use for flake.nix or flake.lock changes; nixpkgs channel changes; input follows relationships; packages consumed from an input; module package options; or wiring an external package or module into a host, Home Manager profile, NixOS module, or Home Manager module.
nixcf Flake Packages
Change inputs and external packages without broad lock churn, architecture regressions, or confused ownership between the flake, overlays, modules, and consumers.
Establish the current graph
- Read the repository
AGENTS.md, rootREADME.md, andflake.nixcompletely. Treatflake.nixandflake.lockas truth; do not copy versions or enabled state from prose. - Read the
readme.mdin each affected directory and its parent, then open only the relevant host, profile, module, and overlay sources. - Inspect the existing working-tree diff before editing. Preserve unrelated and pre-existing changes.
- Trace the requested item through all applicable layers:
| Layer | Responsibility |
|---|---|
flake.nix input | Declare source, ref, flake = false, and nested follows relationships. |
flake.lock | Record resolved revisions and the transitive input graph; mutate only with Nix. |
| Flake composition | Pass inputs through module arguments or import an input-provided NixOS/Home Manager module. |
Module package option | Expose a shared external package as a typed package option injected at the enablement site. |
os/ or fool/ module | Implement reusable system or user behavior and declare options. |
host/ or home/ consumer | Select the hosts/profiles that enable or consume the feature. |
Use targeted rg searches for the input name, package attribute, module import, and option. Do not assume an input is unused merely because it is absent from an overlay.
Pass the decision and authorization gate
A direct request to add, change, pin, update, or remove a named input authorizes only the requested flake.nix input change. Mutating flake.lock requires explicit authorization as well: accept an initial request that explicitly includes updating or reconciling the lock, otherwise ask before running the lock command. Research, diagnosis, package recommendations, or an ambiguous request do not authorize either change.
Before editing an input or mutating flake.lock, establish and state:
- the exact input name, source, owner, ref/revision, and whether it is a flake;
- the stability choice, especially
nixpkgsversusnixpkgs-stable; - the exact package/module output and intended integration layer;
- the target hosts/profiles and therefore both required systems;
- the named lock target and expected transitive churn.
Ask an interactive, concise question when any of those decisions is materially ambiguous. Also ask before accepting unexpected lock churn. Use the interactive input mechanism when available; otherwise ask directly. Do not silently choose a source fork, branch, stability channel, output named default, target host, or broader update scope.
Do not treat permission for one input as permission for all-input updates. Never deploy, commit, tag, access secrets, or update unrelated inputs unless explicitly requested.
Choose one package integration path
- Import an input-provided module in flake composition when the upstream output is itself a NixOS or Home Manager module. Preserve its existing
inputs.<name>.followsrelationships unless the requested compatibility change requires otherwise. - Consume
inputs.<name>.packages.${pkgs.stdenv.hostPlatform.system}.<output>directly when one reusable module owns the package and nopkgs.<name>API is needed. - Declare a typed
packageoption in the owningos/<name>/orfool/<name>/module and injectinputs.<name>.packages.${pkgs.stdenv.hostPlatform.system}.<output>at the enablement site. This is the repository's default integration path; the formerfool/overlayspackage-set exposure was removed. Add an overlay only if the request genuinely requires a stable globalpkgs.<name>API, and document the owning option and every consumer. - Treat
flake = falseinputs as source trees, not flakes withpackagesor module outputs. Add an explicit packaging layer only if the request requires one. - Use the existing
pkgs-stablemodule argument only when the chosen stability policy calls for it. Do not create a second ad-hoc nixpkgs import inside a consumer.
Keep reusable logic in os/ or fool/; keep host/profile files to selection. Add imports and update affected readme.md files according to repository conventions.
Protect follows and overlay semantics
Inspect the corresponding lock nodes before changing follows. Retain shared nixpkgs following where it prevents duplicate graphs, and retain deliberately disabled or independent inputs when required by upstream compatibility. Do not add follows merely to reduce the lockfile.
For overlays:
- derive the output system from the target package set, never
builtins.currentSystem; - confirm the exact
packages.<system>.<output>exists for every target system; - use one owner for each
pkgs.<name>attribute and avoid shadowing a nixpkgs attribute accidentally; - avoid
final.<same-name>self-reference and recursive nixpkgs imports; - use
finalonly for dependencies that should see the composed overlays, andprevfor the pre-overlay package set; - verify unfree policy in the applicable package-set import rather than assuming it globally applies.
Reconcile the lockfile narrowly
- Run
.agents/skills/nixcf-secrets-agenix/scripts/check-nix-source-safety.shbefore any repo-consuming Nix command. Stop on a nonzero result; do not open reported sources or bypass the gate with a narrower update/evaluation. - Read the installed Nix version and the local help for
nix flake updateandnix flake lockimmediately before choosing a command. Their experimental CLI has changed; do not reuse deprecated forms from memory. Commands that only display installed-version or CLI help may run before the source-safety gate because they do not consume the repository. - Prefer the current supported named-input update form for an existing input. For a newly declared or removed input, use the currently documented lock reconciliation that preserves already-current entries.
- Do not use the repository's all-input update recipe for a targeted change.
- Never hand-edit
flake.lock. - Compare the before/after input graph and
git diff -- flake.nix flake.lock. Allow changes to the named node and explainable transitive nodes only. Stop and ask before keeping unrelated top-level changes or surprising source/ref changes.
If the necessary command will fetch from the network or mutate the lock and the user's request did not explicitly authorize that exact operation, ask first. Do not discard the user's existing lockfile edits to narrow a diff.
Validate by architecture and consumer
Resolve host names, profiles, users, and systems from the current flake.nix. For a shared package, explicitly check both x86_64-linux and the Pi's aarch64-linux; for a host-specific package, check every selected host system.
- Re-run the source-safety gate immediately before validation. If blocked, skip every repo-consuming Nix command and report the unvalidated outputs/hosts.
- Probe the exact input package or module output for each target system. A successful x86 output does not establish Pi availability.
- Evaluate every affected
nixosConfigurations.<host>.config.system.build.toplevel.drvPathwith lock writes disabled. This catches module arguments, overlay exposure, option wiring, package availability, unfree policy, and host/profile consumption. - Run
just chkfor Nix configuration changes, thengit diff --check. - Inspect the final diff for preserved
follows, intended imports and enablement, updated directory documentation, and unrelated lock churn.
Do not deploy as validation. If evaluation or checks cannot run because an input is unavailable, a target architecture lacks an output, the network is unavailable, or approval is absent, report the exact unvalidated host/output and reason instead of weakening the check.
Report the result
Summarize the declared source/ref, package or module output, exposure path, enabled consumers, affected systems, lock nodes changed, and validation performed. Call out any intentional transitive churn, unverified architecture, or follow-up decision.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |