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

Core workflow

Maintain shared rules in agents/AGENTS.md.
Configure permissions directly in the agent runtime; auto-approval is generally used.
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.
Use install-tooling.md as a reference when installing external agent tooling.

Deployment

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.

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.

Goal

Maintain one reusable source of truth for agent setup that stays simple to sync and easy to evolve.

README.md

agents