Tool & Skill Documentation Architecture
Akmatori documents tool usage through a layered model: AGENTS.md carries the incident-manager prompt, SKILL.md contains the skill prompt plus an auto-generated Assigned Tools section, and tool usage is expressed through gateway_call() examples instead of direct Python imports.
Overview
The goal is to reduce exploration. Agents should read the assigned skill docs first, use the generated tool examples directly, and avoid extra discovery calls for tools that are already documented in the skill.
File Responsibilities
AGENTS.md
Incident-manager instructions for the current run.
- Contains the incident manager prompt loaded at runtime
- Lives at the workspace root for pi-mono to read directly
- Does not need to embed tool import snippets or per-tool API details
SKILL.md
Skill instructions with an auto-generated Assigned Tools section.
- Stores YAML frontmatter and the human-authored skill prompt
- Includes assigned tools, logical names, parameter notes, and usage examples
- Shows how to call tools through
gateway_call()orexecute_script
Tool-specific examples
Generated examples reflect the actual tool assignments, not a generic static reference.
- Use the skill’s assigned logical tool name for routing
- Avoid unnecessary
list_tools_for_tool_typeorget_tool_detailcalls - Encourage direct, repeatable tool execution patterns
Assigned Tools Pattern
Generated skill docs include ready-to-use examples for the exact tools assigned to that skill, so agents can act without hunting for import paths or wrapper packages.
## Assigned Tools
Your assigned tools are listed below with full parameter schemas and gateway_call examples.
Use these examples directly — no need to call list_tools_for_tool_type or get_tool_detail for tools listed here.
Use `execute_script` to run multi-step scripts with built-in `gateway_call()` for batch operations.
### prod-zabbix (logical_name: "prod-zabbix", type: zabbix)
gateway_call("zabbix.get_problems", {"severity_min": 3}, "prod-zabbix")
SKILL.md, aligned with real assignments and rendered in the format the agent actually executes. Key Principles
Generated from real assignments
Assigned Tools content is regenerated from the skill-to-tool mapping, so docs follow what the skill can actually use.
gateway_call is the runtime interface
Examples should match the real execution path agents use in incidents, rather than an older direct-import model.
Configuration auto-loads
Tool wrappers and connectors should obtain configuration automatically; agents should not hunt for .env files or wire credentials manually.
Less discovery, more execution
Good docs should remove the need for repeated capability probing, trial-and-error routing, and unnecessary source browsing.
Generation Flow
- User assigns one or more tool instances to a skill in the UI.
- The backend regenerates
SKILL.mdwith the current Assigned Tools section. - Tool examples are rendered with logical names and per-tool guidance derived from the assignment.
- On startup, Akmatori can regenerate all skill docs to keep them synchronized.
- When an incident is created, the incident workspace gets an
AGENTS.mdfor the incident manager prompt.
Contributor Checklist
When adding a new tool type
Update the tool example generator so Assigned Tools includes the most useful gateway_call() patterns.
When changing tool behavior
Keep the generated examples aligned with the real runtime path agents use, including logical-name routing and constraints.
When debugging agent behavior
Prefer fixing the generated skill guidance so agents stop making avoidable discovery calls or poking through source files.
Troubleshooting
Assigned tools look wrong
Check the skill-to-tool assignment and regenerate skill docs so SKILL.md is rebuilt from the current mapping.
Agent is still exploring too much
Make sure the generated examples are specific enough that the agent can call the right tool directly without extra probing.
Old Quick Start snippets keep appearing
Verify legacy Quick Start content is being stripped before SKILL.md is regenerated with the new Assigned Tools format.