Writing a good trail
The rules an agent (or a person) follows so a trail reads well and surfaces at the right moment.
GET /v1/authoring-guide and the get_authoring_guide MCP tool return this
guide as data, with the current limits and the list of trails already in the
workspace. This page explains the reasoning.
The one rule
A trail is the company's standard recipe for one job task with an AI tool. Every field is read by the employee in the target role while they do the task: second person, imperative. Never write about the trail, the learner, the creator, or the employee's deliverable.
Good: "Paste the objection, then ask for three counterpoints grounded in our pricing page." Not: "This trail helps account executives handle objections."
The document
| Field | What goes there | Limits |
|---|---|---|
title | The task, as the employee would name it | 3 to 160 characters |
target_role | The job role, e.g. "Account Executive" | up to 120 |
description | The task in one or two sentences | 20 to 2,000 |
tools | The AI tools this recipe is for, from the supported list (chatgpt, claude, ...) | at least one |
trigger.when | The moment in the workflow when the trail applies | up to 600 |
trigger.keywords | Phrases the employee would actually type | 3 to 25, each 2 to 60 characters |
trigger.examples | Realistic prompts with expect: match or no_match | up to 8, each up to 500 characters |
setup_guide | Markdown: what to open, paste, or prepare before the first prompt | up to 40,000 |
prompts | Ordered steps, each with a label and a body using {{snake_case}} placeholders for anything the employee supplies | 1 to 12; label up to 120, body up to 8,000 |
The full JSON Schema comes with the guide response.
How surfacing works
When an employee starts typing in an AI tool, Joring compares the draft against every live trail in their workspace and the Joring catalog, using the trigger, the keywords, and the examples. A judge picks the single best trail, or none. Two trails that describe the same task compete; extend the existing one instead.
That is what trigger.examples are for. Write three to six prompts an
employee would really type, including at least one that is close but should
not surface this trail. run-examples runs each one against the live
catalog; all of them must pass before the trail can be published.
Before publishing
A publish is refused until:
- the title, role, description, at least one tool, the trigger, a setup guide, and at least one prompt are present within their limits;
- the setup guide has no unfinished image uploads;
- if there are examples, the last run passed;
- a
restrictedtrail has at least one person or team granted access.
GET /v1/trails/{id} (and get_trail) return publish_issues with exactly
this list, so an agent can loop on it.
A workflow that produces good trails
- Read the guide and list existing trails.
- Draft the full document and create the trail.
- Read
publish_issues; fix errors, consider warnings. - Add examples and run them. If a "should match" prompt loses to another
trail, sharpen
trigger.whenand the keywords, or narrow the task. - Decide who sees it. New trails start
restricted(only people granted access); setvisibilitytoall_teamsfor everyone in the workspace. - Publish, then tell the person what went live.