Pi Nix Integration Skill

Pi Nix Integration

This skill manages pi packages, extensions, skills, and themes within the nix-darwin system-config project.

Key Difference from Standard Pi

Standard pi workflow: pi install npm:package-name

This project workflow: Pi packages are declared in nix configuration and installed automatically on first pi run.

Architecture

Pi Package Management

Declaration: modules/home-manager/packages/pi.nix
Auto-installation: Packages install on first pi command run
Tracking: Uses pi's native package management but declared in nix
Location: Packages install to ~/.local/lib/node_modules/

Current Integration Method

{pkgs, ...}: let
  piPackages = [
    "pi-prompt-template-model"
    "pi-subagents" 
    "@tmustier/pi-skill-creator"
  ];
  
  installPiPackages = pkgs.writeShellScript "install-pi-packages" ''
    for package in ${toString piPackages}; do
      ${pkgs.nodejs_24}/bin/npx --yes @earendil-works/pi-coding-agent@latest install npm:$package 2>/dev/null || true
    done
  '';
in
pkgs.writeShellScriptBin "pi" ''
  # Ensure pi packages are installed on first run
  if [ ! -f "$HOME/.pi/packages-installed" ]; then
    echo "Installing pi packages..."
    ${installPiPackages}
    touch "$HOME/.pi/packages-installed"
  fi
  
  exec ${pkgs.nodejs_24}/bin/npx --yes @earendil-works/pi-coding-agent@latest "$@"
''

Smart Package Installation

Quick Install Command

Use the project's /pkg-install command for intelligent package management:

/pkg-install package-name

This command will:

Research the package across nixpkgs, homebrew, and pi sources
Determine the optimal installation method
Update the appropriate nix configuration file
Execute the installation automatically

Manual Package Addition

For manual control, follow these steps:

1. Update Nix Configuration

Edit modules/home-manager/packages/pi.nix and add the package name to the piPackages list:

piPackages = [
  "pi-prompt-template-model"
  "pi-subagents" 
  "@tmustier/pi-skill-creator"
  "new-package-name"  # ← Add here
];

2. Apply Changes

sudo darwin-rebuild switch --flake ".#m4-mbp" --impure

3. Trigger Installation

Remove the marker file to force reinstallation:

rm -f ~/.pi/packages-installed
pi list  # This will install all packages including new ones

Local Skills Management

Project-Local Skills

Location: .agents/skills/ (this directory)
Scope: Available only within this project
Priority: Takes precedence over global skills with same name

Creating Local Skills

mkdir -p .agents/skills/my-skill
# Create SKILL.md with proper frontmatter

Global vs Local Skills

Global: ~/.pi/agent/skills/ - available everywhere
Project: .agents/skills/ - available in this project only
Package: skills/ in installed packages

Verification Commands

Check Pi Package Status

pi list                    # List all installed packages
which pi                   # Should show nix-managed path

Check Skill Loading

pi --no-skills            # Start without skills
pi --skill /path/to/skill # Test specific skill
/reload                   # Reload skills after changes

Troubleshooting

Pi Command Not Found After Nix Rebuild

# Clear npx cache if old pi version is cached
rm -rf ~/.npm/_npx
exec $SHELL  # Reload shell

Force Package Reinstallation

rm -f ~/.pi/packages-installed
pi list  # Will reinstall all declared packages

Skill Not Loading

Check frontmatter format in SKILL.md
Verify directory name matches name field
Use /skill:name to invoke explicitly
Check for syntax errors with /reload

Integration Benefits

Declarative: Pi packages declared alongside other system packages Reproducible: Same pi setup across machines using this config Versioned: Pi package list tracked in git Consistent: Follows project's nix-first approach

This approach maintains pi's native package management while gaining nix's reproducibility and declarative configuration benefits.

Agent Skills: Pi Nix Integration

Install this agent skill to your local

Skill Files