---
name: augment
description: Use when building AI-driven software development automations, setting up code review workflows, implementing ticket-to-PR pipelines, or configuring agents to handle SDLC tasks like PR authoring, code review, incident investigation, and feedback triage. Reach for this skill when a user wants to automate engineering workflows, configure Cosmos agents, or integrate development tools with AI agents.
metadata:
    mintlify-proj: augment
    version: "1.0"
---

# Augment Code Skill

## Product Summary

Augment Code is an AI-native platform for enterprise software engineering. It provides two main entry points: **Cosmos** (cloud-hosted agents that react to events and run on schedules) and **Auggie CLI** (terminal-based agent for interactive work and automation). Agents run in environments (cloud VMs or self-hosted daemons), access repositories and tools through integrations, and execute work triggered by GitHub, Linear, Slack, PagerDuty, webhooks, or cron schedules. Key files: `.augment/settings.json` (CLI config), `.augment/skills/` (knowledge packages), `cosmos/files/` (shared files and skills). Primary docs: https://docs.augmentcode.com

## When to Use

Reach for this skill when:
- A user wants to automate code review, PR authoring, ticket management, or incident investigation
- You need to set up a Cosmos Expert (reusable agent) or configure a trigger (GitHub event, schedule, webhook)
- You're building a Software Factory workflow (requirements → ticket → PR → merge → production feedback)
- A user asks to configure integrations (GitHub, Linear, Slack, PagerDuty, GitLab)
- You need to use Auggie CLI for interactive agent work or non-interactive automation
- You're creating skills (domain-specific knowledge packages) or MCP servers (external tool integrations)
- A user wants to debug automation runs, inspect event logs, or tune trigger filters

## Quick Reference

### Cosmos Core Concepts

| Concept | Purpose |
|---------|---------|
| **Expert** | Reusable agent template with system prompt, capabilities, environment, model, and triggers |
| **Environment** | VM (cloud or self-hosted daemon) where agents run; includes repos, toolchain, secrets |
| **Trigger** | Event binding (GitHub, Linear, Slack, schedule, webhook) that launches an Expert session |
| **Capability** | Tool bundle (GitHub, Slack, Linear, web access, MCP servers) an Expert can use |
| **Skill** | Reusable knowledge package (agentskills.io format) providing domain expertise |
| **Session** | Single conversation with an Expert; accessible from web, mobile, Slack |
| **Automation** | Persistent rule binding a trigger to an Expert; fires repeatedly on matching events |

### Auggie CLI Quick Commands

```bash
auggie login                          # Authenticate to Augment
auggie "your prompt"                  # Interactive session (TUI mode)
auggie --print "your prompt"          # Non-interactive; print result to stdout
auggie --print --quiet "prompt"       # Quiet mode; only final output
auggie /config                        # Open configuration wizard (interactive mode)
auggie daemon                         # Start self-hosted daemon on this machine
auggie command list                   # List custom commands
auggie mcp add <server>               # Add MCP server
auggie skills list                    # List available skills
```

### Trigger Types (Cosmos)

| Type | Source | Fires On | Filter |
|------|--------|----------|--------|
| **GitHub** | GitHub App | PR, push, review, issue, comment, workflow | JSONLogic on event payload |
| **Linear** | Linear app | Issue, comment, project (create/update/remove) | JSONLogic on event payload |
| **Slack** | Slack app | @-mention, message | JSONLogic on event payload |
| **GitLab** | GitLab project | Push, MR, issue, note, pipeline | JSONLogic on event payload |
| **PagerDuty** | PagerDuty integration key | Incident (triggered/acknowledged/resolved) | JSONLogic on event payload |
| **Scheduled** | Cron expression | 5-field cron in specified timezone | None (no payload) |
| **Webhook** | Custom HTTPS endpoint | Any service that POSTs JSON | JSONLogic on event payload |

### Configuration Files (Auggie CLI)

| File | Scope | Purpose |
|------|-------|---------|
| `~/.augment/settings.json` | User (global) | Personal defaults across projects |
| `<workspace>/.augment/settings.json` | Project (shared) | Team-shared config; commit to git |
| `<workspace>/.augment/settings.local.json` | Project (personal) | Personal overrides; auto-gitignored |
| `/etc/augment/settings.json` (macOS/Linux) | Managed (read-only) | Admin-enforced settings |

### Template Experts (Pre-built)

