# Hermes Agent Skill Authoring Quick-Start

## What is a skill?
A skill is a reusable playbook Hermes loads on demand. It lives as a SKILL.md
file (plus optional templates, references, and scripts) inside a profile's
skills directory. Skills carry domain knowledge so the agent does not have to
re-discover procedures every session.

## Directory layout
```
skills/
  my-skill/
    SKILL.md              # required — frontmatter + body
    references/
      api.md              # optional
    templates/
      config.yaml         # optional
    scripts/
      validate.py         # optional
```

## SKILL.md structure
```yaml
---
name: my-skill
description: One sentence on what it does and when to load it.
---
```

Body follows the frontmatter. Keep it short: steps, pitfalls, and the exact
commands or workflows the agent should run.

## Loading a skill
```python
skill_view(name='my-skill')
```

Call once at the top of a session when the task touches that domain. Do not
load process skills (testing, debugging) for work you already know.

## Authoring rules
- Frontmatter requires only `name` and `description`.
- Write imperative facts, not instructions to yourself.
- Put reusable procedures in the skill body; one-off facts go in memory.
- If the skill has templates or scripts, list them in linked_files and load
  them with a second `skill_view(name='my-skill', file_path='...')` call.
- Test the skill by invoking it on a real task before committing.

## When to update a skill
- After a correction from the user.
- After discovering a new pitfall or a better command.
- When a workflow changes across sessions.

## Example: minimal working skill
`skills/example/SKILL.md`:
```yaml
---
name: example
description: Prints a greeting. Load when user says 'greet me'.
---
```

```bash
echo "Hello from the example skill."
```

Load it:
```python
skill_view(name='example')
```

## Anti-patterns
- Do not author skills during a one-shot run with no later session to reuse
  them.
- Do not put task-specific notes in memory; memory is injected every turn and
  must stay small.
- Do not edit another profile's skills unless the user explicitly directs you.