Tool & Skill Architecture
Akmatori documents agent behavior through incident-level AGENTS.md guidance and skill-level SKILL.md files that include an auto-generated Assigned Tools section. Instead of Python import snippets, modern Akmatori routes tool use through the MCP Gateway, with generated gateway_call(...) and execute_script examples tied to the skill's actual assigned tools.
Overview
The goal is still to reduce exploration, but the execution model changed. Agents should read the relevant skill doc first, follow the generated tool examples, and use the gateway's namespaced tools directly. This keeps authorization, configuration, and routing centralized instead of asking agents to discover import paths or wire credentials manually. Connector and MCP registration changes can be reloaded at runtime, and proxied MCP tool schemas can be refreshed so newly discovered external tools show up without rewriting the skill prompt model.
File Responsibilities
AGENTS.md
Incident-level instructions loaded at the incident workspace root.
- Defines the incident manager role and investigation workflow
- Points agents to the relevant skill docs before they start exploring
- Can enforce operational guardrails, such as searching runbooks before using infrastructure tools
SKILL.md
Skill prompt plus an auto-generated Assigned Tools section.
- Stores YAML frontmatter and human-authored skill instructions
- Lists only the tools currently assigned to that skill
- Includes per-tool details and ready-to-use
gateway_call(...)examples - Can reference shared context files through linked assets
Gateway Tool Registry
The MCP Gateway is the runtime contract agents execute against.
- Built-in tool types include SSH, Zabbix, VictoriaMetrics, Catchpoint, PostgreSQL, Grafana, PagerDuty, ClickHouse, NetBox, and Kubernetes
- HTTP connectors can add declarative API-backed tools and trigger gateway reloads after CRUD changes
- External MCP servers can be proxied under a custom namespace prefix, with runtime reloads and schema refreshes for discovered tools
Assigned Tools Pattern
Generated skill docs now include a structured tool section with copyable gateway examples. This keeps the docs aligned with the authorized tool set for that skill and avoids stale import instructions.
## Assigned Tools
### Production PostgreSQL (logical_name: "prod-db", type: postgresql)
Use ```python
gateway_call("postgresql.list_tables", {}, "prod-db")
gateway_call("postgresql.describe_table", {"table_name": "users"}, "prod-db")
```
For multi-step work, use `execute_script` with built-in `gateway_call()`.
gateway_call, with execute_script available for multi-step workflows. Key Principles
Skill-scoped authorization
Generated docs should reflect only the tools a skill is actually allowed to use, not the entire platform surface area.
Gateway-first execution
Agents should prefer gateway_call and execute_script so routing, auth, rate limiting, and auditing stay centralized.
Generated docs stay close to runtime behavior
Examples should be produced from current tool assignments and tool types, so docs change when the real execution path changes.
Less discovery, more investigation
Good docs remove avoidable exploration while still leaving room for runbook search, incident analysis, and targeted debugging.
Generation Flow
- User assigns one or more tool instances to a skill in the UI.
- The backend regenerates
SKILL.mdwith the currentAssigned Toolssection. - Each generated block includes the logical tool name and gateway usage examples for that tool type.
- HTTP connector and MCP server changes can trigger gateway reloads so new tools appear without a full rebuild.
- When an incident is created, Akmatori generates
AGENTS.mdthat points agents to the right skills and workflow.
Contributor Checklist
When adding a new built-in tool type
Update tool registration and add a concrete usage example in generateToolUsageExample() so assigned skills get useful gateway examples automatically.
When changing skill docs behavior
Keep generated section markers and stripping logic aligned so user-authored prompt content is preserved while auto-generated blocks stay fresh.
When extending integrations
Decide whether the new capability belongs in a built-in tool type, a declarative HTTP connector, or a proxied external MCP server, then document that runtime path clearly.
Troubleshooting
Assigned tools look wrong
Check the skill-to-tool assignment and regenerate skill docs so SKILL.md is rebuilt from the current mapping.
A connector or MCP server is missing
Verify the HTTP connector or MCP server configuration exists, has a non-conflicting namespace, and that the gateway reload completed successfully.
Agents are still exploring too much
Make sure AGENTS.md points agents to the right skill docs and that the generated gateway examples are specific enough to execute directly.