Skills
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. |
defineTool({
name: "save_lead",
description: "Save a qualified lead for creator follow-up.",
input: CreateLeadSchema,
execute: async (input) => JSON.stringify(await saveLead(input)),
});# 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.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
skills/
memory/
SKILL.md
references/
provider-types.md
filesystem/
SKILL.md
references/
mount-permissions.md
escalation/
SKILL.md---
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
auggy skill add auggy
auggy skill add layeredMemoryThe 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.