mirror of
https://github.com/ryan4yin/nix-config.git
synced 2026-11-20 14:31:28 +01:00
92 lines
4.3 KiB
Markdown
92 lines
4.3 KiB
Markdown
# agents
|
|
|
|
Portable agent resources shared across projects: the global baseline rules, behavioral scenarios for
|
|
those rules, and reference snippets for external tooling.
|
|
|
|
Home Manager links the rules from here into each agent's config location, so `agents/` itself stays
|
|
plain Markdown with no Nix dependency.
|
|
|
|
It is shared across projects. Repo-scoped task procedures for one repository belong elsewhere: put
|
|
them in that repository's `.agents/skills/` (note the leading dot), which OpenCode and compatible
|
|
tools discover automatically. In a repository, use the layers this way:
|
|
|
|
- `AGENTS.md`: always-loaded map and hard safety rules; keep it short.
|
|
- `*.md` / `README.md`: reference and domain runbooks for people, kept next to the code they
|
|
describe.
|
|
- `.agents/skills/*/SKILL.md`: on-demand procedures, verification steps, and agent-only constraints.
|
|
|
|
Keep one canonical home for each fact; link between layers instead of copying paragraphs.
|
|
|
|
## What this directory contains
|
|
|
|
- `AGENTS.md`: global baseline rules for coding agents.
|
|
- `evals/global-rules.md`: behavioral scenarios for validating changes to the global rules.
|
|
- `install-skills.md`: curated `npx skills` command snippets, plus the `npx ctx7` docs-tool setup.
|
|
|
|
The Nix side of the agents — deploying these rules, the agent CLIs, and their environment — lives in
|
|
the Home Manager module [`home/base/tui/agents/`](../home/base/tui/agents/README.md).
|
|
|
|
## Core workflow
|
|
|
|
1. Maintain shared rules in `agents/AGENTS.md`.
|
|
2. Configure permissions directly in the agent runtime; auto-approval is generally used.
|
|
3. Edit the rules; Home Manager links them out-of-store, so the change reaches the next agent
|
|
session without a rebuild. Run a Home Manager switch only when the deployed target set changes.
|
|
4. Use `install-skills.md` as a reference when installing external skills.
|
|
|
|
## Deployment
|
|
|
|
[`home/base/tui/agents/rules.nix`](../home/base/tui/agents/rules.nix) links `AGENTS.md` into every
|
|
supported agent config directory as an out-of-store symlink, so edits apply without a rebuild:
|
|
|
|
- Codex: `AGENTS.md` -> `${CODEX_HOME:-~/.codex}/AGENTS.md`
|
|
- OpenCode: `AGENTS.md` -> `${XDG_CONFIG_HOME:-~/.config}/opencode/AGENTS.md`
|
|
- Pi: `AGENTS.md` -> `~/.pi/agent/AGENTS.md`
|
|
- OMP: `AGENTS.md` -> `~/.omp/agent/AGENTS.md`
|
|
- Generic cross-tool (read by Kimi Code): `AGENTS.md` -> `~/.agents/AGENTS.md`
|
|
|
|
The module is imported through `home/base/tui`, so it covers the hosts that import
|
|
`home/linux/gui.nix` or the macOS `home/darwin` stack; core-only servers are unchanged.
|
|
|
|
Only `AGENTS.md` is deployed to the agents. Permission configuration and skills are not installed by
|
|
Nix; the CLIs themselves are, via the same module's `packages.nix`. The repository-root `AGENTS.md`
|
|
contains guidance for this Nix configuration repository. It is not the global rules source and is
|
|
not deployed.
|
|
|
|
Auto-approval controls tool prompting. The global rules still define task authorization, safety, and
|
|
secret handling.
|
|
|
|
## About `install-skills.md`
|
|
|
|
Use it as a snippet library:
|
|
|
|
- review the commands
|
|
- select what you need
|
|
- run selected commands manually
|
|
|
|
## TODO
|
|
|
|
Ideas worth adopting once a concrete need appears; nothing here is implemented yet.
|
|
|
|
- **Shared instructions and skills.** Deploy one rules body plus declared skills to every agent
|
|
instead of maintaining a copy per agent. Reference: `mirkolenz/infra`
|
|
`options/home-manager/agents.nix` (custom `programs.agents`, follows the Agent Skills spec) and
|
|
`khaneliman/khanelinix` `modules/common/ai-tools/`.
|
|
- **Single-source permissions.** Keep allow/ask/deny command lists and agent role definitions in one
|
|
place and render them per harness. Reference: `khaneliman/khanelinix`
|
|
`modules/common/ai-tools/{permissions,agents}.nix`.
|
|
- **MCP from one definition.** Define MCP servers once and project them into each client. Home
|
|
Manager ships `programs.mcp` (writes `$XDG_CONFIG_HOME/mcp/mcp.json`), but consumers still render
|
|
it per agent. References: Home Manager `modules/programs/mcp.nix`, `jevy/home-manager-nix-config`
|
|
`modules/dev/mcp.nix`, `dryvist/nix-ai` `modules/mcp/`.
|
|
|
|
## Conventions
|
|
|
|
- Keep files portable and reviewable.
|
|
- Keep secrets and machine-specific credentials out of this directory.
|
|
- Keep guidance generic enough to reuse across multiple agent environments.
|
|
|
|
## Goal
|
|
|
|
Maintain one reusable source of truth for agent setup that stays simple to sync and easy to evolve.
|