fix(agents,hands): per-agent/per-hand mcp_servers / skills allowlists (#87)

agents/README.md

@@ -26,6 +26,17 @@ description = "Expert software engineer. Reads, writes, and analyzes code."
 author = "librefang"
 module = "builtin:chat"              # runtime module — builtin:chat for all current agents
 
+# Resource allowlists — keep these small. The kernel injects every entry's
+# tools/skills into the agent's prompt on every LLM call, so an empty list
+# (the default "all available" semantics) on an instance with many MCP
+# servers and skills can burn 30-60k tokens per turn on definitions the
+# agent never uses.
+mcp_servers = ["memory", "git", "github", "filesystem"]   # [] = all available
+skills = ["rust-expert", "python-expert", "git-expert"]   # [] = all available
+# max_history_messages = 60          # OPT-IN override; omit to inherit kernel default
+                                     # (default rises with the kernel; setting too low
+                                     #  thrashes the prompt cache — measure before pinning)
+
 [metadata.routing]
 aliases = ["write code", "fix bug", "implement feature"]    # exact activation phrases
 weak_aliases = ["refactor", "patch", "code change"]         # keyword hints
@@ -171,8 +182,9 @@ Agents can also be used as base templates in a Hand by setting `base = "coder"`
 2. Set `module = "builtin:chat"` unless you have a custom runtime module.
 3. Write a focused `system_prompt` — clear role definition, methodology, and constraints.
 4. Declare only the tools and capabilities the agent actually needs.
-5. Add `[metadata.routing]` aliases so the router can activate the agent by intent.
-6. Run `python scripts/validate.py`.
-7. Submit a PR.
+5. Set `mcp_servers` and `skills` to the minimum the prompt actually references — leaving them empty falls back to "all available", which on a populated instance bloats every LLM call with tool definitions the agent never uses.
+6. Add `[metadata.routing]` aliases so the router can activate the agent by intent.
+7. Run `python scripts/validate.py`.
+8. Submit a PR.
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.

agents/academic-researcher/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["research", "academic", "papers", "literature-review", "science"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "fetch", "exa-search", "brave-search"]
+skills = ["technical-writer", "writing-coach", "pdf-reader"]
+
+
+max_history_messages = 80
 [metadata.routing]
 aliases = [
   "academic research",

agents/analyst/agent.toml

@@ -4,6 +4,14 @@ description = "Data analyst. Processes data, generates insights, creates reports
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "sqlite-mcp", "postgresql"]
+skills = ["data-analyst", "sql-analyst", "python-expert"]
+
+
+max_history_messages = 80
 [metadata.routing]
 aliases = ["analytics", "metrics analysis", "report analysis"]
 weak_aliases = ["kpi", "insights", "reporting"]

agents/architect/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["architecture", "design", "planning"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "fetch", "github"]
+skills = ["openapi-expert", "technical-writer"]
+
+
+max_history_messages = 80
 [metadata.routing]
 aliases = [
   "system design",

agents/assistant/agent.toml

@@ -12,6 +12,14 @@ tags = [
   "productivity",
 ]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "fetch", "filesystem"]
+skills = []
+
+
+max_history_messages = 120
 [metadata.routing]
 aliases = [
   "general help",

agents/code-reviewer/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["review", "code-quality", "best-practices"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "github", "git"]
+skills = ["code-reviewer", "rust-expert", "python-expert", "typescript-expert"]
+
+
+max_history_messages = 80
 [metadata.routing]
 aliases = [
   "code review",

agents/coder/agent.toml

@@ -5,6 +5,20 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["coding", "implementation", "rust", "python"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "git", "github", "filesystem"]
+skills = [
+  "rust-expert",
+  "python-expert",
+  "typescript-expert",
+  "git-expert",
+  "shell-scripting",
+]
+max_history_messages = 80
+
+
 [metadata.routing]
 aliases = [
   "write code",

agents/customer-support/agent.toml

@@ -12,6 +12,14 @@ tags = [
   "resolution",
 ]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "fetch"]
+skills = ["email-writer", "writing-coach"]
+
+
+max_history_messages = 60
 [metadata.routing]
 aliases = [
   "customer support",

agents/data-scientist/agent.toml

@@ -4,6 +4,14 @@ description = "Data scientist. Analyzes datasets, builds models, creates visuali
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "sqlite-mcp", "postgresql"]
+skills = ["data-analyst", "ml-engineer", "python-expert", "sql-analyst"]
+
+
+max_history_messages = 80
 [metadata.routing]
 aliases = ["data science", "build model", "train model", "machine learning"]
 weak_aliases = ["modeling", "statistics"]

agents/debugger/agent.toml

@@ -4,6 +4,14 @@ description = "Expert debugger. Traces bugs, analyzes stack traces, performs roo
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "git", "github", "sentry"]
+skills = ["rust-expert", "python-expert", "shell-scripting"]
+
+
+max_history_messages = 80
 [metadata.routing]
 aliases = [
   "debug this",

agents/devops-lead/agent.toml

@@ -4,6 +4,23 @@ description = "DevOps lead. Manages CI/CD, infrastructure, deployments, monitori
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "git", "github", "filesystem"]
+skills = [
+  "docker",
+  "kubernetes",
+  "terraform",
+  "ansible",
+  "ci-cd",
+  "helm",
+  "prometheus",
+  "sysadmin",
+]
+max_history_messages = 60
+
+
 [metadata.routing]
 aliases = [
   "ci cd",

agents/doc-writer/agent.toml

@@ -4,6 +4,14 @@ description = "Technical writer. Creates documentation, README files, API docs,
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "filesystem", "fetch", "github"]
+skills = ["technical-writer", "writing-coach", "openapi-expert"]
+
+
+max_history_messages = 60
 [metadata.routing]
 aliases = [
   "write documentation",

agents/email-assistant/agent.toml

@@ -12,6 +12,14 @@ tags = [
   "productivity",
 ]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "gmail"]
+skills = ["email-writer", "writing-coach"]
+
+
+max_history_messages = 60
 [metadata.routing]
 aliases = [
   "draft email",

agents/health-tracker/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["health", "wellness", "fitness", "medication", "habits", "tracking"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory"]
+skills = []
+skills_disabled = true
+
+
 [metadata.routing]
 aliases = [
   "health tracking",

agents/hello-world/agent.toml

@@ -4,6 +4,14 @@ description = "A friendly greeting agent that can read files, search the web, an
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "fetch"]
+skills = []
+skills_disabled = true
+
+
 [metadata.routing]
 aliases = [
   "hello world",

agents/home-automation/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["smart-home", "iot", "automation", "devices", "monitoring", "home"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "fetch"]
+skills = []
+skills_disabled = true
+
+
 [metadata.routing]
 aliases = [
   "smart home",

agents/legal-assistant/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["legal", "contracts", "compliance", "research", "review", "documents"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "fetch"]
+skills = ["compliance", "writing-coach"]
+
+
+max_history_messages = 80
 [metadata.routing]
 aliases = [
   "legal review",

agents/meeting-assistant/agent.toml

@@ -12,6 +12,14 @@ tags = [
   "productivity",
 ]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "google-calendar", "gmail"]
+skills = ["writing-coach"]
+
+
+max_history_messages = 60
 [metadata.routing]
 aliases = [
   "meeting notes",

agents/ops/agent.toml

@@ -4,6 +4,20 @@ description = "DevOps agent. Monitors systems, runs diagnostics, manages deploym
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "git"]
+skills = [
+  "docker",
+  "sysadmin",
+  "shell-scripting",
+  "linux-networking",
+  "prometheus",
+]
+max_history_messages = 60
+
+
 [metadata.routing]
 aliases = [
   "service status",

agents/orchestrator/agent.toml

@@ -4,6 +4,14 @@ description = "Meta-agent that decomposes complex tasks, delegates to specialist
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory"]
+skills = []
+
+
+max_history_messages = 120
 [metadata.routing]
 aliases = [
   "multi agent",

agents/personal-finance/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["finance", "budget", "expenses", "savings", "planning", "money"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory"]
+skills = ["data-analyst"]
+
+
+max_history_messages = 60
 [metadata.routing]
 aliases = [
   "budget planning",

agents/planner/agent.toml

@@ -4,6 +4,14 @@ description = "Project planner. Creates project plans, breaks down epics, estima
 author = "librefang"
 module = "builtin:chat"
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "github", "linear", "jira"]
+skills = ["project-manager"]
+
+
+max_history_messages = 60
 [metadata.routing]
 aliases = [
   "project plan",

agents/recipe-assistant/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["cooking", "recipes", "meal-planning", "nutrition", "food"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "fetch"]
+skills = []
+skills_disabled = true
+
+
 [metadata.routing]
 aliases = [
   "recipe helper",

agents/recruiter/agent.toml

@@ -5,6 +5,14 @@ author = "librefang"
 module = "builtin:chat"
 tags = ["recruiting", "hiring", "resume", "outreach", "talent", "hr"]
 
+# Per-agent resource allowlists (refs librefang/librefang-registry#87).
+# Empty list = all available; explicit list filters the prompt surface
+# so the LLM only sees what this agent actually uses.
+mcp_servers = ["memory", "gmail", "linear"]
+skills = ["email-writer", "writing-coach", "interview-prep"]
+
+
+max_history_messages = 60
 [metadata.routing]
 aliases = [
   "candidate screening",