# Agents

Home Manager module that owns the Nix side of the AI coding agents: deploying the global rules and
custom global skills, the agent CLIs, and their environment.

The canonical rules text, local skills, behavioral scenarios, and external-tool snippets live in the
top-level [`agents/`](../../../../agents/README.md) directory. That directory stays portable
Markdown with no Nix dependency; this module only wires it into place.

## Files

- `rules.nix`: links the global rules to every agent's config location.
- `skills.nix`: links the global skills into `~/.agents/skills/<name>`, from pinned flake inputs and
  from `agents/skills/`; the inventory is
  [agents/skills/README.md](../../../../agents/skills/README.md).
- `packages.nix`: agent CLIs (`codex`, `opencode`, `pi`) from the `llm-agents` flake input, dsh from
  `nur-ryan4yin`, `pkgs.ctx7` for the `find-docs` skill, and `pkgs.mcp-grafana` for the Grafana MCP
  server. Profile patches live in `~/.dsh/profiles/<name>/cordis.patch.yml`. See [dsh.md](./dsh.md)
  for the layer order and the settings that bite.
- `env.nix`: telemetry and auto-update opt-outs for the agents.

## Deployed rule targets

`rules.nix` creates one out-of-store symlink per target, all pointing at
`~/nix-config/agents/global-rules.md`:

| Agent      | Target                         |
| ---------- | ------------------------------ |
| Codex      | `~/.codex/AGENTS.md`           |
| OpenCode   | `~/.config/opencode/AGENTS.md` |
| Pi         | `~/.pi/agent/AGENTS.md`        |
| Cross-tool | `~/.agents/AGENTS.md`          |
| dsh        | `~/.dsh/AGENTS.md`             |

dsh reads both `~/.dsh/AGENTS.md` (`$DSH_HOME`) and, from `0.2.1-alpha.2` on, `~/.agents/AGENTS.md`
(`$DSH_AGENTS_HOME`); identical content renders once.

Out-of-store means an edit to `agents/global-rules.md` takes effect on the next agent session
without a Home Manager switch. The trade-off is that the rules stay writable in the checkout; use a
store symlink (`home.file.<target>.source = ../../../../agents/global-rules.md`) if immutability
matters more than fast iteration.

## Global skills

`skills.nix` links every directory under `agents/skills/` out-of-store, so an edit applies on the
next session, and the skills selected from pinned flake inputs as store paths, which change only
with a lock bump and a switch. Home Manager's normal collision checks apply: do not force
replacement of an existing same-name skill, and do not install global skills with
`npx skills add -g` alongside these links.

The installed releases support the shared root and symlinked skill directories, so no agent-specific
compatibility links are needed:

- **Codex**: [Skill documentation](https://learn.chatgpt.com/docs/build-skills.md) lists
  `~/.agents/skills` and symlinked skill folders.
- **OpenCode**:
  [v2.0.22 discovery](https://github.com/anomalyco/opencode/blob/v2.0.22/packages/core/src/config/discovery.ts)
  includes the global `.agents` root; its
  [compatibility loader](https://github.com/anomalyco/opencode/blob/v2.0.22/packages/core/src/config/plugin/compatibility.ts)
  follows skill symlinks.
- **Pi**:
  [v1.0.1 discovery](https://github.com/badlogic/pi-mono/blob/v1.0.1/packages/coding-agent/src/core/package-manager.ts)
  includes `~/.agents/skills` and follows symlink directories.
- **dsh**:
  [Filesystem skill package](https://www.npmjs.com/package/@deepseek-ai/dsh-skill-filesystem)
  documents `~/.agents/skills` and directory symlinks; confirmed in the shipped 0.2.1-rc.2 loader.

Adding or removing links requires a user-run Home Manager switch. Changes to an already-linked skill
are available without a rebuild; start a new session or use the harness's reload mechanism to read
them. After activation, verify the link target and that `git-delivery` appears in the skill catalog.
Custom root overrides or disabled discovery still need runtime configuration.

The rules include a direct checkout fallback for `git-delivery` before its link is installed.
Runtime permissions are not managed by this module.