pi-config/skills/nixos-workflow/SKILL.md

name, description, version

name	description	version
nixos-asset-manager	Manage Pi agent assets (extensions, skills, themes, prompts) on NixOS with Gitea synchronization.	1.0.0

NixOS Asset Manager

This skill guides the agent in maintaining a declarative, Gitea-backed configuration for the Pi coding agent on NixOS.

Core Principles

1. Source of Truth: All custom code (extensions), instructions (skills), and UI assets (themes) must be saved in ~/ai-assets.
2. No Direct Nix Store Writes: Never attempt pi install npm:... or global npm install as it fails on NixOS. Always clone sources into ~/ai-assets/extensions and run npm install locally within that folder.
3. Gitea Sync: After any local modification to ~/ai-assets, the agent must commit and push changes to https://audasmedia.com.au.
4. Configuration Layering:
   • Global: Referenced via home.nix in the ~/.pi/agent/settings.json file.
   • Project-Specific: Defined in .pi/settings.json within individual project folders to avoid "bloat."

File Structure Standards

The agent must maintain the following structure in ~/ai-assets:

• extensions/: TypeScript modules (e.g., steel-browser/index.ts).
• skills/: Markdown instructions (e.g., system-architect/SKILL.md).
• themes/: JSON theme definitions.
• prompts/: Markdown slash-command templates.

Workflows

Adding a New Extension

1. Navigate to ~/ai-assets/extensions.
2. Clone the repository: git clone <url> <name>.
3. Remove internal Git tracking to avoid submodules: rm -rf <name>/.git <name>/.gitignore.
4. Install dependencies locally: cd <name> && npm install.
5. Update the project's .pi/settings.json to include "extensions/ <name>/index.ts".
6. Push to Gitea.

Updating a Skill

1. Modify the relevant .md file in ~/ai-assets/skills/.
2. Push to Gitea.
3. The change is live across all NixOS machines upon the next Pi launch.

Managing Settings via Nix

When instructions involve global changes, the agent must remind the user to update the home.file.".pi/agent/settings.json".text block in their Home Manager configuration.

Critical Guardrails

• DO NOT use ~/.agents/skills as it bypasses Gitea version control.
• ALWAYS check for an existing .git folder in new extensions before pushing to Gitea.
• NEVER push auth.json or sessions/ to Gitea.