# 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.