Agent Skills

Overview

Skills provide a standardized way to give Auggie specialized domain knowledge and capabilities. Following the 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:

---
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, must 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 multiple locations in order of precedence:

Location	Source	Description
`~/.augment/skills/`	User	Available in all workspaces, stored in your home directory (highest precedence)
`<workspace>/.augment/skills/`	Workspace	Project-specific skills, can be version controlled
`~/.claude/skills/`	User	Compatible with Claude Code, stored in home directory
`<workspace>/.claude/skills/`	Workspace	Compatible with Claude Code, in workspace
`~/.agents/skills/`	User	Industry-standard location, stored in home directory
`<workspace>/.agents/skills/`	Workspace	Industry-standard location, in workspace

Skills from all locations are loaded and made available to the agent. When multiple skills with the same name exist in different locations, the skill from the higher precedence location is used. The Source column in the /skills popover shows whether each skill came from your home directory (User) or the current workspace (Workspace).

Invoking Skills

In Auggie’s interactive mode, every discovered skill is registered as its own slash command using the skill’s directory name. You can invoke a skill directly without going through the /skills browser. If you have a skill at .augment/skills/my-skill/SKILL.md, you can run it by typing:

/my-skill

The skill’s instructions are submitted immediately as the current request, so the agent begins responding right away.

Browsing vs. invoking

The /skills command and the direct /<skill-name> form serve different purposes:

Command	Purpose
`/skills`	Open a browser popover that lists every loaded skill, its source, description, and estimated token count. Useful for discovering what is available.
`/<skill-name>`	Invoke a specific skill directly by typing its name as a slash command.

/skills is a discovery aid — it is not required in order to use a skill.

Built-in slash commands take precedence

If a discovered skill’s directory name matches a built-in slash command (for example, /help, /model, /skills, or another command listed under Interactive Mode Slash Commands), the built-in command runs instead of the skill. To make a skill reachable as a slash command, choose a directory name that does not collide with an existing built-in command.

Viewing loaded skills

Use the /skills slash command to view all loaded skills and their details:

/skills

This opens a popover showing:

Name: The skill identifier
Source: Where the skill was loaded from (Workspace or User)
Description: What the skill does
Tokens: Estimated token count based on the SKILL.md file size

Key	Action
`↑` / `↓` or `j` / `k`	Navigate between skills
`Enter`	Open the selected skill in your editor
`Esc`	Close the popover

The token count helps you understand the context window cost of each skill. Skills with larger instructions will consume more tokens when activated.

Creating Your First Skill

Create the skills directory

mkdir -p .augment/skills/my-skill

Create the SKILL.md file

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

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

Verify the skill is loaded

Start Auggie and use the /skills command 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

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

Overview

What are Skills?

Skill File Structure

SKILL.md Format

Required Frontmatter Fields

Skill Name Requirements

Skill Locations

Invoking Skills

Browsing vs. invoking

Built-in slash commands take precedence

Viewing loaded skills

Skills Popover Navigation

Creating Your First Skill

Skills vs Rules

Best Practices

See Also

​Overview

​What are Skills?

​Skill File Structure

​SKILL.md Format

​Required Frontmatter Fields

​Skill Name Requirements

​Skill Locations

​Invoking Skills

​Browsing vs. invoking

​Built-in slash commands take precedence

​Viewing loaded skills

​Skills Popover Navigation

​Creating Your First Skill

​Skills vs Rules

​Best Practices

​See Also

Overview

What are Skills?

Skill File Structure

SKILL.md Format

Required Frontmatter Fields

Skill Name Requirements

Skill Locations

Invoking Skills

Browsing vs. invoking

Built-in slash commands take precedence

Viewing loaded skills

Skills Popover Navigation

Creating Your First Skill

Skills vs Rules

Best Practices

See Also