starred/nix-config
1
0 Fork 0
mirror of https://github.com/ryan4yin/nix-config.git synced 2026-11-13 12:13:46 +01:00
Code Issues Packages Projects Releases 10 Wiki Activity
Files
2b0f01d99c416da9be7d5948b7593b515614a861
nix-config/agents
T
History
ryan4yin | 二花 2b0f01d99c chore(agents): workspace layout, related repositories, and ~/src checkouts (#340) 
* docs(skills): point nix-config-secrets at the private repo under ~/codes

Record where the private nix-secrets checkout lives and that agents should
do the mechanical secret work themselves, handing back only the
interactive/sudo agenix operations and pushes.

* docs(agents): add related repositories to nix-config

* chore(agents): adopt ~/src for source checkouts

Move third-party/source checkouts from ~/codes/src to ~/src so the home
layout reads as three siblings: ~/codes (personal), ~/work (work),
~/src (checkouts). Preserve and back up the new path, and update the
global rule and the two nixpkgs skill references.

* docs(agents): tighten the code layout rule

* docs(agents): fold the work-confidentiality note into the layout line

* docs(agents): base the confidentiality rule on repo visibility

* docs(agents): drop the stale KubeVirt mention
2026-10-02 11:16:24 +08:00
..
evals
docs(agents): clarify local language selection and prefer Bun
2026-10-01 10:23:35 +08:00
AGENTS.md
chore(agents): workspace layout, related repositories, and ~/src checkouts (#340)
2026-10-02 11:16:24 +08:00
install-cli.md
fix(docs): correct stale and mismatched documentation (#338)
2026-10-02 10:21:55 +08:00
install-rules.py
chore(agents): remove crush
2026-09-25 00:30:12 +08:00
install-skills.md
docs(skills): add repo-scoped task skills and give each fact one home (#337)
2026-10-02 10:13:03 +08:00
README.md
docs(skills): add repo-scoped task skills and give each fact one home (#337)
2026-10-02 10:13:03 +08:00
test_install_rules.py
chore(agents): remove crush
2026-09-25 00:30:12 +08:00

README.md

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.

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-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:

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
  • 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

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:

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

Reference in new issue View Git Blame Copy Permalink