ekapkgs-repo
Skill1 starsChanged 9 months agoMITView on GitHub
Scaffold a new ekapkgs-style Nix package repository. Use when creating a satellite repo that plugs into ekapkgs — covers flake.nix, pins.nix, default.nix, pkgs-module.nix, top-level.nix, CI eval/lint, and GitHub Actions.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- cmakeSkill
- ekala-cmake-nixSkill
- goSkill
- mesonSkill
- mk-many-variantsSkill
- nix-buildSkill
- nix-evalSkill
- packagingSkill
- portingSkill
- pythonSkill
- rustSkill
- structured-attrsSkill
- validationSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 68
If the repo will be imported *into* ekapkgs as a non-flake input (like python-pkgs, haskell-pkgs, etc.), use corepkgs directly:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Creating an ekapkgs-style Repository
This guide covers the files needed to create a new Nix package repository that integrates with the Ekala ecosystem. The primary input is ekapkgs. In rare cases where the repo is meant to be consumed by ekapkgs (a satellite repo), use corepkgs as the input instead.
Required Files
my-repo/
├── flake.nix
├── flake.lock # Generated by `nix flake update`
├── default.nix # Flake-free entry point
├── pins.nix # Reads flake.lock for non-flake usage
├── pkgs-module.nix # Exposes overlays for downstream
├── top-level.nix # Aliases and overrides (final: prev:)
├── pkgs/ # Package expressions (auto-registered)
├── ci/
│ ├── eval.nix # Evaluates every package
│ ├── eval.sh # Shell wrapper for CI
│ └── packages.nix # Enumerates packages, probe logic
├── .github/
│ └── workflows/
│ └── nix.yml # Lint + eval jobs
├── .gitignore
└── LICENSEflake.nix
Most repos take ekapkgs as their single input. Follow the systems input from
ekapkgs for forAllSystems.
{
description = "My package set";
inputs = {
ekapkgs.url = "github:ekala-project/ekapkgs";
systems.follows = "ekapkgs/corepkgs/systems";
};
outputs =
{ ekapkgs, self, systems, ... }:
let
forAllSystems = ekapkgs.lib.genAttrs (import systems);
in
{
legacyPackages = forAllSystems (
system:
import ./. {
inherit system;
modules = [ (import ./pkgs-module.nix) ];
}
);
};
}Satellite repo consumed by ekapkgs
If the repo will be imported into ekapkgs as a non-flake input (like
python-pkgs, haskell-pkgs, etc.), use corepkgs directly:
{
description = "Satellite package set for ekapkgs";
inputs = {
corepkgs.url = "github:ekala-project/corepkgs";
systems.follows = "corepkgs/systems";
};
outputs =
{ corepkgs, self, systems, ... }:
let
forAllSystems = corepkgs.lib.genAttrs (import systems);
in
{
legacyPackages = forAllSystems (
system:
import ./. {
inherit system;
modules = [ (import ./pkgs-module.nix) ];
}
);
};
}Satellite repos set flake = false in the consuming flake so they are imported
as plain source trees via pins.nix, not as flake outputs.
pins.nix
Reads flake.lock so the repo can be imported without the flake evaluator.
List every input you need.
let
lock = builtins.fromJSON (builtins.readFile ./flake.lock);
getInfo =
attr:
let
node = lock.nodes.${attr}.locked;
in
if node.type == "path" then
builtins.fetchTree {
inherit (node) type path narHash;
}
else
builtins.fetchTree {
inherit (node)
type
owner
repo
narHash
rev
;
};
in
{
ekapkgs = getInfo "ekapkgs";
}For satellite repos, replace ekapkgs with corepkgs:
{
corepkgs = getInfo "corepkgs";
}default.nix
Flake-free entry point. Imports the upstream package set and applies local modules.
let
pins = import ./pins.nix;
upstream = import pins.ekapkgs;
pkgsModule = import ./pkgs-module.nix;
in
{
modules ? [ ],
...
}@args:
let
filteredAttrs = builtins.removeAttrs args [ "modules" ];
in
upstream (
{
modules = modules ++ [ pkgsModule ];
}
// filteredAttrs
)For satellite repos importing corepkgs:
let
pins = import ./pins.nix;
upstream = import pins.corepkgs;
pkgsModule = import ./pkgs-module.nix;
in
# ...same patternpkgs-module.nix
Exposes overlays for downstream consumption. Uses
lib.packageSets.mkAutoCalledPackageDir to auto-register packages from the
pkgs/ directory.
{ lib, config, ... }:
let
pkgsOverlay = lib.packageSets.mkAutoCalledPackageDir ./pkgs;
pkgsOverrides = import ./top-level.nix;
in
{
overlays.pkgs = [
pkgsOverlay
pkgsOverrides
];
}top-level.nix
Overlay for aliases, variant wrappers, and overrides that cannot be expressed as
a plain callPackage. Starts minimal.
final: prev: {
# Aliases and overrides go here
}ci/packages.nix
Enumerates every package for evaluation. Disables aliases to avoid redundant
work. Provides a probe function that forces drvPath to catch real errors.
{
checkMeta ? false,
}:
let
pkgs = import ../. {
config = {
inherit checkMeta;
aliases.nixpkgs = false;
handleEvalIssue =
reason: msg:
if
builtins.elem reason [
"unknown-meta"
"broken-outputs"
]
then
abort msg
else
throw msg;
};
};
inherit (pkgs) lib;
probe =
package:
let
value = builtins.tryEval package;
in
builtins.tryEval (
if value.success && lib.isDerivation value.value then
builtins.seq value.value.drvPath null
else
null
);
isBuildable =
value:
let
result = builtins.tryEval (lib.isDerivation value && builtins.seq value.drvPath true);
in
result.success && result.value;
names = builtins.attrNames pkgs;
topLevel = map (name: {
inherit name;
value = pkgs.${name};
}) names;
targets = map (pair: pair.value) topLevel;
in
{
inherit probe targets;
buildable = builtins.listToAttrs (builtins.filter (pair: isBuildable pair.value) topLevel);
}ci/eval.nix
Drives the evaluation. Forces every package and reports the count.
let
packages = import ./packages.nix { };
inherit (packages) probe targets;
in
builtins.deepSeq (map probe targets) {
evaluated = builtins.length targets;
}ci/eval.sh
Shell wrapper for CI. Fails on evaluation errors and Nix warnings.
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
stderr="$(mktemp)"
trap 'rm -f "$stderr"' EXIT
if ! result="$(nix-instantiate --eval --strict --json ci/eval.nix --show-trace 2>"$stderr")"; then
cat "$stderr" >&2
exit 1
fi
if grep -q '^warning:' "$stderr"; then
cat "$stderr" >&2
echo
echo "Evaluation emitted the warnings above; fix them or the job stays red."
exit 1
fi
count="$(sed -E 's/.*"evaluated":([0-9]+).*/\1/' <<<"$result")"
echo "All $count packages evaluate."Make it executable: chmod +x ci/eval.sh
.github/workflows/nix.yml
Two jobs: lint (format check) and eval (evaluate all packages).
name: Nix
on:
push:
branches: [ master ]
pull_request:
branches: [ master ]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v30
with:
extra_nix_config: |
extra-substituters = https://ekala-corepkgs.cachix.org
extra-trusted-public-keys = ekala-corepkgs.cachix.org-1:DcZV+vegWoEzacbSdXFXU4S7728C0eS9RfGpKeyHd6w=
- name: Nix Lint
run: nix fmt . -- --ci
eval:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v30
with:
extra_nix_config: |
extra-substituters = https://ekala-corepkgs.cachix.org
extra-trusted-public-keys = ekala-corepkgs.cachix.org-1:DcZV+vegWoEzacbSdXFXU4S7728C0eS9RfGpKeyHd6w=
- name: Evaluate all packages
run: ./ci/eval.sh.gitignore
result*Checklist
flake.nixwith ekapkgs (or corepkgs) as inputpins.nixmirrors flake inputsdefault.niximports upstream and appliespkgs-module.nixpkgs-module.nixregisterspkgs/viamkAutoCalledPackageDirtop-level.nixexists (can be empty overlay)ci/eval.sh,ci/eval.nix,ci/packages.nixin place.github/workflows/nix.ymlwith lint + eval jobsnix flake updateto generateflake.lock./ci/eval.shpasses locally
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