| Expert | Purpose |
|--------|---------|
| **PR Author** | Implement ticket → open PR → handle review/CI/conflicts |
| **PR Fixer** | Repair review findings, CI failures, merge conflicts on existing PRs |
| **Deep Reviewer** | Line-by-line correctness review (non-interactive) |
| **Pair Reviewer** | Interactive review focusing on design, security, architecture |
| **Risk Analyzer** | Auto-approve low-risk changes; route high-risk to humans |
| **Verifier** | Test changes against running environment; report findings |
| **Ticket Manager** | Own Linear/Jira/GitHub tickets from readiness through closure |
| **Ticket Dispatcher** | Scan ready work; dispatch implementation workers |
| **Incident Investigator** | Investigate alerts; summarize findings and actions |
| **Feedback Triager** | Classify Slack feedback; create tickets or launch fixes |
| **Project Builder** | Turn feature brief into design and ordered ticket breakdown |

## Decision Guidance

### When to Use Cosmos vs Auggie CLI

| Scenario | Use Cosmos | Use Auggie CLI |
|----------|-----------|----------------|
| Automated PR review on every GitHub event | ✓ (trigger + Expert) | |
| Interactive debugging in terminal | | ✓ (interactive mode) |
| Scheduled daily report generation | ✓ (cron trigger) | ✓ (--print in cron job) |
| One-off code analysis | | ✓ (--print --quiet) |
| Team-wide automation with UI dashboard | ✓ | |
| Local development with context engine | | ✓ |
| Incident response workflow | ✓ (webhook trigger) | ✓ (manual invocation) |

### When to Use Cloud Environment vs Self-Hosted Daemon

