New Module Agent Skill

Create a new flake-parts module for planetscale/nix-devshell. Use when adding a new language toolchain module, team module, or any new shared devShell module to this repository.

676 tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/planetscale/nix-devshell --skill new-module

The instruction itself

8 sections, as written by the author

Creating a New nix-devshell Module

Checklist

Create modules/<name>.nix
Export it in flake.nix under flake.flakeModules
If adding a team module, place it in modules/teams/<name>.nix

Module Template

Needs `mattware` (Go versions, Zig tools, etc.)

{ mattware }: { lib, ... }: {
  perSystem =
    { system, pkgs, config, ... }:
    {
      options = {
        nix-devshell.<name>.package = lib.mkOption {
          type = lib.types.package;
          default = mattware.packages.${system}.<package>;
          defaultText = lib.literalExpression "mattware.packages.\${system}.<package>";
        };
      };

      config = {
        devShells.<name> = pkgs.mkShell {
          packages = [
            config.nix-devshell.<name>.package
            pkgs.<tool1>
            pkgs.<tool2>
          ];
        };
      };
    };
}

Only needs nixpkgs (no mattware)

{ lib, ... }: {
  perSystem =
    { pkgs, config, ... }:
    {
      devShells.<name> = pkgs.mkShell {
        packages = with pkgs; [ <tool1> <tool2> ];
      };
    };
}

Team module (wraps base + adds team tools)

{ baseModule }: { ... }: {
  imports = [ baseModule ];

  perSystem =
    { pkgs, config, ... }:
    {
      devShells.<teamName> = pkgs.mkShell {
        inputsFrom = [ config.devShells.base ];
        packages = with pkgs; [ just <team-tools> ];
      };
    };
}

Exporting in flake.nix

In the flake.flakeModules attrset:

# No nix-devshell inputs needed — direct path
<name> = ./modules/<name>.nix;

# Needs mattware — use importApply
<name> = importApply ./modules/<name>.nix withMattware;

# Team module needing baseModule
<teamName> = importApply ./modules/teams/<teamName>.nix {
  baseModule = ./modules/base.nix;
};

withMattware is already defined in flake.nix as { inherit (inputs) mattware; }.

Key Rules

Use importApply whenever the module needs anything from *this* flake's inputs (mattware). Without it, inputs inside the module refers to the *consumer's* inputs — mattware won't be there.
Options go under nix-devshell.<name>.* namespace.
Include defaultText on any lib.mkOption that uses ${system} interpolation (for documentation).
Do not set systems in language modules — only base sets systems (via lib.mkDefault).
Team modules should use inputsFrom = [ config.devShells.base ] rather than re-importing base directly, to avoid double-import issues.

How to use it

Copy the folder

Take planetscale/new-module from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.