name	nix-pinned-package
description	Install and maintain pinned Nix packages from fixed upstream versions in a nix-update-friendly way.
compatibility	opencode
metadata	{"workflow":"nix-update","scope":"repo"}

Pinned Package Workflow

Use This Skill

Use this when the user wants to install something declaratively, but it must stay pinned to a specific upstream version, tarball, AppImage, npm artifact, or similar fixed-output source.

Default Decision Tree

Prefer an existing nixpkgs package.
If none exists, use the smallest reproducible fixed-output derivation.
Keep the package in a standalone file such as packages/<name>.nix.
Expose it as a flake package output if you want nix-update --flake to manage it.
Only fall back to a custom updater when nix-update cannot safely follow the version path.

Package Shape

Keep the derivation explicit: pname, version, source URL, hash, wrapper, and metadata.
Avoid burying package logic inside a NixOS or Home Manager module.
If a module needs the package, import the package file and read passthru fields from the package instead of duplicating version data.

Updateability Rules

Prefer nix-update over hand-editing hashes.
If the source is versioned and machine-readable, add passthru.updateScript.
The update script should fetch upstream release metadata, determine the new version, prefetch the fixed-output hash, and rewrite the package file.
Keep the update script adjacent to the package definition.
Use nix-update --flake --use-update-script <name> when the package is exposed as a flake output.

Unfree Packages

If the package is unfree and exported via flake.packages, make sure the flake pkgs instance allows unfree packages.
Do not rely on the NixOS host config alone.

Verification

Run:

nix build .#<name>
nix run github:Mic92/nix-update -- --flake --use-update-script <name>

Guardrails

Do not use imperative installs like npm -g.
Do not create a one-off update script if nix-update can do the job cleanly.
Ask a short clarification if the source cannot be pinned or updated safely.

Más de este repositorio

mismo repositorio

reference-projects

Vincent-HD/.nixfiles

Workflow for managing and browsing reference projects — cloned third-party repos kept locally in references/ for comparison. Load when the user asks to compare with references, add/update a reference, or look at how other projects handle something. Trigger phrases include "compare with references", "compare with others", "reference projects", "add a reference", "update references", "how do others do".

2026-05-063

noctalia

Vincent-HD/.nixfiles

Compare Noctalia JSON exports against local and upstream defaults before updating `modules/noctalia/noctalia.nix`.

2026-04-273

update-investigation-commands

Vincent-HD/.nixfiles

Maintains `INVESTIGATION_COMMANDS.md` for this nixfiles repo by collecting reusable Nix-centric shell command patterns from the current session, merging duplicates, normalizing commands into reusable templates, and keeping `README.md` linked to the reference. Use when a session in this repo involves meaningful Nix investigation, evaluation, validation, or runtime checks that can recur across multiple tasks.

2026-04-243

Pinned Package Workflow

Use This Skill

Use this when the user wants to install something declaratively, but it must stay pinned to a specific upstream version, tarball, AppImage, npm artifact, or similar fixed-output source.

Default Decision Tree

Prefer an existing nixpkgs package.

If none exists, use the smallest reproducible fixed-output derivation.

Keep the package in a standalone file such as packages/<name>.nix.

Expose it as a flake package output if you want nix-update --flake to manage it.

Only fall back to a custom updater when nix-update cannot safely follow the version path.

Package Shape

Keep the derivation explicit: pname, version, source URL, hash, wrapper, and metadata.

Avoid burying package logic inside a NixOS or Home Manager module.

If a module needs the package, import the package file and read passthru fields from the package instead of duplicating version data.

Updateability Rules

Prefer nix-update over hand-editing hashes.

If the source is versioned and machine-readable, add passthru.updateScript.

The update script should fetch upstream release metadata, determine the new version, prefetch the fixed-output hash, and rewrite the package file.

Keep the update script adjacent to the package definition.

Use nix-update --flake --use-update-script <name> when the package is exposed as a flake output.

Unfree Packages

If the package is unfree and exported via flake.packages, make sure the flake pkgs instance allows unfree packages.

Do not rely on the NixOS host config alone.

Verification

Run:

nix build .#<name>

nix run github:Mic92/nix-update -- --flake --use-update-script <name>

Guardrails

Do not use imperative installs like npm -g.

Do not create a one-off update script if nix-update can do the job cleanly.

Ask a short clarification if the source cannot be pinned or updated safely.