Skip to content

ekala-project/corepkgs / .agents/skills/best-practices

best-practices

Verified

Review 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.

FileKindSize
SKILL.mdskill md5.0 KB
---
name: best-practices
description: Review 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 URL
- `meta.mainProgram` — for packages that install a binary

### Forbidden Fields

Flag as error if present:

- `meta.maintainers` or `meta.teams` — not a recognised key; fails `check-meta`

## Build-System Idioms

### CMake

- If `cmakeEntries`, `cmakeFlags`, or `cmakeBuildType` are used, `cmake.configurePhaseHook` **must** be in `nativeBuildInputs`. (Some builds use cmake as a dependency without the configure phase hook — that is fine.)
- Prefer `cmakeEntries` (attrset) over `cmakeFlags` (string list) for `-D` flags. Flag `cmakeFlags` with `-D` entries as "prefer cmakeEntries".

### Meson

- If `mesonEntries`, `mesonFlags`, or `mesonFeatures` are used, `meson.configurePhaseHook` **must** be in `nativeBuildInputs`.
- `ninja` **must** be in `nativeBuildInputs` when `meson.configurePhaseHook` is present.
- Prefer `mesonEntries` over `mesonFlags` for `-D` options. Flag `mesonFlags` with `-D` entries as "prefer mesonEntries".
- Prefer `mesonFeatures` for feature-type options (`enabled`/`disabled`/`auto`).

### Python

When using `buildPythonPackage`:

- `pyproject = true` should be set (flag legacy `format =` as "prefer pyproject")
- `build-system` should be present when `pyproject = true`
- `pythonImportsCheck` is recommended

### Rust

When using `buildRustPackage`:

- `cargoHash` must be present
- `meta.mainProgram` is recommended for binary crates

### Go

When using `buildGoModule`:

- `vendorHash` must be present
- `meta.mainProgram` is recommended for CLI tools

## Packaging Conventions

### Structural

- Use `finalAttrs` pattern — flag `rec {` as "prefer finalAttrs"
- Do **not** set `__structuredAttrs = true` — it is the default
- Do **not** set `doCheck = false` or `doInstallCheck = false` — they are defaults
- Do **not** set `meta.maintainers` or `meta.teams`
- Avoid `placeholder` if 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`, and `disabled` may be grouped together without blank lines

### Dependencies

- Build tools (compilers, code generators, pkg-config) belong in `nativeBuildInputs`, not `buildInputs`
- Libraries belong in `buildInputs`, not `nativeBuildInputs`
- Test-only deps belong in `checkInputs` or `nativeCheckInputs`
- `strictDeps = true` should be set when `depsBuildBuild` is used
- In top-level scope, prefer referencing the interpreter's package set over the top-level alias — e.g. `python3.pkgs` over `python3Packages`

### Sources

- Prefer forge-specific fetchers (`fetchFromGitHub`, `fetchFromGitLab`, `fetchFromBitbucket`, etc.) for source checkouts — flag `fetchzip`/`fetchurl` pointing at a forge source tarball as "prefer fetchFrom*". Fetching uploaded release artifacts (e.g. pre-built binaries, vendored bundles) with `fetchzip`/`fetchurl` is acceptable.
- `fetchFromGitHub`/`fetchFromGitLab` should use `tag`, not `rev` with 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.tests` over in-build `doCheck = true`
- Python packages: prefer `testPaths` over 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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall