Skills

Skills are the context you author for your agents: what your architecture looks like, how to handle a specific alert, and how your team uses a given tool. This guide walks you through creating and organizing them.

Prerequisites

• Access to your Autoheal organization
• At least one integration connected (recommended, so you have something to document)

Where skills live

From the Autoheal sidebar, open Engineering Context → Skills. Three tabs hold the three kinds of skill:

Page	Tab	Purpose
Skills	Agent's instructions	Agents.md containing general context about your team, services, and procedures for alert and incident response
Skills	Integration Skills	How your team uses specific tools (Datadog, GitHub, etc.)
Skills	Alert skills	Step-by-step procedures for specific alerts or common issues

Your services, teams, people, and repositories live in the Catalog instead, since those are imported from your integrations rather than authored here.

Creating Your First Document

1

Select a Category Tab

Click the tab matching the type of document you want to create. For your first document, start with Alert Skills. This gives the agent step-by-step procedures for specific alerts.

2

Click New Document

Click the + button to create a new document.

3

Choose a Template

Select a template that fits your content:

• Agent's instructions - Overview of your services and environment
• Alert Skill - Procedure for a specific alert
• Integration Skill - How to use a specific tool
• Blank - Start from scratch

4

Write Your Content

Use the markdown editor to write your document. The editor supports:

• Standard markdown formatting
• Code blocks with syntax highlighting
• Tables for structured information
• Live preview

5

Save

Click Save. Your document is immediately available to your agents during investigations.

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:

# 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)

note

Memories are not authored here. Autoheal learns them automatically from past investigations, and you review them on the Memories page rather than writing them. See Agent Context for how memories work and their lifecycle. The categories above (skills and instructions) are the context you author.

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:

1. Alerts that page most frequently
2. Incidents that take longest to resolve
3. Issues that require specific tribal knowledge
4. Alerts that new team members struggle with
5. Anything you've explained more than twice

Keep It Current

Outdated documentation is worse than no documentation. 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 three documents. They'll immediately improve investigation quality:

1

Your Most Frequent Alert

Create an Alert Skill for the alert that pages most often:

• What the alert means
• Step-by-step investigation procedure
• Common causes and resolutions
• When to escalate

2

Integration Skill

Create an Integration Skill for your primary monitoring tool:

• Your tagging conventions
• Key dashboards and when to use them
• Useful log queries
• Service names in APM

LLM Review

When you save a document, 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 document 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:

1. Export or copy the content as markdown
2. Create a new document in the appropriate category
3. Paste and adjust the formatting
4. Add any missing context (specific dashboard names, commands, contacts)

tip

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:

1. Go to Investigations
2. Start a new investigation
3. Ask about something you've documented:

   How should I investigate high payment latency?

4. The agent should reference your skill in its response

If the agent doesn't find your document, check that:

• The document 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

Next Steps

Engineering Context Graph Overview

Learn how your agents use the Engineering Context Graph and how it evolves over time.