Skip to main content

​
About Skills

Skills are reusable knowledge packages that extend the agent with domain-specific expertise — deployment guides, debugging playbooks, framework best practices, and more. Each skill is a self-contained skill folder with a markdown file that provides specialized instructions the agent can draw on during conversations. Skills follow the agentskills.io specification, ensuring compatibility across AI tools.

​
Creating a Skill

Each skill lives in its own named directory containing a markdown file that shares the name of the directory: 
cosmos/files/organization/.augment/skills/
  ├── python-testing/
  │   └── python-testing.md
  ├── api-design/
  │   └── api-design.md
  └── deploy-guide/
      └── deploy-guide.md

​
Markdown Format

Each markdown file must include YAML frontmatter with a name and description, followed by markdown content with instructions: 
---
name: deploy-guide
description: Step-by-step deployment procedures for our production infrastructure
---

# Deployment Guide

## Pre-deployment Checklist
1. Run all tests with `npm test`
2. Verify environment variables are set
3. Check database migrations are up to date

## Deploying to Production
...

​
Frontmatter Fields

FieldDescriptionRequirements
nameSkill identifier1–64 characters, lowercase alphanumeric and hyphens only, must match directory name
descriptionWhat the skill does and when to use it1–1024 characters

​
Skill Name Requirements

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 markdown file
Valid names: python-testing, api-design, deploy-guide Invalid names: Python-Testing, api_design, -deploy, my--skill

​
Skill Locations

Skills are discovered from multiple locations in order of precedence:
LocationScopeDescription
cosmos/files/organization/.augment/skills/OrganizationAvailable to all users in your Organization (highest precedence)
cosmos/files/user/.augment/skills/UserPrivate to you across all sessions
<repo>/<workspace>/.claude/skills/ProjectCompatible with Claude Code
<repo>/<workspace>/.agents/skills/ProjectIndustry-standard location
When multiple skills with the same name exist in different locations, the skill from the higher-precedence location is used.

​
Getting Started

1

Create a directory to host your skill

Navigate to Files > Organization > .augment > skills and create a new directory for your skill.
2

Create the my-skill.md file

Upload a markdown file to directory using the Upload File button:
---
name: my-skill
description: Custom skill for my project workflow
---

# My Custom Skill

Add your domain-specific guidance, examples, and instructions here.
3

Use the skill

The skill will be discovered automatically and injected into your Expert’s context.

​
Best Practices

  1. Focus each skill on a single domain — keep skills modular and specific
  2. Include concrete examples — provide code samples and commands
  3. Write clear descriptions — help the agent understand when to apply each skill

​
See Also