quill: draft skill authoring quick-start guide

wizard-work/quill/skill-quickstart-guide.md

@@ -0,0 +1,77 @@
+# 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.