> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Commit a procedure to your repository and call it from a rule or a PR comment

## Overview

A skill is a markdown file of instructions in your repository. Call it by name from a rule or a PR comment and the agent follows it, so the procedure lives in one file instead of being repeated in every rule.

Use a skill when you want to give the agent a procedure, not a server. A [custom integration](/integrations/custom-integrations) is an MCP server the agent calls. A skill is instructions, plus any scripts you keep next to them.

<CardGroup cols={2}>
  <Card title="Versioned With Your Code" icon="code-branch">
    A skill changes on the branch that changes the procedure
  </Card>

  <Card title="No Setup" icon="bolt">
    Commit `SKILL.md` and the next run finds it
  </Card>

  <Card title="Called On Demand" icon="feather">
    Costs nothing on the runs that do not use it
  </Card>

  <Card title="Runs Your Scripts" icon="terminal">
    A skill can run scripts you keep in its directory
  </Card>
</CardGroup>

<Note>
  Skills are available on the **Pro** and **Enterprise** plans, alongside [repository rules](/features/rules).
</Note>

## Where Skills Live

Each skill is a directory with a `SKILL.md` inside:

```
your-repo/
  .gitar/skills/
    migration-check/
      SKILL.md
      scripts/
        find_callers.sh
    release-notes/
      SKILL.md
```

Gitar reads `.gitar/skills/` and `.claude/skills/`, one level deep. A `SKILL.md` nested deeper is not found. On a name collision `.gitar/skills/` wins, and an enabled integration whose slug matches a skill `name` wins over the skill — pick a name no integration uses.

## Writing a Skill

Frontmatter, then the instructions:

```markdown theme={null}
---
name: migration-check
description: Verify a database migration is reversible and safe to run against production
---

# Migration Check

When a PR adds a file under `db/migrations/`:

1. Confirm the migration has a `down` step, or a comment saying why it cannot.
2. Run `scripts/find_callers.sh <table>` to list the code paths that read the
   affected table.
3. Flag any column drop or rename that ships in the same PR as code reading it,
   since the deploy is not atomic.

Report each problem with the file and line. Say nothing when the migration is clean.
```

| Field         | Required | Description                             |
| ------------- | -------- | --------------------------------------- |
| `name`        | Yes      | How the skill is called. Use kebab-case |
| `description` | No       | One line on when the skill applies      |

The body goes to the agent as written, so write instructions to follow, not documentation.

<Warning>
  `name` comes from the frontmatter, not the directory. A `SKILL.md` with no `name` is skipped.
</Warning>

## Calling a Skill

Name the skill in a rule:

```markdown theme={null}
---
title: "Migration Safety"
description: "Check database migrations before they merge"
when: "PRs that add or modify files under db/migrations/"
actions: "Comment with any reversibility or ordering problems"
---

# Migration Safety

When a PR touches `db/migrations/`, use the `migration-check` skill and post
its findings as a review comment. Say nothing when the migration is clean.
```

Or ask on any PR:

```
gitar run the migration-check skill on this
```

Naming the skill is what calls it. There is no slash-command syntax, so `/migration-check` does nothing.

A skill runs on its own, with the repository checked out, so it can run scripts from its directory. It gets no MCP server and no secrets, so anything that has to reach an external system belongs in a [custom integration](/integrations/custom-integrations).

<Note>
  A skill runs only when something calls it. To change what code review looks for on every PR, use [`.gitar/review/`](/configuration/repository-config#custom-review-instructions).
</Note>

## When to Use a Skill

| You want                              | Use                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------- |
| Guidance on every PR                  | [`.gitar/review/`](/configuration/repository-config#custom-review-instructions) |
| A procedure the agent runs when asked | A skill                                                                         |
| A workflow that fires on a condition  | A [rule](/features/rules)                                                       |
| To read or write an external system   | A [custom integration](/integrations/custom-integrations)                       |

Review instructions load on every run and you pay for them every run. A skill loads only when called, so a long procedure belongs in one.

## Frequently Asked Questions

### Why is my skill not being used?

Check the file is `SKILL.md`, that it sits one directory under `.gitar/skills/` or `.claude/skills/`, and that the frontmatter has a `name`. After that, the usual cause is that nothing named it.

### Can a skill use my Jira or Slack credentials?

No. A skill is instructions and scripts, with no secrets of its own. Let the skill decide what should happen and let the rule call the integration.

### Can a skill span more than one file?

Yes. Only `SKILL.md` is read up front, but the rest of the directory is checked out, so a skill can point at `references/schema.md` or run `scripts/check.sh`.