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

# Agent Skills

> Extend Auggie's capabilities with specialized domain knowledge using the agentskills.io specification.

You're viewing docs for **Auggie 1.x.x**
(prerelease). To see Auggie 0.x.x, go to
[the 0.x.x docs](https://docs.augmentcode.com/cli/v0/skills.md)
.

## Overview

Skills provide a standardized way to give Auggie specialized domain knowledge and capabilities. Following the [agentskills.io](https://agentskills.io) specification, skills are modular packages of guidance, resources, and context that help the agent understand specific domains or workflows.

## What are Skills?

Skills are self-contained packages that provide:

* **Specialized knowledge**: Domain-specific guidance and best practices
* **Contextual resources**: Links to documentation, APIs, or tools
* **Workflow patterns**: Step-by-step procedures for common tasks
* **Tool usage guidance**: How to use specific tools or frameworks

Unlike rules (which provide general guidelines), skills are designed to be:

* **Discoverable**: The agent can see what skills are available through their metadata
* **Modular**: Each skill is independent and can be added or removed easily
* **Standardized**: Following the agentskills.io spec ensures compatibility across AI tools

## Skill File Structure

Skills are defined in `SKILL.md` files located in the `.augment/skills/`, `.claude/skills/`, or `.agents/skills/` directories (in either your workspace or home directory). Each skill must be in its own subdirectory:

```
.augment/skills/
  ├── python-testing/
  │   └── SKILL.md
  ├── api-design/
  │   └── SKILL.md
  └── database-migrations/
      └── SKILL.md
```

### SKILL.md Format

Each `SKILL.md` file must include YAML frontmatter with required metadata:

**Example SKILL.md file:**

```markdown theme={null}
---
name: python-testing
description: Best practices for writing and running Python tests with pytest
---

# Python Testing Skill

This skill provides guidance on writing effective Python tests.
```

The file content after the frontmatter can include:

* Markdown headings and text
* Code examples (using code blocks)
* Lists and other markdown formatting

### Required Frontmatter Fields

| Field | Description | Requirements |
| :- | :- | :- |
| `name` | Skill identifier | 1-64 characters, lowercase alphanumeric and hyphens only, should match directory name |
| `description` | What the skill does and when to use it | 1-1024 characters, helps the agent understand when to apply the skill |

### Skill Name Requirements

Per the agentskills.io specification, skill names must:

* Be 1-64 characters long
* Use only lowercase letters, numbers, and hyphens
* Not start or end with a hyphen
* Not contain consecutive hyphens
* Match the directory name containing the SKILL.md file

**Valid names**: `python-testing`, `api-design`, `database-migrations`\
**Invalid names**: `Python-Testing`, `api_design`, `-database`, `my--skill`

## Skill Locations

Skills are discovered from these locations, in order of precedence:

| Location | Source | Description |
| :- | :- | :- |
| `~/.augment/skills/` | User | Available in all workspaces (highest precedence) |
| `<workspace>/.augment/skills/` | Workspace | Project-specific skills, can be version controlled |
| `~/.claude/skills/` | User | Compatible with Claude Code |
| `~/.agents/skills/` | User | Industry-standard location |
| `.augment/skills/`, `.claude/skills/`, `.agents/skills/` in the current directory and its parents | Workspace | Searched up to the git repository root |

Skills from all locations are loaded and made available to the agent. When multiple skills with the same name exist, the skill from the higher precedence location is used.

You can also load skills from other paths:

* Pass `--skill <path>` to load a skill file or directory for one run. Repeat the flag to add more.
* Add paths to the `skills` array in [`settings.json`](https://docs.augmentcode.com/cli/settings).
* Use `--no-skills` to turn off discovery. Skills passed with `--skill` still load.

## Invoking Skills

In interactive mode, every discovered skill is registered as a slash command named `/skill:<name>`. If you have a skill at `.augment/skills/my-skill/SKILL.md`, run it by typing:

```
/skill:my-skill
```

Any text after the command is passed to the skill along with its instructions:

```
/skill:my-skill focus on the payments module
```

Type `/skill:` to see the available skills and their descriptions in the autocomplete list. To turn off skill commands, set `enableSkillCommands` to `false` in `settings.json`.

You don't have to invoke a skill yourself. The agent sees each skill's name and description and loads the full `SKILL.md` when a task matches.

## Creating Your First Skill

**1. Create the skills directory**

```bash theme={null}
mkdir -p .augment/skills/my-skill
```

**2. Create the SKILL.md file**

Create a file at `.augment/skills/my-skill/SKILL.md` with the following content:

```markdown theme={null}
---
name: my-skill
description: Custom skill for my project's specific workflow
---

# My Custom Skill

Add your skill content here with guidance, examples, and resources.
```

**3. Verify the skill is loaded**

Start Auggie and type `/skill:` to confirm your skill appears in the list.

## Skills vs Rules

While both skills and rules provide guidance to the agent, they serve different purposes:

| Feature | Skills | Rules |
| :- | :- | :- |
| **Purpose** | Specialized domain knowledge | General coding guidelines |
| **Format** | agentskills.io specification | Markdown with optional frontmatter |
| **Discovery** | Metadata-based (name + description) | Content-based or always-applied |
| **Scope** | Specific domains/workflows | Project-wide conventions |
| **Standard** | Cross-platform (agentskills.io) | Augment-specific |

Use **skills** for:

* Framework-specific knowledge (e.g., React patterns, Django best practices)
* Tool usage guides (e.g., Docker workflows, CI/CD procedures)
* Domain expertise (e.g., security practices, performance optimization)

Use **rules** for:

* Code style preferences
* Project architecture guidelines
* Team conventions

## Best Practices

1. **Be Specific**: Focus each skill on a single domain or workflow
2. **Include Examples**: Provide concrete code examples and commands
3. **Keep Updated**: Review and update skills as tools and practices evolve
4. **Use Clear Descriptions**: Help the agent understand when to use each skill
5. **Version Control**: Commit workspace skills to share with your team

## See Also

* [agentskills.io Specification](https://agentskills.io/specification) - Official skill format specification
* [Example Skills](https://github.com/anthropics/skills) - Collection of example skills from Anthropic
* [Rules & Guidelines](https://docs.augmentcode.com/cli/rules.md) - Configure general project guidelines
* [CLI Reference](https://docs.augmentcode.com/cli/reference.md) - Complete command-line reference


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