| Factor | Cloud | Self-Hosted |
|--------|-------|-------------|
| Reproducibility needed | ✓ | |
| Local network access required | | ✓ |
| Regulated data (can't leave premises) | | ✓ |
| Custom hardware (GPU, Mac mini) | | ✓ |
| Scaling across team | ✓ | |
| Persistence between sessions | | ✓ |
| Cost model | Per-minute uptime | No additional cost |

### When to Use Template Expert vs Custom Expert

| Condition | Template | Custom |
|-----------|----------|--------|
| Workflow matches PR authoring, code review, ticket management | ✓ | |
| Workflow is team-specific or combines systems uniquely | | ✓ |
| Want automatic prompt improvements from Augment | ✓ | |
| Need full control over system prompt | | ✓ |
| Integrations are standard (GitHub, Linear, Slack) | ✓ | |
| Need custom integrations or MCP servers | | ✓ |

## Workflow

### Setting Up a Cosmos Automation (Event-Driven)

1. **Connect integrations** — Go to Cosmos Settings > Integrations. Connect GitHub, Linear, Slack, or other sources the Expert will read from or write to.

2. **Create or pick an Expert** — Use a Template Expert (PR Author, Ticket Manager, etc.) or create a Custom Expert with a system prompt, environment, and capabilities.

3. **Add a trigger** — Open Automations > Create automation. Pick the Expert, then Add trigger. Choose trigger type (GitHub, Linear, Slack, schedule, webhook). Set event type and optional JSONLogic filter.

4. **Validate the filter** — Open Event Log under Automations. Filter by source and event type. Paste your JSONLogic filter into Advanced Filter to see which real events match. Adjust until the filter captures exactly what you want.

5. **Test manually first** — Start a session with the Expert directly (don't use the trigger yet). Send it a representative event payload or task. Verify the output before automating.

6. **Enable the trigger** — Save the trigger. It's off by default. Test it against a real event (e.g., open a PR if the trigger is GitHub). Once confirmed, the trigger stays on.

7. **Monitor run history** — Open Automations > Run History. Click into a session to see what the Expert did, what tools it called, and any errors.

### Setting Up a Scheduled Automation (Cron-Based)

1. **Create an Expert** with the capabilities it needs (GitHub, Slack, Linear, etc.).

2. **Add a scheduled trigger** — Open Automations > Create automation. Pick the Expert. Add trigger > Scheduled. Enter a 5-field cron expression (e.g., `0 9 * * 1-5` for 9 AM weekdays) and pick a timezone.

3. **Test the Expert** — Start a manual session and verify it produces the right output.

4. **Enable the trigger** — Save. The Expert runs on the schedule without further input.

### Using Auggie CLI for Automation

1. **Install and authenticate** — `npm install -g @augmentcode/auggie`, then `auggie login`.

2. **Run interactively** — `auggie "your prompt"` opens the TUI. Use `/config` to customize settings, `/task` to manage multi-step work.

3. **Run non-interactively** — `auggie --print "your prompt"` executes once and exits. Use `--quiet` to suppress intermediate steps.

4. **Integrate into CI/CD** — Wrap `auggie --print --quiet` in a shell script or GitHub Action. The agent runs in the current directory (auto-indexed) and returns structured output.

### Creating a Skill (Knowledge Package)

1. **Create directory structure** — In Cosmos Files > Organization > .augment > skills, create a folder named `my-skill` (lowercase, hyphens only).

2. **Add markdown file** — Upload `my-skill.md` with YAML frontmatter:
   ```markdown
   ---
   name: my-skill
   description: What this skill teaches the agent
   ---
   
   # My Skill
   
   Detailed guidance, examples, and procedures here.
   ```

3. **Attach to Expert** — Edit the Expert. The skill is auto-discovered and injected into the Expert's context.

4. **Validate** — Start a session with the Expert. The agent can reference the skill's guidance.

## Common Gotchas

- **Filters cost nothing when they fail** — A JSONLogic filter that returns false prevents session creation entirely. Use the Event Log to validate filters before deploying.

- **Triggers are off by default** — New triggers don't fire until you explicitly enable them. Test manually first, then turn on.

- **Repeated triggers without idempotency checks** — If the same event fires multiple times (e.g., a GitHub webhook retry), the Expert may create duplicate comments or tickets. Add idempotency checks in the system prompt (e.g., "Check if you've already commented on this PR").

- **Secrets referenced in MCP configs need separate access grants** — Sharing an MCP server doesn't automatically grant access to secrets it references. Grant access to the secret separately in Settings > Secrets > Manage access.

- **Sessions created by triggers are auto-archived by default** — Fire-and-forget automations don't appear in your session list. Turn off "Auto-archive sessions created by this trigger" if you want to revisit them.

- **Environment variables and secrets are not inherited by workers** — If an Expert launches worker Experts, workers don't automatically see the parent's environment variables or secrets. Explicitly pass them or configure them on the worker's environment.

- **Workspace context is required for Auggie CLI to index** — Run `auggie` from a git directory or specify a directory with `--workspace`. Without context, the agent has no codebase knowledge.

- **Settings files merge hierarchically** — User settings, project settings, and local project settings are merged. Higher-precedence files override lower ones. MCP servers and plugins are replaced, not deep-merged.

- **Skills must follow agentskills.io naming rules** — Skill names must be 1–64 characters, lowercase alphanumeric and hyphens only, and match the directory name. Invalid: `Python-Testing`, `api_design`, `-deploy`.

- **Cosmos Advisor is the recommended path** — Hand-editing Expert configs, triggers, and environments is possible but error-prone. Use Cosmos Advisor (describe your workflow in plain language) to have the agent wire up Experts and automations for you.

## Verification Checklist

Before submitting work with Augment:

- [ ] **Integrations connected** — GitHub, Linear, Slack, or other sources are connected in Settings > Integrations.
- [ ] **Environment ready** — Cloud environment or self-hosted daemon is provisioned and repositories are cloned.
- [ ] **Expert tested manually** — Start a session with the Expert directly and verify it produces correct output before automating.
- [ ] **Trigger filter validated** — Use Event Log > Advanced Filter to confirm the JSONLogic filter matches the right events.
- [ ] **Idempotency checks in place** — System prompt includes checks to prevent duplicate comments, tickets, or sessions on repeated events.
- [ ] **Secrets and MCP access granted** — Any secrets or MCP servers the Expert uses have "Can use" access for the intended users/spaces.
- [ ] **Trigger enabled** — Scheduled and webhook triggers are explicitly enabled; GitHub/Linear/Slack triggers are on by default.
- [ ] **Run history inspected** — At least one automation run has completed; inspect the session to confirm behavior.
- [ ] **Auto-archive setting correct** — Fire-and-forget automations have auto-archive on; revisitable sessions have it off.
- [ ] **Skills discoverable** — Custom skills are in the correct location (`cosmos/files/organization/.augment/skills/`) and follow naming rules.

## Resources

- **Comprehensive page listing** — https://docs.augmentcode.com/llms.txt
- **Cosmos getting started** — https://docs.augmentcode.com/cosmos/getting-started
- **Automations and triggers** — https://docs.augmentcode.com/cosmos/automations
- **Auggie CLI overview** — https://docs.augmentcode.com/cli/overview

---

> For additional documentation and navigation, see: https://docs.augmentcode.com/llms.txt