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

Commit it to a repository, or to one of up to three [configuration repositories](/configuration/configuration-repository) the whole organization inherits from.

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:

```text theme={null}
your-repo/
  .gitar/skills/
    migration-check/
      SKILL.md
      scripts/
        find_callers.sh
    release-notes/
      SKILL.md
```

In a repository, Gitar reads four directories, in this order:

| Directory | Notes |
| - | - |
| `.gitar/skills/` | Gitar's own. Wins a name collision |
| `.claude/skills/` | Claude Code's convention, read as-is |
| `.agents/skills/` | Codex's convention, read as-is |
| `.github/skills/` | Copilot's convention, read as-is |

Skills already under `.claude/skills/`, `.agents/skills/`, or `.github/skills/` need no second copy. Committing the same `name` under `.gitar/skills/` overrides the other directories.

Nesting works, so a monorepo can group skills by package:

```text theme={null}
.gitar/skills/
  packages/
    api/
      migration-check/
        SKILL.md
    web/
      deploy/
        SKILL.md
```

The directory holding a `SKILL.md` is the skill, so nothing inside it is read as a second one - a `references/` directory can hold an example `SKILL.md` safely.

## One Repository for the Whole Organization

Gitar supports unlimited reusable skills. Teams can share procedures across repositories, and skills load on demand.

Skills do not have to be committed into every repository. Select up to three [configuration repositories](/configuration/configuration-repository) and every repository in the organization inherits their skills.

Two extra directories are read there, `skills/` and `plugins/<plugin>/skills/`, so a marketplace repository works as-is. A repository's own skills win a name collision.

Rules and review instructions are inherited from the same repository. See [what it holds](/configuration/configuration-repository#what-it-holds).

## 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` | No | How the skill is called. Use kebab-case. Defaults to the skill's directory name |
| `description` | No | One line on when the skill applies. This is what the agent reads when deciding whether to call the skill, so write it as a trigger |
| `disable-model-invocation` | No | `true` keeps the skill out of the list the agent sees. A rule naming it still loads it |

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

Frontmatter keys Gitar does not read, like `allowed-tools` or `license`, are ignored rather than rejected, so a `SKILL.md` written for Claude Code or Copilot works unchanged.

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

```text theme={null}
gitar run the migration-check skill on this
```

Naming the skill is what calls it. Slash-command syntax does not work, so `/migration-check` does nothing.

The agent loads the skill's instructions into its own turn and follows them with the tools it already has, with the repository checked out, so a skill can read files and run scripts from its directory. It gets no MCP server and no secrets of its own, 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 that `SKILL.md` sits in one of the [supported directories](#where-skills-live). Give it a description that explains when it applies, and name the skill in a rule or PR comment.

### 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.