# AI agents (/docs/ai-agents)

Give an AI assistant these docs, and what it must know to write a correct rule.



A rule file is plain JSON checked strictly when it loads, which makes it a good task for an AI assistant: it writes the file, and the panel tells you exactly what is wrong if anything is.

## Give the docs to your assistant [#give-the-docs-to-your-assistant]

These docs are published as Markdown for language models:

| URL                                | Content                                                                                                                   |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| [`/llms.txt`](/llms.txt)           | An index of every page, with its description ([llms.txt](https://llmstxt.org)).                                           |
| [`/llms-full.txt`](/llms-full.txt) | Every page in one Markdown file. Give this one to an assistant that writes rules.                                         |
| `/llms.mdx/docs/<page>/content.md` | One page as Markdown, such as [`/llms.mdx/docs/reference/fields/content.md`](/llms.mdx/docs/reference/fields/content.md). |

Every page also has a **Copy Markdown** button under its title, and a menu to open it in an AI assistant.

## A prompt that works [#a-prompt-that-works]

```text
Read the PPROLint rule documentation: <url>/llms-full.txt

Write a PPROLint rule file that reports <what you want to find>.
- Use only fields listed in the Fields reference, in the scope you choose.
- Put thresholds in options, with defaults that rarely fire on a correct timeline.
- Messages name the item and give the measured value and the threshold.
- Output the complete file, named <id>.rule.json.
```

Save the answer in your rules folder and click **Reload rules**. If the file has problems, paste them back to the assistant: each one gives the JSON path and the reason.

## Checklist for agents [#checklist-for-agents]

When writing a rule file:

1. **Start from a built-in rule** with a similar purpose: the [built-in rules](/docs/rules) show complete, valid files. Reusing an existing id replaces that rule; choose a new id otherwise.
2. **Pick the scope** whose items you report on: `clip`, `track`, `effect`, `marker` or `sequence` ([Scopes](/docs/reference/scopes)).
3. **Use only listed fields** of that scope ([Fields](/docs/reference/fields)). Paths are checked; there are no other fields and no expressions.
4. **Respect types.** Number operators need number fields and values; `in` takes a list; `exists` takes no value ([Operators](/docs/reference/operators)).
5. **Guard unknown values.** A comparison on an unknown value is false, and `not` turns it true: prefer positive comparisons, or add `exists` ([Unknown values](/docs/guides/conditions#unknown-values)).
6. **Put thresholds in `options`** and refer to them as `{ "field": "options.<name>" }` ([Options](/docs/guides/options)).
7. **Severity**: `info` for something unusual, `warning` or `error` for a certain problem.
8. **Write self-explaining messages** with `{field.path}` placeholders, and plural forms when a number changes the grammar ([Messages](/docs/guides/messages)).
9. **Add `data`** with the measured value and the thresholds ([Data](/docs/guides/data)).
10. **No unknown properties.** Every property is listed in [Rule file](/docs/reference/rule-file); anything else is an error.