Skills
Skills are the procedures your agents follow. They describe what your architecture looks like, how to handle a specific alert, and how your team uses a given tool. You write or import them, and the Healer can propose changes to them for your approval. This guide shows how to create and organize them.
Prerequisites
- Access to your Autoheal organization
- At least one integration connected (recommended, so you have something to document)
Where skills live
Go to Agent Studio → Skills. The page is a table of your project's Git skills, with three columns:
| Column | What it shows |
|---|---|
| Skill | The title, the folder name (the skill's id), the description and the labels. If the skill has an error, a line under it shows the error. An agent that leaves skills out of its definition skips a skill that has an error. An agent that lists the skill still gets it, together with the problems. |
| Runs 30d | How many runs in the last 30 days loaded the skill, and how many agents those runs belong to. Only the runs of this project's agents count. |
| Last changed | When the last commit to the skill's folder was made, and who made it. A sparkle shows a commit that the Assistant or one of Autoheal's agents made. When you commit your own editor changes together with changes the Assistant made, the commit shows as the Assistant's. The column reads only recent Git history: a skill changed before that shows Before recent history. For an imported skill, the column shows the project that owns it. |
Search finds a skill by its title, id or description. Filters narrows the list by Labels, Changed by, Not loaded in 30 days and Has errors. Skills saved outside Git (built-in skills such as the Architecture Overview, older custom skills, imported skills and old integration guides) show only when you click Filters → Show legacy skills.
The types of skill are:
| Type | What it is |
|---|---|
| Built-in | Skills that ship with Autoheal, such as the Architecture Overview |
| Integration skill | How your team uses a specific tool, such as Datadog or GitHub. It is the Git skill skills/<integration>/SKILL.md, labelled integration: <integration> |
| Custom | Skills you write, such as a procedure for a specific alert |
| Imported | Skills synced from a repository, such as a .claude/skills folder |
Skills are stored in Autoheal. Autoheal reads imported skills from your repository on import, when you click Refresh now, and once a day. Autoheal doesn't write to that repository.
Services, teams, people, and repositories are entities in the Context Graph. Label a skill with an entity's blueprint and canonical name, such as service: payments-api, to connect the skill to it. A Git-backed skill keeps these labels in its SKILL.md frontmatter, as - key: value items; repeat a key for each of its values.
Creating your first skill
- Click New skill
On the Skills page, click New skill. The Add a Skill dialog opens.
- Name the skill
Give the skill a display title. The skill's id is generated from the title. Click Create, and the skill opens as a new file in the agent workspace.
- Write your content
Write in markdown. For your first skill, document one alert your team handles often: how to recognize it, how to investigate it, and when to escalate.
- Save
Commit the skill from the workspace. Your agents can use it once it is committed. Changes the Healer proposes, by contrast, wait for an engineer's review before they apply.
Write a skill as a file
You can also write a skill as a file and push it with the Autoheal CLI. A skill is a folder that contains a SKILL.md file. The folder name is the skill's identifier. SKILL.md starts with YAML front matter that has two fields:
name: the display title.description: what the skill is for and when to use it.
The rest of the file is the procedure, in Markdown:
---
name: Dependency fix ranking
description: How to rank vulnerable dependencies by fix priority. Use it when you rank scan results.
---
# Dependency fix ranking
1. Rank by severity first, then by whether a fixed version exists.
2. Put a package that several repositories use before one that only one repository uses.
3. For each package, give the advisory ID and the lowest fixed version.
The skill folder can be in one of two places:
| Location | Reference in agent.yaml | Which agents can use it |
|---|---|---|
skills/<name>/SKILL.md at the project root | skills:<name> | Every agent in the project. Create it with New skill on the Skills page. |
agents/<agent>/skills/<name>/SKILL.md, inside an agent's folder | ./skills:<name> | Only that agent. Push it with the agent. |
To add a skill to one agent, put the skill folder in the agent's folder:
agents/
dependency-ranker/
agent.yaml
skills/
dependency-fix-ranking/
SKILL.md
Refer to the skill in agent.yaml:
skills:
- ./skills:dependency-fix-ranking
Then push the agent folder:
autoheal agents push agents/dependency-ranker
autoheal agents push commits the whole agent folder, including the skill, and prints any errors. The agent sees each skill's reference and description. It loads the full skill with its load_skill tool when it decides that the skill is relevant. For more about the skills field, see the Agent and Trigger Reference.
Document Categories
Architecture Overview Skill
The Architecture Overview is a built-in skill that tells Autoheal how your production system fits together. It should be short, current, and opinionated enough that an on-call engineer could read it before debugging an unfamiliar service.
Autoheal reads this skill during investigations, so use it for context that applies across many incidents rather than one-off remediation steps. What to include:
- Core services, ownership, and the customer-facing capabilities they support
- Important dependencies, queues, databases, caches, and third-party APIs
- Environment names, regions, deployment topology, and how to identify them in logs or alerts
- Critical request flows, background jobs, and asynchronous handoffs
- Operational gotchas your team already knows to check during incidents
Update the overview when architecture, ownership, deployment shape, or investigation assumptions change. For incident-specific steps, create a separate alert skill so the Architecture Overview stays easy to scan.
Alert Skills
Procedures for specific alerts. Include what the alert means, how to investigate, and how to resolve:
# High Payment Latency
## What This Means
Payment API p99 latency exceeded 500ms for 5+ minutes.
## Investigation Steps
1. Open "Payments Deep Dive" dashboard in Datadog
2. Check if latency is isolated to specific endpoints
3. Look for correlation with database latency
## Common Causes
- Database connection pool exhaustion
- Downstream payment provider issues
- Recent deployment regression
## Resolution
- If database: Scale API replicas or kill long-running queries
- If provider: Check status.stripe.com, enable fallback
- If deployment: Roll back with `kubectl rollout undo`
Integration Skills
How your team uses specific tools, such as dashboards, queries, and tagging conventions. Each integration has one integration skill, the Git skill skills/<integration>/SKILL.md with the label integration: <integration>. Agents load it when they work with that integration.
To write it, open the integration's page and go to the Skill tab. Click Write it with the Assistant, or open the skill in the editor. The Assistant shows you the commit, and you approve it before it is saved.
An integration guide saved before integration skills were Git skills shows on the Skills page as Old guide when you click Filters → Show legacy skills. Older agents still read it. To keep what it says, click Move to a Git skill on the guide's page or on the integration's Skill tab. The Assistant merges the guide into skills/<integration>/SKILL.md and keeps what people wrote there. When you have approved the commit, delete the old guide.
An integration skill can look like this:
# How We Use Datadog
## Tagging Convention
- `env:production`, `env:staging`
- `service:<service-name>`
- `team:platform`, `team:payments`
## Useful Log Queries
- All errors: `status:error env:production`
- Payment failures: `service:payments-api @error.type:PaymentFailed`
## APM Services
- `payments-api-prod` (production payments)
- `user-service-prod` (production auth)
Memories are not authored here. Autoheal learns them automatically from past agent runs, and you review them on the Memories page rather than writing them. See Memories for how memories work and their lifecycle. Skills are the context you author or approve.
Writing Effective Documents
Be Specific
The agent can't use vague guidance. Instead of "check the dashboard," write "open the 'Platform Team Overview' dashboard in Datadog."
Vague: Check the logs for errors.
Specific: Run this Datadog query: service:payments-api status:error env:production
Include Commands
Copy-paste-ready commands help both the agent and tired on-call engineers:
# Roll back the payments-api deployment
kubectl rollout undo deployment/payments-api -n production
# Check current replica count
kubectl get deployment payments-api -n production
Explain Why
Don't just document what to do. Explain why. This helps the agent make better decisions in novel situations:
"Check the batch job schedule first because time-correlated latency issues are often caused by scheduled jobs competing for database connections."
Name Names
Include specific contacts, channels, and escalation paths:
- Slack: #payments-oncall
- Escalation: @jane-smith (payments lead)
- PagerDuty: Platform → SRE → Engineering Manager
Start With Your Top 5 Alerts
Don't try to document everything at once. Start with:
- Alerts that page most frequently
- Incidents that take longest to resolve
- Issues that require specific tribal knowledge
- Alerts that new team members struggle with
- Anything you've explained more than twice
Keep It Current
Outdated documentation is worse than no documentation. The Evaluator flags runs that went wrong. The Healer proposes skill changes for you to review. But you know about changes before any run does. After each incident:
- Update skills that didn't fit
- Remove steps that no longer apply
- Add discoveries from the investigation
- Mark deprecated services or dashboards
Recommended First Documents
Start with these two skills, alongside the built-in Architecture Overview:
- Your Most Frequent Alert
Create a Custom skill for the alert that pages most often:
- What the alert means
- Step-by-step investigation procedure
- Common causes and resolutions
- When to escalate
- Integration Skill
Write the integration skill,
skills/<integration>/SKILL.md, for your primary monitoring tool. Include:- Your tagging conventions
- Key dashboards and when to use them
- Useful log queries
- Service names in APM
To let the Assistant write it, open the integration's page, go to the Context tab and click Set up with the Assistant. The Assistant examines the connection, asks you for the facts it cannot find, and shows you the skill to approve before it saves it as
skills/<integration>/SKILL.md.
LLM Review
When you save a skill, Autoheal generates a review with suggestions for improvement. You'll see feedback like:
- Questions about missing information
- Suggestions for more specific commands
- Recommendations for better organization
Review the feedback and update your skill as needed. This helps ensure your engineering context is as useful as possible.
Importing Existing Documentation
If you have existing skills in Confluence, Notion, or a Git repository:
- Export or copy the content as markdown
- Create a new skill of the appropriate type
- Paste and adjust the formatting
- Add any missing context (specific dashboard names, commands, contacts)
Don't try to migrate everything at once. Start with your most critical skills, the ones that get used during real incidents. Expand from there based on what gaps you notice during investigations.
Verifying Your Setup
Test that your skills are working:
- Go to Investigations
- Start a new investigation
- Ask about something you've documented:
How should I investigate high payment latency? - The agent should reference your skill in its response
If the agent doesn't find your skill, check that:
- The skill was saved successfully
- The content includes the keywords you're asking about
- You're asking in a way that matches how you described the issue