Skills
A skill is a set of instructions that you write to tell the agent how to investigate one kind of problem. The agent reads the skills that are relevant to an incident. Every connected tool is available to every skill.
What a skill is
Each skill is a SKILL.md file: YAML frontmatter with the name and description, then Markdown instructions for the agent. Create a skill with Skills → New skill, or put a directory with a SKILL.md in the skills directory and press Sync. The agent sees the name and description of every enabled skill and reads the full instructions when a skill is relevant.
Akmatori adds two generated sections to the end of each SKILL.md: the memory manifest of the skill's scope, and a pointer to connected-tools/SKILL.md, the generated list of every enabled tool with gateway_call(...) examples. Do not put credentials in a skill: the MCP Gateway adds them when it runs a tool.
SKILL.md format
An example skill:
---
name: investigate-high-cpu
description: Investigate and diagnose high CPU usage alerts
---
# Investigation instructions
When receiving a high CPU alert, follow these steps:
1. Confirm the affected host and service from the alert payload
2. Use the SSH and monitoring tools from connected-tools/SKILL.md through gateway_call
3. Check CPU, memory, recent deploys, and relevant runbooks
4. Summarize findings and recommend next steps
## Expected output
Provide a structured report with:
- Root cause analysis
- Affected services
- Recommended remediation stepsFrontmatter fields
nameRequiredUnique skill name in kebab-case, up to 64 characters (for example zabbix-analyst). It is also the name of the skill's directory.
descriptionRequiredWhat the skill does. The agent uses it to decide when the skill is relevant, so name the systems and symptoms it covers.
metadataGeneratedAkmatori writes metadata.short-description, the description cut to 50 characters. It rewrites the frontmatter with only name, description and metadata, so other keys, such as version, are dropped.
toolsNot usedTools are not assigned to skills. Every enabled connector is available to every skill, and the generated connected-tools skill lists them.
Connected tools
You do not give tools to a skill. Every enabled connector, including custom MCP servers and HTTP connectors, is available to every incident run. Akmatori generates the system skill connected-tools, which lists each enabled tool instance with its logical name, parameters and gateway_call examples. It regenerates the skill when a connector changes. You cannot edit or disable this skill. To keep a tool from the agent, disable its tool instance. The old /api/skills/:name/tools endpoints return 410 Gone.
- Use `execute_script` with its built-in `gateway_call()` for batch operations.
## ssh
### ssh-production (logical_name: "prod-ssh", type: ssh)
**Parameters:**
- `execute_command`: command* | servers
- `test_connectivity`: servers
- `get_server_info`: servers
(* = required)
Usage (via gateway_call):
```
gateway_call("ssh.execute_command", {"command": "uptime"}, "prod-ssh")
gateway_call("ssh.test_connectivity", {}, "prod-ssh")
```Best practices
Be specific
Name the systems, checks and expected output. Write steps the agent can follow, not general advice.
Add context files
Upload reference documents (architecture notes, configs, inventories) on the Context Files page and refer to them in a skill with [[filename]]. Put procedures in Runbooks.
Test before you rely on it
Ask the agent about a known problem, for example with a Slack mention, and read the run log to check that it used the skill.