agent-skills-nix
Declarative management of Agent Skills on Nix
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
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/Kyure-A/agent-skills-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/Kyure-A/agent-skills-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
Markdown
[](/listings/kyure-a--agent-skills-nix)HTML
<a href="/listings/kyure-a--agent-skills-nix"><img src="/api/listings/kyure-a--agent-skills-nix/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Put skills config in a small child flake so the only pinned inputs there are skill sources.
Use the quickstart example:
- Overview: [`examples/quickstart/README.md`](./examples/quickstart/README.md) - Main (tightly coupled): [`examples/quickstart/main/flake.nix`](./examples/quickstart/main/flake.nix) - Child (separated catalog): [`examples/quickstart/child/flake.nix`](./examples/quickstart/child/flake.nix)
Notes:
- In `main`, `agent-skills` and skill sources are listed directly in the top-level inputs. - In `child`, top-level only depends on `skills-catalog = path:./skills`; skills inputs live under `./skills/flake.nix`. - If you use source `input` references in your module config, pass flake `inputs` to Home Manager via `extraSpecialArgs`. - To enable a default target, set `targets.<name>.enable = true;` (e.g. `targets.claude.enable = true;`). - `structure = "link"` uses `home.file` symlinks; `symlink-tree` and `copy-tree` run in `home.activation`. - `symlink-tree` uses `rsync -a --delete` (preserve symlinks); `copy-tree` uses `rsync -aL --delete` (dereference symlinks). - Runtime `dest` values support `$HOME`, `~`, and `${VAR:-$HOME/...}` fallback forms (e.g. `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills`). Home Manager's `link` structure requires a static path and uses the fallback path. - Symlinks inside skills are preserved when their target stays inside the source root; escaping or dangling ones are dropped. See [Symlinks inside skills](#symlinks-inside-skills).
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 · 142 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # agent-skills-nix
- Manage Agent Skills (directories containing `SKILL.md`) declaratively with Nix.
- Pin skill sources, select the skills you need, and install them through Home
- Manager or project-local commands. You can also export selected skills as a
- self-contained Agent Plugin.
- Nothing is installed by default: choose both skills and targets explicitly.
- ## Quick start with Home Manager
- For an existing flake-based Home Manager configuration, add these inputs to
- your flake:
- ```nix
- inputs = {
- agent-skills.url = "github:Kyure-A/agent-skills-nix";
- anthropic-skills = {
- url = "github:anthropics/skills";
- flake = false;
- };
- };
- ```
- Capture the flake inputs with `outputs = inputs@{ ... }: ...;`. Add
- `inputs.agent-skills.homeManagerModules.default` to your existing Home Manager
- `modules` list and pass `extraSpecialArgs = { inherit inputs; };` to
- `home-manager.lib.homeManagerConfiguration`. This makes the named skill input
- available to the module.
- Then add the following to your Home Manager configuration:
- ```nix
- programs.agent-skills = {
- enable = true;
- sources.anthropic = {
- input = "anthropic-skills";
- subdir = "skills";
- };
- skills.enable = [ "frontend-design" "skill-creator" ];
- targets.claude.enable = true;
- };
- ```
- Apply your Home Manager configuration as usual. The selected skills are synced
- to `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills`. Enable other agents with
- `targets.<name>.enable = true;`; see [default target paths](#default-target-paths).
- For an existing non-empty skills directory, see
- [destination ownership](./docs/installation.md#destination-ownership).
- The [complete quickstart examples](./examples/quickstart/README.md) show both
- ways to arrange the inputs:
- - [Main flake](./examples/quickstart/main/flake.nix): keep agent-skills and skill
- sources alongside your Home Manager inputs.
- - [Child flake](./examples/quickstart/child/flake.nix): keep the skill inputs in a
- separate catalog flake.
- ## How it works
- 1. **Sources** point to skill roots in flake inputs, local paths, or an optional
- [source registry](./docs/source-registry.md).
- 2. **Discovery** scans for `SKILL.md` files and builds a catalog. Nested skill
- IDs use `/`, such as `documents/pdf`; `idPrefix` adds a source namespace.
- 3. **Selection** chooses catalog entries with `skills.enable` or
- `skills.enableAll`, and custom declarations with `skills.explicit`.
- 4. **Bundling** builds the selection in the Nix store, including any content
- transforms and package dependencies.
- 5. **Targets** install the bundle for enabled agents. Explicit skills can limit
- installation to named targets with `agents`.
- ## Guides and examples
- | Task | Guide | Example |
- |------|-------|---------|
- | Configure sources, select skills, and customise content | [Configuration](./docs/configuration.md) | [Transforms and dependencies](./examples/skill-customization/explicit-transform.nix) |
- | Install skills in a project | [Installation](./docs/installation.md#project-local-installation) | [Local install flake](./examples/local-install/flake.nix) |
- | Install automatically on shell entry | [Development shells](./docs/installation.md#development-shells) | [devShell flake](./examples/devshell/flake.nix) |
- | Pin sources without a flake input per repository | [Source registry](./docs/source-registry.md) | [Registry flake](./examples/source-registry/README.md) |
- | Export a portable skills-only plugin | [Agent Plugin export (experimental)](./docs/agent-plugin.md) | [Plugin flake](./examples/agent-plugin/README.md) |
- | Build your own integration | [Library and flake reference](./docs/reference.md) | [Library snippet](./examples/library-functions/snippet.nix) |
- The root flake has an empty catalog and no enabled targets. Installation
- commands such as `nix run .#skills-install-local` must run against your own
- configured flake. Home Manager installs skills when you activate your home
- configuration; it does not add apps to your flake.
- ## Default target paths
- Use `agents` to install a shared skill set for tools that discover
- `.agents/skills`. Claude Code uses its own skill directory:
- | Target | Global path | Local path |
- |--------|-------------|------------|
- | agents (shared) | `$HOME/.agents/skills` | `.agents/skills` |
- | claude | `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills` | `.claude/skills` |
- Product-specific targets remain available for separate installation destinations
- and features that require a dedicated path. See the
- [full target list](./docs/installation.md#default-target-paths).
- All built-in targets are disabled by default. Global targets use
- `symlink-tree`; local targets use `copy-tree`. See
- [target configuration](./docs/installation.md#target-configuration) for custom
- paths, structures, and system filters.
- ## Development
- The root `flake.nix` depends only on nixpkgs. It wires the library, packages,
- apps, checks, and Home Manager module through ordinary Nix imports:
- | Directory | Contents |
- |-----------|----------|
- | `lib/` | Discovery, selection, bundling, targets, registry, and plugin export |
- | `modules/` | Shared options and Home Manager integration |
- | `nix/` | Package, app, and default configuration definitions |
- | `scripts/` | Synchronization, source locking, and plugin validation runtimes |
- | `test/` | Library and runtime checks, plus Home Manager integration tests |
- | `examples/` | Consumer configurations |
- Home Manager is a test-only dependency in `test/flake.nix`, which imports the
- root flake through a relative path and follows its nixpkgs input. Consumers do
- not inherit a Home Manager dependency.
- Run both check suites from the repository root:
- ```console
- nix flake check
- nix flake check ./test
- ```
- To update dependencies, update the root lock first, then the test lock:
- ```console
- nix flake update
- nix flake update --flake ./test
- ```
- CI runs both suites and checks formatting with `nix fmt`. The dependency update
- workflow updates both lock files.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.