Skip to content
Back to search

rigup.nix

AI agents and Nix: parametrable skills/instructions and tools, packaged together in a reproducible and modular fashion

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/YPares/rigup.nix with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/YPares/rigup.nix'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ypares--rigup-nix/badge.svg)](/listings/ypares--rigup-nix)

HTML

<a href="/listings/ypares--rigup-nix"><img src="/api/listings/ypares--rigup-nix/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

First, install the `rigup` CLI tool:

nix profile add github:YPares/rigup.nix#rigup

_**NOTE:** On older Nix versions, "`add`" is "`install`" instead._

If already installed, update with:

nix profile upgrade rigup

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.

# Show the riglets and rigs exposed by a remote flake
rigup show github:YPares/rigup.nix
# Show all metadata about riglets and each rig's contents
rigup show --detailed github:YPares/agent-skills  # A Skills repo that also packages them via rigup

# Directly build a rig from a remote flake
rigup build github:YPares/rigup.nix#example-rig # this builds <flake>#rigs.<system>.example-rig.home and outputs a symlink

# Directly open a rig from a remote flake in a subshell
rigup shell github:YPares/rigup.nix#example-rig

# Directly run a rig's entrypoint (if it has any)
rigup run github:YPares/agent-skills#claude-rig
  # Then in Claude Code: Ctrl+o to show details, to see the RIG.md manifest that Claude was prompted with via a startup hook
rigup run github:YPares/agent-skills#copilot-rig
  # Almost the same rig, but using `copilot-cli` as an entrypoint

Create a new project

Create it from one of the templates in this repo:

rigup new foo [-t minimal]
  # Use 'minimal' template for a project which should not define any local riglet 

cd foo

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.

# List available riglets from flake's self and inputs
rigup show --detailed --with-inputs

# Build your rig
rigup build ".#default"

# Explore the rig
cat .rigup/default/RIG.md

# Or open the rig as a sub-shell instead of creating a local symlink
rigup shell ".#default"

Edit `riglets/*.nix` and `rigup.toml` to customize the project.

The default template includes some example riglets and shows how `rigup` supports using a Claude Marketplace as a direct input, to import pre-existing Skills and use them as a basis for riglets.

Alternative: Use `devenv`

