name	create-custom-package
description	Create a new repo-local custom Nix package under packages/, following this flake's package patterns and validation flow.
when_to_use	Use when the user asks to add a new custom package, write a new package.nix, package an upstream tool/app for this repo
allowed-tools	["Bash(nix build )","Bash(nix fmt )"]

Create Custom Package

Add new packages in packages/<name>/package.nix.

packages/default.nix auto-imports every subdirectory containing package.nix, and flake.nix exposes them as packages.<system>.<name>. Do not add manual registry entries for normal package creation.

Workflow

Inspect nearby examples in packages/ before choosing a builder.
Create packages/<name>/package.nix.
Pick the simplest matching pattern:
- buildGoModule for Go projects with modules
- buildNpmPackage for Node packages
- stdenv.mkDerivation for simple binaries, app bundles, or custom installs
- another language-specific builder only when the upstream project clearly needs it
Add mainProgram for CLI tools when there is one clear executable.
Restrict platforms when the package is OS-specific, like lib.platforms.darwin.

Hashes And Build Inputs

Use fetchFromGitHub when the source is a GitHub repo; otherwise choose the narrowest fetcher that fits.
For package hashes use lib.fakeHash, build once (expecting a failure), and replace it with the reported value.

Custom Updaters

When the upstream does not provide a stable source tag or URL pattern, write a custom update script
Attempt to find the release feed via an appcast URL or squirrel feed for Darwin apps. Inspect the app package if necessary (usually the Info.plist)
Prefer writeShellApplication with focused feed parsers like jq or xmllint
Updaters should refresh the package version, source url, and hash together
Ensure the src url's value uses interpolation where possible
Don't set any meta values to the release feed URL
Verify by evaluating, building, and running the updater, then doing package dry-runs

Validation

nix build .#<package-name>

Create Custom Package

Add new packages in packages/<name>/package.nix.

Workflow

Inspect nearby examples in packages/ before choosing a builder.

Create packages/<name>/package.nix.

Pick the simplest matching pattern:

buildGoModule for Go projects with modules
buildNpmPackage for Node packages
stdenv.mkDerivation for simple binaries, app bundles, or custom installs
another language-specific builder only when the upstream project clearly needs it

Add mainProgram for CLI tools when there is one clear executable.

Restrict platforms when the package is OS-specific, like lib.platforms.darwin.

Hashes And Build Inputs

Use fetchFromGitHub when the source is a GitHub repo; otherwise choose the narrowest fetcher that fits.

For package hashes use lib.fakeHash, build once (expecting a failure), and replace it with the reported value.

Custom Updaters

When the upstream does not provide a stable source tag or URL pattern, write a custom update script

Attempt to find the release feed via an appcast URL or squirrel feed for Darwin apps. Inspect the app package if necessary (usually the Info.plist)

Prefer writeShellApplication with focused feed parsers like jq or xmllint

Updaters should refresh the package version, source url, and hash together

Ensure the src url's value uses interpolation where possible

Don't set any meta values to the release feed URL

Verify by evaluating, building, and running the updater, then doing package dry-runs

Validation

nix build .#<package-name>

create-custom-package