From 8d108ee0355627a50518b204c19d7f85fc5358ef Mon Sep 17 00:00:00 2001
From: Ryan Yin <xiaoyin_c@qq.com>
Date: Mon, 14 Sep 2026 11:40:13 +0800
Subject: [PATCH] docs(agents): add herdr skill and record config TODOs

---
 agents/README.md         | 17 +++++++++++++++++
 agents/install-skills.md |  4 ++++
 2 files changed, 21 insertions(+)

diff --git a/agents/README.md b/agents/README.md
index fdd34227..1e70ab58 100644
--- a/agents/README.md
+++ b/agents/README.md
@@ -65,6 +65,23 @@ Use them as snippet libraries:
 - 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.
diff --git a/agents/install-skills.md b/agents/install-skills.md
index 9a5b4dfb..fc021a3c 100644
--- a/agents/install-skills.md
+++ b/agents/install-skills.md
@@ -49,6 +49,9 @@ npx skills add -g DietrichGebert/ponytail --skill 'ponytail-review'
 
 # enable a terse response mode when context or token usage matters
 npx skills add -g JuliusBrussee/caveman --skill 'caveman'
+
+# inspect and control herdr panes, tabs, workspaces, agents, and commands from a herdr pane
+npx skills add -g herdrdev/herdr --skill 'herdr'
 ```
 
 ## Optional project skills
@@ -78,5 +81,6 @@ References:
 - https://github.com/blader/humanizer
 - https://github.com/DietrichGebert/ponytail
 - https://github.com/JuliusBrussee/caveman
+- https://github.com/herdrdev/herdr
 - https://github.com/anthropics/skills
 - https://github.com/trailofbits/skills