Authoring skills
1. Frontmatter
| Field |
Rule |
name |
Required. 1–64 chars, a-z0-9 and hyphens, no leading/trailing or doubled hyphen, must equal the folder name |
description |
Required. 1–1024 chars. Triggers + boundary, keyword-rich, no workflow summary: Use when [triggers]. Not for [neighbor] (use [other-skill]). |
metadata |
Optional str → str map; kit convention version as a plain string, unbumped on a text edit |
license, compatibility |
Optional; compatibility 1–500 chars, only for real environment requirements |
The description is the only text a future session sees before deciding: triggers
(the words users type, in their language, including "сделай скилл" and symptoms)
plus one clause naming the neighbor it is confused with. A trigger miss is fixed with
the phrasing the user used.
2. Layout and scripts
SKILL.md required; scripts/ helpers; references/ detail behind a "read when"
pointer; evals/evals.json expected; assets/ optional. References one level deep —
chained ones force multi-hop loads.
A bundled script prefers an existing tool (npx, uvx, pipx, bunx), documents
dependencies in SKILL.md or compatibility, and is agent-safe: no interactive
prompts and arguments only, since an agent waits on a TTY forever; --help and
errors saying what to do next; stdout result, stderr diagnostics, exit code carrying
success; idempotent with --dry-run for destructive steps; output bounded to
10–30K characters, where agents truncate. Run it via --help, not its source.
3. Body: size and tone
- Small. Each loaded procedure costs context and work; assess that cost
against the outcome it protects. Stay well under 500 lines; past ~350, move
detail into
references/<topic>.md.
- Each rule lives once: restating OPS or a neighbor skill dilutes what is unique
here. "Use X when Y, because Z" beats "critical, you must"; MUST/NEVER is for
safety, authority and fabrication lines.
- Keep decision-relevant examples: retain a table when it prevents a named
failure, not merely because it increases compliance. Tables and prose carry
the same burden of demonstrating value in their intended scope.
- Write what the agent doesn't know: gotchas, exact commands, fields,
thresholds. Positive recipes beat prohibitions for output shape.
4. Merge before you add
Overlapping triggers split routing and weaken both: extend the owner with a headed
section, bulk to its references/. Merging X into Y folds X's body and its
evals/evals.json cases in with their should_trigger semantics, adds a near-miss
negative owned by a neighbor, then deletes X. A new skill needs a distinct job:
another artifact, workflow moment or trigger phrase.
5. Turning a session into a skill
Raw material: this chat, or a named directory, procedure or URL — not a conclusion
to remember (dev-wiki).
- Isolate the repeatable procedure: what a fresh session would rediscover, in
order, with the why behind non-obvious decisions.
- Trigger test before writing; no plausible trigger, stop. Cases in
skills/<name>/evals/evals.json: {"skill_name": "<name>", "evals": [...]} of
id, prompt, should_trigger — one natural request true, one neighbor's near
miss false.
- Draft the body by §3.
- Location: portable → kit
skills/<slug>/ under the English, file-size and
review checks; machine-specific → the harness's own user skills dir, which does
not travel. Publishing it is an OPS §1 action.
- Ship it as a candidate until §6's evidence exists.
6. Promotion and retirement evidence
Run the tools, don't argue from impressions; without --executor they only validate
inputs (dry run).
python eval/trigger_eval.py --queries auto --only <slug> — trigger and false
rate; auto reads the skill's evals/evals.json, else eval/trigger_queries.json;
--executor "docker:<image> <argv>"/--model run it live.
python eval/runner.py --scenario <name> --repeat <n> — behavior on the
originating scenario; eval/scenarios; --executor/--judge grade it,
--release-grade when it counts.
python eval/ablate.py --executor "docker:<image> <argv>" — pass-rate change per
skill removed, on its scenarios.
python scripts/tools/usage_audit.py --retirement-report — no observed read
requests in the window (default 14 days), proposal only.
Addition and continued default use of an optional procedure need a named user
outcome or failure it protects, plus evidence proportionate to its cost and risk.
Routing checks show whether it is selected, not whether it helps. Use an originating
case, a nearby negative and a held-out case to assess outcome, side effects and
additional work; do not promote on compliance or trigger rate alone.
Apply the same standard to removal or narrowing: it need not make the model smarter.
A reversible trial can be justified by observed cost and weak benefit evidence,
with checks for the specific regressions at risk. Lack of a detected benefit is
uncertainty, not proof of uselessness; retain unique useful knowledge on demand
where appropriate. Read counts alone justify neither keeping nor retiring a skill.
Authority, stopping, honesty and protections for irreversible or high-impact
actions are not optional workflow overhead. Do not remove them by this cost rule.
Keep the evidence and limitations attached to the decision; no requirement for
another global benchmark, gate or fixed report format.
Gotchas
- Over-generalizing: encode the procedure that exists, not the class it resembles.
- Russian only in trigger words inside the description; bodies stay English.
- Scripts live in
scripts/, never inline in the body; a skill that was wrong once
is fixed like code — edit it, re-run the case that caught it.
1---2name: skill-authoring3description: 'Use when creating or editing a skill, or turning a session, procedure or URL into a reusable one ("learn", "/learn", "turn this session into a skill", "make a skill from this workflow", "сделай скилл из этой процедуры", "навык из"): name and description rules, folder layout, script bundling, promotion and retirement evidence. Not for saving conclusions in memory (dev-wiki) or for ordinary code changes.'4license: MIT5compatibility: applies to skills/ in this set, ~/.hermes/skills, .claude/skills6metadata:7 source: https://skillmd.com/skills/oleg494/skill-authoring8 version: "6.1.0"9---1011# Authoring skills1213## 1. Frontmatter1415| Field | Rule |16|---|---|17| `name` | Required. 1–64 chars, `a-z0-9` and hyphens, no leading/trailing or doubled hyphen, must equal the folder name |18| `description` | Required. 1–1024 chars. Triggers + boundary, keyword-rich, no workflow summary: `Use when [triggers]. Not for [neighbor] (use [other-skill]).` |19| `metadata` | Optional `str → str` map; kit convention `version` as a plain string, unbumped on a text edit |20| `license`, `compatibility` | Optional; `compatibility` 1–500 chars, only for real environment requirements |2122The description is the only text a future session sees before deciding: triggers23(the words users type, in their language, including "сделай скилл" and symptoms)24plus one clause naming the neighbor it is confused with. A trigger miss is fixed with25the phrasing the user used.2627## 2. Layout and scripts2829`SKILL.md` required; `scripts/` helpers; `references/` detail behind a "read when"30pointer; `evals/evals.json` expected; `assets/` optional. References one level deep —31chained ones force multi-hop loads.3233A bundled script prefers an existing tool (`npx`, `uvx`, `pipx`, `bunx`), documents34dependencies in SKILL.md or `compatibility`, and is agent-safe: no interactive35prompts and arguments only, since an agent waits on a TTY forever; `--help` and36errors saying what to do next; stdout result, stderr diagnostics, exit code carrying37success; idempotent with `--dry-run` for destructive steps; output bounded to3810–30K characters, where agents truncate. Run it via `--help`, not its source.3940## 3. Body: size and tone4142- **Small.** Each loaded procedure costs context and work; assess that cost43 against the outcome it protects. Stay well under 500 lines; past ~350, move44 detail into `references/<topic>.md`.45- **Each rule lives once**: restating OPS or a neighbor skill dilutes what is unique46 here. "Use X when Y, because Z" beats "critical, you must"; MUST/NEVER is for47 safety, authority and fabrication lines.48- **Keep decision-relevant examples**: retain a table when it prevents a named49 failure, not merely because it increases compliance. Tables and prose carry50 the same burden of demonstrating value in their intended scope.51- **Write what the agent doesn't know**: gotchas, exact commands, fields,52 thresholds. Positive recipes beat prohibitions for output shape.5354## 4. Merge before you add5556Overlapping triggers split routing and weaken both: extend the owner with a headed57section, bulk to its `references/`. Merging X into Y folds X's body and its58`evals/evals.json` cases in with their `should_trigger` semantics, adds a near-miss59negative owned by a neighbor, then deletes X. A new skill needs a distinct job:60another artifact, workflow moment or trigger phrase.6162## 5. Turning a session into a skill6364Raw material: this chat, or a named directory, procedure or URL — not a conclusion65to remember (dev-wiki).66671. **Isolate the repeatable procedure**: what a fresh session would rediscover, in68 order, with the why behind non-obvious decisions.692. **Trigger test before writing**; no plausible trigger, stop. Cases in70 `skills/<name>/evals/evals.json`: `{"skill_name": "<name>", "evals": [...]}` of71 `id`, `prompt`, `should_trigger` — one natural request true, one neighbor's near72 miss false.733. **Draft the body** by §3.744. **Location**: portable → kit `skills/<slug>/` under the English, file-size and75 review checks; machine-specific → the harness's own user skills dir, which does76 not travel. Publishing it is an OPS §1 action.775. **Ship it as a candidate** until §6's evidence exists.7879## 6. Promotion and retirement evidence8081Run the tools, don't argue from impressions; without `--executor` they only validate82inputs (dry run).8384- `python eval/trigger_eval.py --queries auto --only <slug>` — trigger and false85 rate; `auto` reads the skill's `evals/evals.json`, else `eval/trigger_queries.json`;86 `--executor "docker:<image> <argv>"`/`--model` run it live.87- `python eval/runner.py --scenario <name> --repeat <n>` — behavior on the88 originating scenario; `eval/scenarios`; `--executor`/`--judge` grade it,89 `--release-grade` when it counts.90- `python eval/ablate.py --executor "docker:<image> <argv>"` — pass-rate change per91 skill removed, on its scenarios.92- `python scripts/tools/usage_audit.py --retirement-report` — no observed read93 requests in the window (default 14 days), proposal only.9495Addition and continued default use of an optional procedure need a named user96outcome or failure it protects, plus evidence proportionate to its cost and risk.97Routing checks show whether it is selected, not whether it helps. Use an originating98case, a nearby negative and a held-out case to assess outcome, side effects and99additional work; do not promote on compliance or trigger rate alone.100101Apply the same standard to removal or narrowing: it need not make the model smarter.102A reversible trial can be justified by observed cost and weak benefit evidence,103with checks for the specific regressions at risk. Lack of a detected benefit is104uncertainty, not proof of uselessness; retain unique useful knowledge on demand105where appropriate. Read counts alone justify neither keeping nor retiring a skill.106107Authority, stopping, honesty and protections for irreversible or high-impact108actions are not optional workflow overhead. Do not remove them by this cost rule.109Keep the evidence and limitations attached to the decision; no requirement for110another global benchmark, gate or fixed report format.111112## Gotchas113114- Over-generalizing: encode the procedure that exists, not the class it resembles.115- Russian only in trigger words inside the description; bodies stay English.116- Scripts live in `scripts/`, never inline in the body; a skill that was wrong once117 is fixed like code — edit it, re-run the case that caught it.