Agent Skills Workshop: write, test and run SKILL.md skills for Hermes, Claude Code and Codex

Here is a job I have done three times [paste notes]. Draft a SKILL.md using this card [paste].
Write the description as 'Use when...' with the words I actually type. Leave Owner blank.

Fill Done means and May not yourself if the draft is vague.

Review this skill I did not write [paste every file]. Fill this intake check [paste section 5].
List every path, network call and command it can trigger, and quote any instruction about tone, identity or what to skip.

Rewrite in your own words if it fails reach or tone.

# Agent Skills Workshop: write, test and run SKILL.md skills for Hermes, Claude Code and Codex

A bot template and teaching guide by PaperChaseWebb for building your own agent skills instead of collecting other people's. A skill card template, a three-skill split for long jobs, a capture loop that turns your corrections into skill drafts, an intake check for skills you did not write, action classes for what a skill may do on its own, a SKILLS.md register, an overnight run sheet, eight skill drills, a rules block and 14 prompts. Plain .md.

Skills in the SKILL.md format load in Hermes Agent, Claude Code, Codex, Cursor and other harnesses that read it. That is the good news and the risk: a skill written once travels everywhere, and so does whatever its author assumed about your files, network and tone. This pack treats a skill as a standing instruction you are responsible for, not a plugin you collect.

This is a method, not a hosted product and not an endorsement of any vendor or skill library. Check each harness's current docs for where skills live and how they load.

## Contents

1. What a skill is, and when a prompt is enough
2. The skill card
3. Split long jobs into three skills
4. Turn your corrections into skill drafts
5. Skills you did not write: the intake check
6. Action classes: what a skill may do on its own
7. SKILLS.md: one register for every harness
8. Overnight runs with skills
9. Tools behind skills (MCP servers and plugins)
10. Failure modes and fixes
11. Eight skill drills
12. Rules block and 14 prompts
13. Sources

## 1. What a skill is, and when a prompt is enough

A skill is a folder with a SKILL.md file: a short name, one line on when to use it, and the steps. Some skills carry helper files (a script, a checklist, a reference image list). The harness reads the one-line description to decide whether to load the skill, then follows the steps.

Write a skill when all three are true:

- **You have done the job at least three times** and corrected the agent the same way twice.
- **The steps are stable.** If the steps change every week, keep it as a prompt.
- **Someone other than you would run it.** Another harness, a scheduled job, or a teammate's agent.

Keep it as a prompt when it is a one-off, when the judgment is the whole job, or when the "steps" are really "think hard about this".

## 2. The skill card

Every skill you write starts from this card. Fill it before you write a single step.

```
---
name: [verb + object, for example "draft weekly client report"]
description: [one line: WHEN to use this, written for the harness deciding whether to load it]
---
# Purpose
[One sentence on the outcome.]

# Inputs
- [What the skill needs before it starts. If missing, stop and ask.]

# Steps
1. [Short, checkable step.]
2. ...

# Done means
- [The check that proves it finished: a file exists, a test passes, a count matches.]

# May not
- [Actions this skill never takes, even if a step seems to call for it.]

# Action class
[read / draft / change / outward. See section 6.]

# Owner and version
[Who answers for it. Date. What changed last.]
```

The description line does more work than any step. "Use for X" loads the skill at the right time. "A helpful skill for productivity" loads it never, or always.