Skip to main content

3. Add a Skill

Instructions tell an agent what to do on every run. A skill holds know-how that the agent loads only when it needs it, such as review rules, a runbook or a checklist. Many agents can use the same skill.

Step 1: Add the skill​

Go to Agent Studio → Skills and click New skill. In Title, type Review rules. Autoheal makes the ID review-rules from the title. Click Create blank, or Create if you do not see Create blank.

The editor opens skills/review-rules/SKILL.md. Replace its content with this:

MARKDOWN
---
name: Review rules
description: >-
The team's rules for pull request review: what blocks a merge, how to
write a finding, and an example. Load it before you review a pull request.
labels:
- topic: code-review
---

# Review rules

Give each finding a severity:

- **Blocker**: the change can break production, lose data or expose a secret. Do not merge.
- **Should fix**: a bug risk or a missing test. Merge only after a fix or a reply from the author.
- **Nit**: style or naming. A nit never blocks a merge.

Check these rules on each pull request:

- A fix must come with a test that fails without the fix.
- A new setting must have the same name in the code and in the docs.
- A call to another service must have a timeout.
- A pull request that changes more than 400 lines must say why it is not split.

Write each finding on one line: the severity, the file and line, the problem, and the fix.

## Example

- **Should fix** `src/cart/CartStore.cs:88`: the retry loop has no limit. Stop after 3 attempts.

These rules are an example. Change them to the rules that your team uses.

Step 2: Point the agent at the skill​

Add this to the agent's agent.yaml:

YAML
skills:
- skills:review-rules

Step 3: Commit and run​

Commit your changes, and run the agent with the pull request URL from the Quick Start. In the transcript, find the load_skill call. The agent loaded the skill because the skill's description matched the job.

Check that the review now gives each finding a severity: Blocker, Should fix or Nit. Check also that the review now has a finding about the missing test. The agent finds it because the skill has a rule about tests.

What to know​

  • The folder name is the skill's ID. The description tells the agent when to load the skill, so write it as "when to use this".
  • If an agent has no skills field, it can use every skill in the project. skills: [] gives it no skills.
  • skills:x is a skill in the project's skills/ folder. ./skills:x is a skill in the agent's own folder, and only that agent can use it.
  • Keep one topic in each skill. Two short skills work better than one long skill.

Instructions or skill?​

Put it in the instructionsPut it in a skill
The agent's job, steps and rulesKnow-how that more than one agent uses
Text that applies to every runText that applies only to some runs
A few linesLong examples, tables and checklists

From the CLI​

The CLI does not create skills. Add the skill in the web app or with the Assistant, then push the agent:

BASH
autoheal agents push agents/pr-review -m "Use the review rules skill"

See Skills in the reference, and Skills in the Engineering Context Graph.