lifeich1/nixcf / .agents/skills/nixcf-module-change
nixcf-module-change
VerifiedImplement and review scoped NixOS or Home Manager module changes in the nixcf repository. Use when adding a reusable module, changing a `fool.*` option, wiring imports, enabling a feature for a host or Home profile, moving shared logic out of host/profile files, or updating the corresponding module documentation.
nixcf Module Change
Route each change through the repository's host/profile/module graph, keep machine selection separate from reusable implementation, and validate every affected configuration.
Inspect Before Editing
- Work from the repository root and inspect
git status --short. Preserve unrelated user changes and do not reformat or revert them. - Read
README.mdandflake.nix. Derive the current host names, architectures, usernames, Home profiles, module arguments, and import graph from source rather than memory. - Before opening a potential credential source, run
.agents/skills/nixcf-secrets-agenix/scripts/check-nix-source-safety.sh. If blocked, treat every reported path as opaque and continue only with path/status metadata and permitted sources. - Read the
readme.mdin the target directory and its parent. Open only the target host/profile and modules implicated by the request and permitted by the source-safety gate. - Trace the option definition, every enablement site, and any shared dependency before deciding where to edit. When changing proxy behavior, inspect both the user and system definitions of
fool.proxyonly when the gate permits their sources; otherwise report the blocked dependency. - Identify the affected
nixosConfigurationsand architectures. Pay particular attention to external packages and overlays reachable byaarch64-linuxhosts.
Ask the user only when the target host/profile or the intended sharing boundary cannot be inferred and the alternatives would materially change behavior on different machines. Otherwise, make the narrowest source-backed assumption and state it.
Route the Change
| Concern | Location | Rule |
|---|---|---|
| Machine-specific system or hardware selection | host/<hostname>/ | Keep only host differences and system feature switches here. |
| Profile-specific user feature selection | home/<profile>/ | Enable Home Manager features here; do not implement reusable modules here. |
| Reusable NixOS behavior | os/<name>/ | Define system options and guarded configuration here. |
| Reusable Home Manager behavior | fool/<name>/ | Put options under the fool.* namespace and guard configuration here. |
| Packages exposed from flake inputs | os/<name>/ or fool/<name>/ package option | Injected at the enablement site; confirm every affected architecture has the required output. |
Move behavior used by multiple hosts or profiles into os/ or fool/ instead of copying it. Keep a one-host implementation local only when it is intrinsically machine-specific.
Implement the Module
- Add or update
default.nixin the selected reusable module directory. - Declare an explicit option under
fool.<name>and uselib.mkIforlib.mkMergeto make opt-in behavior clear. Reuse existing repository conventions instead of introducing a second namespace or enablement pattern. - Import a new reusable module from
os/default.nixorfool/default.nix. Preserve explicit exceptional imports inflake.nixunless the task specifically requires changing that architecture. - Enable the option from the relevant
host/<hostname>/configuration.nix,home/<profile>/default.nix, or an existing shared profile such ashome/desktop-common.nix. - Update the new module's
readme.mdand every affected parent or profilereadme.mdwhose routing, options, dependencies, or enabled feature list changed. Describe current source behavior, not intended future work. - Re-read the complete diff to catch duplicate imports, unconditional configuration, misplaced host choices, and accidental edits outside scope.
Respect Guardrails
- Do not modify
hardware-configuration.nixunless the request explicitly concerns hardware changes. - Do not change
system.stateVersionorhome.stateVersionas part of a module or input upgrade. - Do not update flake inputs or
flake.lock, deploy, create tags, or commit unless the user explicitly authorizes that action. - Do not decrypt, print, copy, or move secret plaintext. If a module needs a credential, use the repository's Agenix declarations and runtime paths without exposing values.
- Treat
os/nixcache settings and the Pi Attic service as coupled. While the source-safety gate is blocked, keep any reported credential source opaque and do not attempt to inspect its netrc producer; report that the coupled change cannot yet be completed safely.
Validate and Report
Run validation in proportion to the change:
- Run
git diff --checkfor every change, including documentation-only work. - Before any repo-consuming Nix command, run
.agents/skills/nixcf-secrets-agenix/scripts/check-nix-source-safety.sh. Stop and report its path/category-only output if blocked; do not open reported sources or bypass it with a narrower attribute. - Run
just chkfor Nix configuration changes only after the source-safety gate succeeds. Do not substitute a deployment command for local validation. - If validation cannot complete because of the environment or the source-safety gate, report the exact command, failure, and unverified configurations. Do not claim success from partial evaluation.
- Summarize changed files, routing decisions, affected hosts and architectures, completed checks, and any remaining manual or runtime verification. Mention explicitly that no deployment occurred.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |