ekala-project/corepkgs / .agents/skills/best-practices
best-practices
VerifiedReview a package expression for best-practices compliance. Use when reviewing PRs or auditing existing packages — checks meta completeness, build-system idioms (cmakeEntries, mesonEntries, pyproject), dependency placement, and packaging conventions.
Best Practices Review
Review a Nix package expression and report violations. Read the package file(s), then check every rule below. Report each finding with the line number and a short explanation.
Meta Attributes
Required Fields
Every package must have all three:
| Field | What to check |
|---|---|
meta.description | Present, non-empty, does not repeat the package name verbatim |
meta.license | Present, uses lib.licenses.* (not a raw string) |
meta.platforms | Present, uses lib.platforms.* |
Recommended Fields
Flag as "recommended" (not error) if missing:
meta.homepage— upstream project URLmeta.mainProgram— for packages that install a binary
Forbidden Fields
Flag as error if present:
meta.maintainersormeta.teams— not a recognised key; failscheck-meta
Build-System Idioms
CMake
- If
cmakeEntries,cmakeFlags, orcmakeBuildTypeare used,cmake.configurePhaseHookmust be innativeBuildInputs. (Some builds use cmake as a dependency without the configure phase hook — that is fine.) - Prefer
cmakeEntries(attrset) overcmakeFlags(string list) for-Dflags. FlagcmakeFlagswith-Dentries as "prefer cmakeEntries".
Meson
- If
mesonEntries,mesonFlags, ormesonFeaturesare used,meson.configurePhaseHookmust be innativeBuildInputs. ninjamust be innativeBuildInputswhenmeson.configurePhaseHookis present.- Prefer
mesonEntriesovermesonFlagsfor-Doptions. FlagmesonFlagswith-Dentries as "prefer mesonEntries". - Prefer
mesonFeaturesfor feature-type options (enabled/disabled/auto).
Python
When using buildPythonPackage:
pyproject = trueshould be set (flag legacyformat =as "prefer pyproject")build-systemshould be present whenpyproject = truepythonImportsCheckis recommended
Rust
When using buildRustPackage:
cargoHashmust be presentmeta.mainProgramis recommended for binary crates
Go
When using buildGoModule:
vendorHashmust be presentmeta.mainProgramis recommended for CLI tools
Packaging Conventions
Structural
- Use
finalAttrspattern — flagrec {as "prefer finalAttrs" - Do not set
__structuredAttrs = true— it is the default - Do not set
doCheck = falseordoInstallCheck = false— they are defaults - Do not set
meta.maintainersormeta.teams - Avoid
placeholderif possible — prefer shell output references for better content-addressed derivation support. E.g."PREFIX=${placeholder "out"}"→"PREFIX=$(out)"
Formatting
- Attributes inside a derivation block (e.g.
mkDerivation) should be separated by an empty line between each attribute - Exception:
pname,version,extensions,pyproject, anddisabledmay be grouped together without blank lines
Dependencies
- Build tools (compilers, code generators, pkg-config) belong in
nativeBuildInputs, notbuildInputs - Libraries belong in
buildInputs, notnativeBuildInputs - Test-only deps belong in
checkInputsornativeCheckInputs strictDeps = trueshould be set whendepsBuildBuildis used- In top-level scope, prefer referencing the interpreter's package set over the top-level alias — e.g.
python3.pkgsoverpython3Packages
Sources
- Prefer forge-specific fetchers (
fetchFromGitHub,fetchFromGitLab,fetchFromBitbucket, etc.) for source checkouts — flagfetchzip/fetchurlpointing at a forge source tarball as "prefer fetchFrom*". Fetching uploaded release artifacts (e.g. pre-built binaries, vendored bundles) withfetchzip/fetchurlis acceptable. fetchFromGitHub/fetchFromGitLabshould usetag, notrevwith a tag value- Hash should be SRI format (
sha256-...), not bare hex
Commits
- Each commit should be one logical change
- Fixup commits (
fixup!,squash!, or small corrections to a previous commit in the same PR) should be squashed into the commit they fix before merge - Standalone fixup commits are only acceptable when they address an existing issue in an already-merged commit
Testing
- Prefer
passthru.testsover in-builddoCheck = true - Python packages: prefer
testPathsover manual test phase
Output Format
Group findings by severity:
## Errors
- line 12: missing `cmake.configurePhaseHook` in nativeBuildInputs
- line 30: `meta.maintainers` is forbidden — remove it
## Warnings
- line 8: `cmakeFlags` with -D entries — prefer `cmakeEntries` attrset
- line 25: `doCheck = false` is the default — remove redundant line
## Recommendations
- missing `meta.homepage`
- missing `meta.mainProgram` for binary package
If there are no findings in a severity group, omit that group. If the package is clean, say so.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |