Jern Cloud docs

Skills: playbooks the agent reads when a task matches.

A repository can keep playbooks under .jern/skills/. The agent carries only their names and descriptions on its prompt and reads one when the task calls for it, so a repository can hold many playbooks and pay context for one.

Writing a skill

A skill is one folder under .jern/skills/ with a SKILL.md inside. Its front matter names it and says when it applies; the rest is the playbook.

---
name: release-notes
description: How to write the changelog entry for a release.
---

Read CHANGELOG.md first. Every entry names the user-visible change,
starts with the noun it changes, and links the pull request.
Do not add an entry for a change that a user cannot see.

The description is what the agent sees before deciding to read the body, so it should say when the skill applies, in one line. A skill without front matter is named after its folder and described by its first line of text. A loose file under .jern/skills/ that is not in a folder is ignored.

How the agent uses it

At the start of each attempt the agent lists the skills folder once and adds one line per skill to its system prompt: the name, the description, and the path to read. The body stays on disk until the task matches, when the agent reads it with read_file and follows it. Reading once per attempt keeps the prompt byte-stable, so prompt caching keeps working.

Skills are on-demand playbooks. CONVENTIONS.md at the repository root is the always-on note: it rides the prompt whole on every turn. Put the rules that apply to every change there, and the procedures that apply to some tasks in skills.

Why this is safe

Skills are repository content under the same review as the code. A session pins the repository revision it starts from, so the skills it reads are the ones your reviewers approved at that commit, and the protected .jern/ directory keeps the agent from editing them. Every read is on the trace and the receipt: the receipt's tool line counts the listing, and the session shows the read of the skill's path.

Seeing it work

On the public demo repository, a skill under .jern/skills/docstrings/ says how a conversion function is documented: one line, starting "Convert a temperature from", both units in full, no formula. A session asked to add missing docstrings read the skill and produced exactly that line, and left an intentional bug in the function body alone because the skill's last line asked it to.

Skills the runtime ships with

None yet. Skills are yours; the runtime brings the mechanism. If you would rather start from examples, write to hello@jern.ai and we will share the ones we run.