mirror of
https://github.com/ryan4yin/nix-config.git
synced 2026-09-14 22:01:46 +02:00
94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# agents
|
|
|
|
Reusable, symlink-first agent resources shared across projects.
|
|
|
|
This directory is the canonical source for baseline agent rules and supporting command references.
|
|
The primary workflow is to symlink files from here into each agent runtime/config location.
|
|
|
|
## 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-rules.py`: installs the baseline by creating symlinks in supported agent config dirs.
|
|
- `test_install_rules.py`: regression tests for file preservation and independent target handling.
|
|
- `install-cli.md`: curated CLI install/update command snippets.
|
|
- `install-skills.md`: curated `npx skills` command snippets.
|
|
|
|
## Core workflow
|
|
|
|
1. Maintain shared rules in `agents/AGENTS.md`.
|
|
2. Configure permissions directly in the agent runtime; auto-approval is generally used.
|
|
3. Run `install-rules.py` to refresh symlinks in local agent homes.
|
|
4. Use `install-cli.md` and `install-skills.md` as reference snippets when needed.
|
|
|
|
## Install baseline rules (symlink-based)
|
|
|
|
Run:
|
|
|
|
```bash
|
|
python3 agents/install-rules.py
|
|
```
|
|
|
|
Current targets:
|
|
|
|
- Codex: `AGENTS.md` -> `${CODEX_HOME:-~/.codex}/AGENTS.md`
|
|
- OpenCode: `AGENTS.md` -> `${XDG_CONFIG_HOME:-~/.config}/opencode/AGENTS.md`
|
|
- Claude Code: `AGENTS.md` -> `~/.claude/CLAUDE.md`
|
|
- Generic cross-tool (read by Kimi Code): `AGENTS.md` -> `~/.agents/AGENTS.md`
|
|
|
|
Behavior:
|
|
|
|
- Each target is handled independently.
|
|
- Target errors are reported while remaining targets are attempted; any error yields a nonzero exit.
|
|
- Missing destination directories are skipped.
|
|
- Existing regular files are preserved as `.bak` backups (numbered when a backup already exists).
|
|
- Destination links are replaced atomically; a failed link creation leaves the destination intact.
|
|
|
|
The installer links only `AGENTS.md`; it does not install permission configuration, skills, or CLIs.
|
|
The repository-root `AGENTS.md` contains guidance for this Nix configuration repository. It is not
|
|
the global rules source and is not installed by this script.
|
|
|
|
Auto-approval controls tool prompting. The global rules still define task authorization, safety, and
|
|
secret handling.
|
|
|
|
Run installer regression tests without changing installed rules:
|
|
|
|
```bash
|
|
python3 -B -m unittest discover -s agents -p test_install_rules.py
|
|
```
|
|
|
|
## About `install-cli.md` and `install-skills.md`
|
|
|
|
Use them as snippet libraries:
|
|
|
|
- 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, and the install
|
|
scripts above do not cover it.
|
|
|
|
- **Shared instructions and skills.** Deploy one rules body plus declared skills to every agent
|
|
(Claude Code, Codex, OpenCode) 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.
|