kkrafft1999/snotra / system-skills/snotra-skill-authoring
snotra-skill-authoring
VerifiedHow to write or change a skill — where it goes (.agents/skills/<name>/ in the open folder), folder layout, front matter, a description that makes it fire, and how it becomes global. Use when the user asks you to create, build, extend or fix a skill, or to turn a way of working into one ("make a skill for this", "add X to the skill", "bau mir einen Skill").
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.4 KB |
SKILL.md
View on GitHub---
name: snotra-skill-authoring
description: How to write or change a skill — where it goes (.agents/skills/<name>/ in the open folder), folder layout, front matter, a description that makes it fire, and how it becomes global. Use when the user asks you to create, build, extend or fix a skill, or to turn a way of working into one ("make a skill for this", "add X to the skill", "bau mir einen Skill").
license: Apache-2.0
metadata:
snotra-system-skill: 'true'
---
# Writing skills
A skill is a folder with a `SKILL.md`: YAML front matter with `name` and
`description`, then instructions in Markdown. The description of every
switched-on skill is part of the system prompt; the instructions are fetched
with `load_skill` once the description matches the task.
## Where a skill goes
**Two ways to write a skill.**
- **A skill of one `SKILL.md`** — a procedure in steps — goes through the tool
`remember` with `kind: "instruction"`: `topic` is the skill's name,
`description` says what it is for and when to use it, and `body` is the whole
skill as it should read. `scope: "workspace"` writes
`.agents/skills/<name>/SKILL.md` in the open folder, `scope: "user"` writes
`~/.snotra/skills/<name>/SKILL.md` for every folder. It is always a **whole
version**: to change a skill, send the complete new text — it replaces the
old one, and the user sees the diff on the card. There is no `team` reader
for a skill. Ask the user which folder it is for before the call.
- **A skill of several files** — `references/`, `scripts/`, `assets/` — only
in the open folder, under `.agents/skills/<name>/`, with the ordinary file
tools: `write_file_text` for a new file (missing folders are created),
`edit_file` or `apply_patch` for changes. An existing skill there is
changed the same way — it is part of the folder, not locked. Such a write
asks on a card in *Smart* and *Always ask*; in *Auto* it goes through, and
your answer names every skill file you wrote.
Read-only for the file tools, with no way around it:
- the global skills in `~/.snotra/skills/` and `~/.agents/skills/` — `remember`
is the one way to write `~/.snotra/skills/`, and `~/.agents/skills/` is never
written,
- the system skills built into Snotra, this one included; names beginning with
`snotra-` are theirs.
Do not try to reach them with `shell_execute` or `run_python` either — that is
going around a line the user drew, not a workaround.
**No folder open:** only a global one-file skill through `remember`; for
anything else offer the complete `SKILL.md` in the chat.
A new skill applies once the user switches it on under **{menu:settings.skills}**;
say so after writing one.
## Folder layout
```
.agents/skills/<name>/
├── SKILL.md required — the instructions
├── references/ optional — longer material, read only when needed
├── scripts/ optional — code the instructions tell you to run
└── assets/ optional — templates, sample files
```
Keep `SKILL.md` focused on what to do; move long reference tables, specs and
examples into `references/` and say in `SKILL.md` when to read which file.
Once the skill is switched on, its files are read with `skill:<name>/…`, for
example `skill:<name>/references/api.md`. Anything over 20,000 characters in
the body of `SKILL.md` is cut off.
What a skill **produces** while it runs — notes, caches, state — never goes
into its own folder. It goes to `.agents/data/` in the open folder.
## Front matter
```yaml
---
name: release-notes
description: Writes release notes from the merged pull requests since the last tag, grouped by area. Use when the user asks for release notes, a changelog or "what changed since vX".
---
```
- **`name`** — exactly the folder name. Letters, digits, `.`, `_` and `-`,
starting with a letter or digit, at most 64 characters. Prefer lowercase
words joined by hyphens. Do not start a name with `snotra-`: that prefix
belongs to the built-in skills, and a built-in skill of the same name always
wins.
- **`description`** — decides whether the skill is ever used. Say **what** it
does and **when** to use it, with the phrases the user would actually say,
in the languages they use. One to three sentences, at most about 1,000
characters. A description that only names the topic ("Release notes") does
not fire.
- Other keys (`license`, `metadata`) are allowed and ignored.
Ask about the name if the user did not give one and it is not obvious, and
before you overwrite a skill that already exists in the folder.
## The body
Write instructions, not an essay: imperative steps in the order they happen,
the decisions with their criteria, what to do when something fails, and what
not to do. Concrete examples beat abstract rules. Leave out what any capable
model already knows.
## After writing
The result of every write to `.agents/skills/<name>/SKILL.md` carries a
`skill_check`:
- **`valid: false`** — the catalog skips the skill; `problem` says why
(missing front matter, missing `name` or `description`, invalid name, name
not equal to the folder). Fix it right away, before you answer.
- **`valid: true`** — the skill is in the catalog. Skills from a folder start
**switched off**: tell the user to tick it under
**{menu:settings.skills}**, unless it is on already. Until then it is not in
your system prompt, so do not claim it is in use.
Then sum up in a sentence or two what the skill does and when it will fire —
not the whole file again.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |