YPares/rigup.nix

rigup is a Nix-based system for packaging knowledge, instructions and skills for your AI agent with the tools and configuration needed to execute them.
A _riglet_ is _executable knowledge_:
- metadata to indicate to your agent what this riglet is for and when it is useful to consult it
- a set of operations, instructions, processes, a.k.a a new Skill for your agent
- the tools (nix packages) needed to execute these instructions
- the configuration for these tools (if any)
By combining the relevant riglets together, you build your agent's _rig_: the tools it needs to work on your project, and the operational knowledge it needs to use those tools properly and efficiently.
By default, the documentation of a riglet is _lazily_ loaded (like Skills are): at startup your agent is fed a manifest, only showing for each riglet a quick description and a set of use cases.
It will then go on reading it when it needs to, or is prompted to.
However, rigup gives you more control than Skills traditionally do in terms of when your agent should be exposed to a riglet's content.
For instance, a fundamental riglet can be set to have an _eager_ disclosure (forcing the agent to see the whole SKILL.md at startup), while another one can have a _shallow-toc_ disclosure (the agent will see a table of contents of the riglet's main SKILL.md).
Besides, while Skills are necessarily fixed files, riglets' documentation files can be produced by any Nix _derivation_. It means the contents can also just be read from a raw file, or they can be defined programmatically, for instance by a bash script. This makes a riglet's doc file contents configurable in the same way this riglet's tools are. rigup's Nix library provides utilities to template your skills via minijinja to facilitate this use case.
rigup has a "knowledge-first" design: documentation is the payload, tools are dependencies. The "main entrance" to the rig will be the RIG.md manifest that rigup will generate for your AI agent to read, and through which it will discover all the available tools, knowledge and processes to follow.
In short, rigup is **parametrable agent skills + lightweight home management** for your agent, with a high-level of interoperability with Skills and Claude plugin marketplaces so reusing existing Skills as riglets or as basis for riglets is made as easy as possible.
Quick start
First, install the rigup CLI tool:
_**NOTE:** On older Nix versions, "add" is "install" instead._
If already installed, update with:
This CLI tool makes it easier to:
- get information about riglets and rigs exposed by a flake and its inputs (rigup show)
- show the contents of a rig, including which options can be used to customize it with their description, type, default and current values (rigup inspect)
- directly start a coding agent harness (rigup run or just rigup) if the rig contains a riglet that provides an _entrypoint_. Entrypoints act as connectors, wrapping a harness executable to start it with the appropriate config
- build a full rig as a folder of symlinks (rigup build)
- use a rig as a subshell, with $PATH and $RIG_MANIFEST (path to the RIG.md) set up (rigup shell)
Note all these commands are just wrappers, provided for convenience, around the rigup Nix library. So you may still do everything with usual nix build calls if you prefer.
You can then create a new project from the templates provided by this repository, or even directly build the example rig defined here.
Use a rig from this project (or any other repo using rigup)
This project defines example riglets, and an example rig combining them.
Create a new project
Create it from one of the templates in this repo:
This creates a ./foo folder, initializes it as a git repo, calls nix flake init to create a basic project structure with a flake.nix and example riglets and rigs, adds all the files to git tracking (_important_), and finally runs nix flake check on the result to make sure everything is in order.