mirror of
https://github.com/ryan4yin/nix-config.git
synced 2026-11-13 12:13:46 +01:00
78 lines
3.5 KiB
Markdown
78 lines
3.5 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-tooling.md`: curated install snippets for external agent tooling (`npx skills`,
|
|
`npx ctx7`, tuios integration).
|
|
|
|
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-tooling.md` as a reference when installing external agent tooling.
|
|
|
|
## 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. The
|
|
per-agent target list lives in that module's
|
|
[README](../home/base/tui/agents/README.md#deployed-rule-targets).
|
|
|
|
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-tooling.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.
|
|
|
|
- **Unified skill and MCP management.** Skills are installed with `npx skills` and MCP servers are
|
|
configured by hand per harness; a single source that renders to each agent would be nicer, though
|
|
MCP config formats differ per client. Reference: `mirkolenz/infra`
|
|
`options/home-manager/agents.nix` (custom `programs.agents`, follows the Agent Skills spec).
|
|
|
|
## 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.
|