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

# Skills

> Teach Synti's agent reusable procedures with markdown SKILL.md instruction files it can invoke on demand or automatically.

Skills are how you teach Synti's agent to do something your way, repeatably. A skill is a `SKILL.md` file—plain markdown instructions with a little metadata—that the agent adds to its toolkit. Once a skill exists, the agent draws on it automatically when a task matches, or you can invoke it directly with an `@mention`. Think of a skill as a saved procedure: "how we write commit messages," "how we run a release," "how we review authentication changes."

Synti's skills follow the open Agent Skills standard, so a `SKILL.md` written for Synti is compatible with other tools that support the same format.

## Creating a skill

The easiest way to make one is to ask:

> "Create a skill called `commit` that writes conventional commit messages."

The agent knows where skills live and how they're formatted, so it writes the `SKILL.md` for you—name, description, and instructions included. You can then refine the file by hand.

## File layout

Each skill is a folder inside your [workspace](/go-further/workspaces):

```text theme={null}
~/.synti/workspaces/{workspace-id}/skills/{slug}/
├── SKILL.md     # required: frontmatter + instructions
└── icon.png     # optional: cached icon
```

`SKILL.md` is YAML frontmatter followed by markdown. The frontmatter sets metadata and when the skill activates; the body is the instructions the agent follows.

```markdown SKILL.md theme={null}
---
name: commit
description: Write a conventional commit message for staged changes.
icon: ✅
---

When asked to commit, inspect the staged diff and write a message in
conventional-commit format (feat:, fix:, docs:, chore:, etc.).

- Summarize the change in the subject line, under 72 characters.
- Add a short body explaining the "why" when the change isn't obvious.
- Never commit unrelated changes together.
```

## Frontmatter fields

| Field             | Required | Purpose                                                            |
| ----------------- | -------- | ------------------------------------------------------------------ |
| `name`            | Yes      | Display identifier for the skill                                   |
| `description`     | Yes      | Short summary shown in skill listings and used to decide relevance |
| `icon`            | No       | Emoji or URL shown next to the skill                               |
| `globs`           | No       | File patterns that trigger the skill automatically                 |
| `alwaysAllow`     | No       | Tools pre-authorized while the skill runs                          |
| `requiredSources` | No       | Sources enabled automatically when the skill is invoked            |

## How the agent uses skills

There are two ways a skill comes into play.

<Steps>
  <Step title="Automatically">
    When your request matches a skill's `description`—or you're touching files that match its `globs`—the agent applies the skill on its own, without being asked.
  </Step>

  <Step title="By mention">
    Invoke a skill directly by name with `@`:

    ```text theme={null}
    @commit
    @review the authentication changes
    @deploy to staging
    ```

    Mentioning a skill guarantees the agent uses it for that turn.
  </Step>
</Steps>

## Pre-authorizing tools and sources

Two frontmatter fields make skills run smoothly:

* **`alwaysAllow`** lists tools the agent may use during the skill without stopping to ask, so a well-scoped skill runs without repeated approval prompts. It works alongside your [Permissions](/core-concepts/permissions) settings.
* **`requiredSources`** names [sources](/sources/overview) to enable for the session the moment the skill is invoked. The agent has those tools available from the first turn—no manual authentication mid-task. A `deploy` skill might declare your CI [MCP server](/sources/mcp-servers/overview), for example.

## Overriding built-in skills

Workspace skills take precedence over built-in ones. To customize built-in behavior, create a skill with the same slug in your workspace—Synti uses your version instead. This lets you tailor default procedures to your team's conventions without losing the ability to fall back later.

<Tip>
  Keep each skill focused on one job with a crisp `description`. A precise description is what lets the agent recognize when the skill applies, so tight scoping makes automatic activation more reliable.
</Tip>