If your project uses [`devenv`](https://devenv.sh) instead of Nix flakes, an experimental integration of `rigup` is available, using this repo directy as a devenv module you can import in your project. Follow the [example here](https://github.com/YPares/rigup-devenv-demo).

IMPORTANT: The `rigup` CLI tool **only** deals with flake-based projects, and the rest of this documentation is written assuming a flake-base project, but everything regarding how to declare rigs and riglets remains applicable. Only the way to start up rigs changes.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 472 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![logo](assets/logo/rigup-logo.jpg)
  2. # Self-Contained & Modular AI Agent Config
  3. `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.
  4. A _riglet_ is _executable knowledge_:
  5. - metadata to indicate to your agent what this riglet is for and when it is useful to consult it
  6. - a set of operations, instructions, processes, a.k.a a new [Skill](https://code.claude.com/docs/en/skills) for your agent
  7. - the tools (nix packages) needed to execute these instructions
  8. - the configuration for these tools (if any)
  9. 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.
  10. 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.
  11. It will then go on reading it when it needs to, or is prompted to.
  12. However, `rigup` gives you more control than Skills traditionally do in terms of when your agent should be exposed to a riglet's content.
  13. 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).
  14. 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](https://github.com/mitsuhiko/minijinja) to facilitate this use case.
  15. `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.
  16. 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.
  17. ## Quick start
  18. First, install the `rigup` CLI tool:
  19. ```bash
  20. nix profile add github:YPares/rigup.nix#rigup
  21. ```
  22. _**NOTE:** On older Nix versions, "`add`" is "`install`" instead._
  23. If already installed, update with:
  24. ```bash
  25. nix profile upgrade rigup
  26. ```
  27. This CLI tool makes it easier to:
  28. - get information about riglets and rigs exposed by a flake and its inputs (`rigup show`)
  29. - 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`)
  30. - 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
  31. - build a full rig as a folder of symlinks (`rigup build`)
  32. - use a rig as a subshell, with `$PATH` and `$RIG_MANIFEST` (path to the `RIG.md`) set up (`rigup shell`)
  33. 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.
  34. You can then create a new project from the templates provided by this repository, or even directly build the example rig defined here.
  35. ### Use a rig from this project (or any other repo using `rigup`)
  36. This project defines example riglets, and an example rig combining them.
  37. ```bash
  38. # Show the riglets and rigs exposed by a remote flake
  39. rigup show github:YPares/rigup.nix
  40. # Show all metadata about riglets and each rig's contents
  41. rigup show --detailed github:YPares/agent-skills # A Skills repo that also packages them via rigup
  42. # Directly build a rig from a remote flake
  43. rigup build github:YPares/rigup.nix#example-rig # this builds <flake>#rigs.<system>.example-rig.home and outputs a symlink
    • Dismissed after review: Contains a <system> block, a common wrapper for instructions hidden in a tool description
    • Line 66 on GitHub
  44. # Directly open a rig from a remote flake in a subshell
  45. rigup shell github:YPares/rigup.nix#example-rig
  46. # Directly run a rig's entrypoint (if it has any)
  47. rigup run github:YPares/agent-skills#claude-rig
  48. # Then in Claude Code: Ctrl+o to show details, to see the RIG.md manifest that Claude was prompted with via a startup hook
  49. rigup run github:YPares/agent-skills#copilot-rig
  50. # Almost the same rig, but using `copilot-cli` as an entrypoint
  51. ```
  52. ### Create a new project
  53. Create it from one of the templates in this repo:
  54. ```bash
  55. rigup new foo [-t minimal]
  56. # Use 'minimal' template for a project which should not define any local riglet
  57. cd foo
  58. ```
  59. 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.
  60. ```bash
  61. # List available riglets from flake's self and inputs
  62. rigup show --detailed --with-inputs
  63. # Build your rig
  64. rigup build ".#default"
  65. # Explore the rig
  66. cat .rigup/default/RIG.md
  67. # Or open the rig as a sub-shell instead of creating a local symlink
  68. rigup shell ".#default"
  69. ```
  70. Edit `riglets/*.nix` and `rigup.toml` to customize the project.
  71. The default template includes some example riglets and shows how `rigup` supports using a Claude Marketplace as a direct input, to import pre-existing Skills and use them as a basis for riglets.
  72. ### Alternative: Use `devenv`
  73. If your project uses [`devenv`](https://devenv.sh) instead of Nix flakes, an experimental integration of `rigup` is available, using this repo directy as a devenv module you can import in your project. Follow the [example here](https://github.com/YPares/rigup-devenv-demo).
  74. IMPORTANT: The `rigup` CLI tool **only** deals with flake-based projects, and the rest of this documentation is written assuming a flake-base project, but everything regarding how to declare rigs and riglets remains applicable. Only the way to start up rigs changes.
  75. Additionally, the `devenv` integration only covers declaring your own rigs and riglets and re-using riglets defined in other flake-based projects. To package riglets for others to use, Nix flakes remain a better fit.
  76. More information about using `rigup` with `devenv` will be added here as this integration matures.
  77. ## Deeper dive
  78. This section covers the general workflow of defining and editing riglets and rigs.
  79. ### Creating a riglet
  80. Riglets are a simple use case of [Nix modules](https://nix.dev/tutorials/module-system/a-basic-module/).
  81. Concretely, this means a riglet (in its most general form) is a `(config, dependencies) -> data` Nix function, where:
  82. - `config` is the final config of the rig which the riglet is part of,
  83. - `data` is a dictionary-like structure ("attribute set" in Nix lingo) providing nested fields that will _themselves_ contribute to the final aggregated config
  84. Create a `riglets/` folder at the root of your project.
  85. Then add to it a `<riglet-name>.nix` file:
  86. ```nix
  87. # riglets/my-riglet.nix
  88. # First argument: the defining flake's `self` - gives access to:
  89. # - `self.inputs.*` for external package dependencies
  90. # - `self.riglets.*` for inter-riglet imports
  91. # Just use `_` if you don't need it
  92. self:
  93. # Second argument: module args constructed by the _user_ of the riglet, when the full rig is built
  94. # - config is the final aggregated config of the rig using my-riglet,
  95. # - pkgs is your usual imported nixpkgs,
  96. # - system is just pkgs.stdenv.hostPlatform.system, for quicker access
  97. # - riglib is injected by rigup, and contains utility functions to build riglets
  98. { config, pkgs, system, riglib, ... }: {
  99. # (Optional) Which riglets to depend on (whether from self or input flakes)
  100. # If this riglet is included in a rig, ALL the riglets it imports will automatically be included as well
  101. imports = [
  102. self.riglets.foo
  103. self.inputs.aaa.riglets.bar
  104. ...
  105. ];
  106. # Each riglet must declare itself under config.riglets.<riglet-name>
  107. # <riglet-name> MUST be the SAME as the file name, minus the .nix extension
  108. config.riglets.my-riglet = {
  109. # (Optional) The tools needed by this riglet
  110. tools = [
  111. pkgs.mytool
  112. ./path/to/some/script.sh
  113. ];
  114. # The metadata that will enable your agent to know what this riglet
  115. # provides and when it should be consulted
  116. meta = {
  117. intent = "cookbook";
  118. # 'base', 'sourcebook', 'toolbox', 'cookbook', or 'playbook':
  119. # what should the agent expect from this riglet: general knowledge
  120. # that may come useful vs. highly specific procedure(s) to follow
  121. description = "What this provides";
  122. whenToUse = [
  123. "Need to know about X"
  124. "Want to achieve Y"
  125. "Have problems with Z"
  126. ...
  127. ];
  128. keywords = [ "search" "terms" ];
  129. status = "draft";
  130. version = "0.1.0";
  131. };
  132. # The Skill part of the riglet. It is a file hierarchy that should contain a
  133. # SKILL.md entry right under the root
  134. docs = riglib.writeFileTree {
  135. # Use inline strings...
  136. "SKILL.md" = ''
  137. # My Riglet Documentation
  138. ...
  139. For more advanced cases, see references/advanced-cases.md
  140. '';
  141. references = {
  142. # ...or local file paths...
  143. "advanced-cases.md" = ./path/to/advanced-cases.md;
  144. # ...or derivations that build a file
  145. "foo.md" = pkgs.writeText "foo.md" (mkFooContents x y z t);
  146. };
  147. };
  148. # Alternatively, if you already have a folder that follows the Agent Skill convention,
  149. # (SKILL.md at the top and references/*.md files), you can directly reuse it:
  150. #docs = ./path/to/skill/folder;
  151. # (Optional) The configuration that the tools should use.
  152. # This will go under `.config` in the final "home directory" of the rig, but only
  153. # for consultation purposes: tools are by default *wrapped* to see a XDG_CONFIG_HOME that
  154. # always points to this joint config folder. This way we can separate tools between those
  155. # that need custom config and those that will just "inherit" the pre-existing user config
  156. configFiles = riglib.writeFileTree {
  157. # Will generate `.config/mytool/config.toml`
  158. mytool."config.toml" = ''
  159. setting = "value"
  160. '';
  161. };
  162. };
  163. }
  164. ```
  165. ...or just ask your agent to do it! :) `rigup.nix` comes with the `riglet-creator` riglet that teaches your agent to write riglets and... and, ahem, yes that's becoming very meta, sorry about that.
  166. Just as with regular Agent Skills, the point of separating the docs into several files
  167. is to allow [_progressive disclosure_](https://en.wikipedia.org/wiki/Progressive_disclosure).
  168. When using AI Agents, this is important because [context](https://www.ibm.com/think/topics/context-window) is on a budget, and agents should not have to read [more documentation than they need](https://medium.com/@cdcore/mcp-is-broken-and-anthropic-just-admitted-it-7eeb8ee41933) to complete a task.
  169. #### Alternative structure
  170. Instead of `riglets/<riglet-name>.nix`, you can define your riglet as `riglets/<riglet-name>/default.nix` to add supporting files next to it:
  171. ```
  172. riglets/
  173. ├── simple-riglet.nix # Single-file riglet
  174. └── complex-riglet/ # Directory-based riglet
  175. ├── default.nix # Main riglet definition
  176. ├── SKILL.md # Referenced in default.nix via ./SKILL.md
  177. └── references/
  178. └── advanced.md # Referenced in default.nix via ./references/advanced.md
  179. ```
  180. This is useful to break up a riglet into various Nix or raw text files to make it more manageable.
  181. `rigup` will discover and treat both layouts identically.
  182. #### Inter-riglet dependencies
  183. If a riglet depends on another (for instance because it builds on its concepts or requires its tools or configuration), use `imports` with `self.riglets.*`:
  184. ```nix
  185. # riglets/advanced-riglet.nix
  186. self:
  187. { riglib, ... }: {
  188. # Import the base riglet - if both are added to a rig, evalModules deduplicates
  189. imports = [ self.riglets.base-riglet ];
  190. config.riglets.advanced-riglet = {
  191. # ...
  192. };
  193. }
  194. ```
  195. **Important:** Always use `self.riglets.*` for imports, never path-based imports like `./base-riglet.nix`. The `self.riglets.*` form ensures proper deduplication when the same riglet is included both directly and via imports.
  196. For dependencies on riglets from external flakes:
  197. ```nix
  198. self:
  199. { riglib, ... }: {
  200. imports = [ self.inputs.other-flake.riglets.some-riglet ];
  201. # ...
  202. }
  203. ```
  204. #### Using external packages
  205. Riglets can access packages from external flakes via `self.inputs`:
  206. ```nix
  207. self:
  208. { pkgs, system, riglib, ... }: {
  209. config.riglets.my-riglet = {
  210. tools =
  211. let someFlakePkgs = self.inputs.some-flake.packages.${system};
  212. in [
  213. someFlakePkgs.default
  214. pkgs.git
  215. ];
  216. };
  217. }
  218. ```
  219. This lets riglets bundle their own dependencies without requiring consumers to know about them.
  220. ### Creating a rig
  221. #### Simple option: `rigup.toml`
  222. Define rigs in `rigup.toml` at the top of your project:
  223. ```toml
  224. # Riglets to include in this rig, grouped by source
  225. [rigs.default.riglets]
  226. rigup = ["git-setup", "typst-reporter"] # From the rigup flake input
  227. self = ["my-local-riglet"] # From your riglets/ folder
  228. # Configuration for the riglets used in this rig
  229. [rigs.default.config.agent.identity]
  230. name = "Alice" # This is used by both git-setup and typst-reporter example riglets
  231. email = "alice@example.com"
  232. ```
  233. Your `flake.nix` should be:
  234. ```nix
  235. {
  236. inputs.rigup.url = "github:YPares/rigup.nix";
  237. outputs = { self, rigup, ... }@inputs:
  238. rigup {
  239. inherit inputs;
  240. # A unique name to identify your project in error messages :
  241. projectUri = "my-username/my-project";
  242. # Add this if you want your rigs and/or riglets to be built as part of `nix flake check` :
  243. #checkRigs = true;
  244. #checkRiglets = true;
  245. };
  246. }
  247. ```
  248. Finally, build the rig with:
  249. ```shell
  250. rigup build ".#default"
  251. ```
  252. ...or enter it through a sub-shell with:
  253. ```shell
  254. rigup shell ".#default"
  255. ```
  256. _NOTE: Just like `nix build` and `nix develop` target the `"default"` package or devShell when called without extra args, so do `rigup build` or `rigup shell` by targetting the rig named `"default"`_
  257. The riglets listed in your `rigup.toml` **must** match your flake inputs and what exists in your project. As a general case:
  258. ```toml
  259. [rigs.my-rig.riglets]
  260. some-flake = ["foo", "bar"]
  261. ```
  262. means that your `flake.nix` has a `some-flake` input that exposes the `riglets.foo` and `riglets.bar` outputs.
  263. `self` is just a special case of that, as every flake has an implicit `self` input which is the flake itself.
  264. **NOTE:** The main reason to use a TOML file instead of always defining everything as Nix code is not _just_ because TOML is (much) more well-known than Nix syntax.
  265. It is mainly because pure data (that can already cover a large set of use cases) is easier to manipulate via CLI tools than Nix code.
  266. #### Advanced option: combine with Nix
  267. ...that being said, building rigs directly in Nix (if you need the full Nix power to write your rig's configuration) is totally supported:
  268. ```nix
  269. {
  270. inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  271. inputs.rigup.url = "github:YPares/rigup.nix";
  272. inputs.foo.url = "github:bar/foo";
  273. outputs = { self, rigup, nixpkgs, foo, ... }@inputs:
  274. let
  275. system = "x86_64-linux";
  276. pkgs = import nixpkgs { inherit system; };
  277. in
  278. pkgs.lib.recursiveUpdate # merge both recursively, second arg taking precedence
  279. (rigup {
  280. inherit inputs;
  281. projectUri = "...";
  282. })
  283. {
  284. # Override or extend with custom rigs
  285. rigs.${system}.custom = rigup.lib.buildRig {
  286. inherit pkgs;
  287. modules = [
  288. self.riglets.aaa # Will use `$PROJECT_ROOT/riglets/{aaa.nix,aaa/default.nix}`
  289. foo.riglets.bbb # Use external riglets defined by our inputs
  290. foo.riglets.ccc
  291. # Extra config is given in the form of a simple in-line Nix module,
  292. # with or without `{ config, pkgs, riglib, ... }` arguments
  293. {
  294. config = {
  295. # More advanced config, that e.g. requires direct access to some Nix functions,
  296. # or even takes the form of Nix functions:
  297. aaa-config.i-need-a-derivation = pkgs.someDerivationBuilder "..." "........";
  298. bbbModuleOpts.conditions.is-x-y-pair-valid = x: y: x * y <= 42.420000000000001;
  299. }
  300. }
  301. ];
  302. };
  303. };
  304. }
  305. ```
  306. **IMPORTANT:** This makes the `rigup.toml` entirely _optional_, but it is **still necessary** to use `rigup { inherit inputs; ... }` to construct your flake's outputs.
  307. This is so `rigup` can discover which riglets are defined in your `$PROJECT_ROOT/riglets/` and correctly set up the `riglets` output of your flake.
  308. As the above suggests, you can totally mix both options: define some simple rigs in the `rigup.toml` and some advanced ones in Nix code.
  309. Although, prefer splitting you rigs' definitions in separate Nix files rather than declaring everything in your `flake.nix`, the example above is just for the sake of concision.
  310. ## Riglet metadata
  311. You may have noticed that riglets are a bit richer but also stricter in terms of metadata than Skills.
  312. This is to enforce a bit more rigidly some good documentation-writing practices, and to make critical information more upfront, both for agents reading a manifest and for humans browsing riglets provided by some source with `rigup show`.
  313. This contributes to the final documentation's quality without being too constraining.
  314. This is why, contrary to Skills:
  315. - a riglet must always have an **`intent`**: why it was written, what type of information it was meant to provide, what should one expect to gain when reading it.
  316. This notably guides the writing process, and limits the risk of riglets becoming a mash-up of contextual info, general guidelines and specific processes.
  317. Don't forget riglets can depend on one another: if some background knowledge is needed to specify some processes that an agent should follow, then rather than trying to conflate everything into one big mess, make a first `sourcebook` or `toolbox` riglet which can then be used as a dependency of subsequent `playbook` riglets.
  318. This way, the background information is shared, and will always come along with the more critical knowledge.
  319. Smaller, more focused riglets means more reusability.
  320. - a riglet has a dedicated list of use cases (`whenToUse`), which is **not** conflated with its `description`. When a riglet should "activate", i.e. when an agent should consult and follow it, is probably the most critical piece of information about it, and thus warrants a dedicated field
  321. This is notably useful when using agents to write riglets: they are not great at filling general fields like "description". They are better when their thinking is guided by a stricter schema.
  322. But this enables riglets to perform things that Skills just cannot do:
  323. - explicitly depend on one another (as we previously saw), to make sure critical background knowledge is always accessible _if needed_, and not simply assumed to be part of the LLM's training dataset.
  324. - specify _how_ they should be disclosed to an agent. Not all skills are equal, some contain critical information which you want to be very upfront about, others are "just in case" tips and tricks that should not overwhelm the agent. This is what the `meta.disclosure` field is about.
  325. - document ahead-of-time the quality of the knowledge they contain. Has it been battle tested quite a few times and proven useful? Could it still benefit from some proofreading or clarifications? This is what the `meta.status` field is for. Agents, just like humans, can make much better decisions if they know how much trust they can put in an information source. It is always safer to progress on shaky ground when you _know_ the ground is shaky.
  326. - provide a general framework for _agent configuration_ besides just Markdown docs: riglets are Nix modules, and the main goal of Nix modules is to set up configuration in a modular and reusable fashion.
  327. Riglets are no different, it's just that the biggest part of an AI agent's "config" happens to be human-readable documentation, which is why the focus so far has been on packaging docs.
  328. But riglets can have `meta.intent = "base"`: this is for riglets that should remain transparent to the agent while still interacting with the rig, e.g. to provide tools or plain old JSON or TOML config files.
  329. `rigup` enforces that these `base` riglets are NOT disclosed to the agent.
  330. This notably enables the most important tool of the rig, the agent's harness, to be expressed, packaged and used _just like any other part of the rig_.
  331. ## Features
  332. - **Plug-and-play integration with common agent harnesses** via riglets defining an `entrypoint` derivation. `rigup` will generate config for:
  333. - Claude Code
  334. - OpenCode
  335. - Pi (no MCP and deny rules support)
  336. - VSCode with Copilot
  337. - Cursor & `cursor-agent`
  338. - `copilot-cli` (although `copilot-cli` does not allow custom prompt commands, and MCP servers can only be set in user's config for now)
  339. - ...and possibly others to come (PRs are welcome!)
  340. - **Configure more than just Skills:** Harnesses that support it will be fed config for:
  341. - `mcpServers`: riglets can define MCP servers, both HTTP and command-based
  342. - `promptCommands`: riglets can define custom "slash commands" (prompt templates)
  343. - **Reproducible:** Nix ensures consistent tool versions
  344. - **Data-driven config:** `rigup.toml` for CLI-manageable rigs. Riglets from `riglets/` automatically exposed
  345. - **Compatibility with Skills and Claude Marketplaces:**
  346. - Directly import Claude Marketplace repos as inputs and use provided skills as basis for new riglets
  347. - Riglet documentation follows as much as possible the Skills structure and conventions to facilitate reusability
  348. - **Self-documenting:** Riglets like `agent-rig-system`, `riglet-creator`, and `nix-module-system` teach agents how the system works — so they can help you write Nix and extend your rig. Learn Nix as a side effect, with AI assistance.
  349. ## Related projects
  350. - [`openskills`](https://github.com/numman-ali/openskills): Universal Skill loader, following Claude Skills system and manifest
  351. - [`llm-agents.nix`](https://github.com/numtide/llm-agents.nix): Numtide's flake packaging AI coding agents and development tools
  352. - [`agent-skills-nix`](https://github.com/Kyure-A/agent-skills-nix): Nix lib to discover and bundle skills, with home-manager integration
  353. ## License
  354. MIT
  355. ______________________________________________________________________
  356. *Built with Nix • Formatting: nixfmt-rfc-style • Uses [blueprint](https://github.com/numtide/blueprint)*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.