# Skills

Canonical: https://auggy.dev/docs/add-skills
Status: Published
Package: auggy 0.5.0

Teach the model when and how to use an augment without loading every instruction into context on every turn.

## What skills are

Skills are markdown files the model reads on demand through the filesystem augment. Every turn receives a compact, trust-filtered manifest with each matching skill's exact SKILL.md path. The runtime instructs the model to read a relevant skill before answering or using tools in that domain, without loading every skill body into every turn.

Trust filtering applies to discovery and filesystem access. Creator-only skills are absent from public manifests, and public read, list, or search requests cannot reach them through alternate path spellings or symlink aliases.

| Layer | What loads | Cost |
| --- | --- | --- |
| Manifest | Name and description for each mounted skill. | Small idle context. |
| SKILL.md body | Full teaching file read with `fs_read` when relevant. | Only when needed in a thread. |
| References | Detailed supporting files under references/. | Only when the model requests depth. |

## Tool description or skill?

Start with the tool description. Add a skill only when the model needs a larger operating playbook than the tool definition can express clearly.

| Mechanism | Use it for |
| --- | --- |
| Tool description | Helping the model select one tool and understand its immediate purpose. |
| Skill | Optional workflow guidance: sequencing, clarification, judgment, failure recovery, and coordination across tools. |
| Runtime code | Enforcing schemas, authorization, consent, business invariants, and consequential state changes. |

**The description handles selection**

```ts
defineTool({
  name: "save_lead",
  description: "Save a qualified lead for creator follow-up.",
  input: CreateLeadSchema,
  execute: async (input) => JSON.stringify(await saveLead(input)),
});
```

**The skill handles the workflow**

```
# Lead intake

- Ask for an email address and a concrete need.
- Ask one clarifying question when qualification is incomplete.
- Save the lead before notifying the operator.
- If saving fails, do not claim the lead was recorded.
- Escalate only when urgency or purchase intent meets the documented criteria.
```

> **Warning: Skills do not enforce policy**
>
> Put authorization, consent requirements, validation, and business invariants in runtime code. A skill can guide model behavior, but it is not a security boundary.

## What belongs where

| Primitive | Role |
| --- | --- |
| Augment | Runtime capability mounted at boot. |
| Tool | Callable function exposed to the model. |
| Skill | Optional markdown playbook the model reads when a workflow needs more guidance. |

A skill provides no tools, routes, or lifecycle hooks. If the capability needs code, it belongs in an augment; if the model needs judgment about that code, it belongs in the skill.

## Folder convention

**Skill folder**

```
skills/
  memory/
    SKILL.md
    references/
      provider-types.md
  filesystem/
    SKILL.md
    references/
      mount-permissions.md
  escalation/
    SKILL.md
```

**SKILL.md frontmatter**

```
---
name: memory
description: When/how to use memory_read, memory_write, memory_search, memory_list, memory_forget
---

# Memory Tools

Teach when to use each tool, common mistakes, and workflows.
```

## When to include one

- Include a skill when tools have non-obvious interaction patterns.
- Include a skill when there are judgment calls, do-not rules, or multi-step workflows.
- Skip a skill when the tool name and description are enough.
- If you would brief a teammate for more than 30 seconds before using the capability, add a skill.

## Refresh bundled guidance

**Refresh an existing project**

```bash
auggy skill add auggy
auggy skill add layeredMemory
```

The first command refreshes the general **Auggy** build-out guide. The second refreshes the peer-memory teaching for an installed layeredMemory augment. Bundled refreshes overwrite that skill folder's installed snapshot, so keep project-specific teaching in a separate user-authored skill.

## Related

- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)