> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/playbooks/playbook-conventions.md).

# Playbook conventions

When creating playbooks to contribute, you need to following conventions and standards that keep playbooks consistent, usable, and readable.

#### Naming

* Names are Title Case.
* Playbook names cannot contain the following special characters:

  ```programlisting
  Punctuation marks: ! " # $ % & ' ( ) * + , . / : ; < = > ? @ [ \ ] ^ ` { | } ~    
  Symbols: © ® ™ ° µ ± ß    
  Formatting characters: ¶ §
  ```
* After the playbook name, but before specifying a version number or integration name, use a dash (-).

  Example: `Endpoint Enrichment - Generic v2`.
* If adding `Test` to the playbook name, use a dash and add it to the end of the name.

  Example: `Phishing - Core - Test`
* When adding `test` to a later version of a playbook, use `- Test` at the end.

  Example: `Phishing - Core v2 - Test`
* In the descriptions of playbooks, specify the supported integrations or file types. File types are in capital letters. Integration names are in title case.

  ![integration\_names.png](/files/wnaEBHexGFQtvQgG7E19)

  ![filetypes.png](/files/H6O0TWefOqujxQLV0gIh)

#### Tasks

* The first letter of task names is capitalized. The rest of the task name is sentence case, but integration names should be capitalized.
* When using verbs, the verb form should be the simple command. For example, `Save`, and not `Saving` or `Saves`.
* Conditional tasks should end with a question mark. For example, `Is there a file?`, `Is there an endpoint to enrich?`, `Is there an email file attached?`, `Is Carbon Black Enterprise Response enabled?`,`Is there a Word file?`
* Descriptions of tasks, unlike the names of tasks, should use the verb form `Saves` and not `Save`. For example, `Checks if this is the first iteration`.

#### Tips

* To automatically extract indicators from an output of a command, in the task **Advanced** tab, select one of the options provided: **Use system default**, **None, Inline, Out of Band.** See [Indicator extraction](/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/indicators.md) for more information about each option.
* When outputting to context in integrations or scripts, use generic descriptions. For example, **Extract Indicators From File - Generic v2** has two different tasks outputting to `File.Text` but in the playbook outputs there is a description for only one.
* Set defaults for playbook inputs as needed, by clicking **Playbook Triggered** at the top of the playbook.
* Avoid programming terms, as playbooks can be used by non-programmers.
* When working with indicators or data that should be unique, use `Uniq` transformers to prevent duplications in the returned list. Do the same for playbook inputs.
* Avoid using [DT](/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/integrations-and-scripts/advanced-topics/transform-language-dt.md) (Transform Language) if not required. Instead, use selectors (**Get** step), filters, and transformers. This is easier to work with and also prevents a common error where data is passed by value instead of reference. An exception to this rule is when using the `Set` script, which sets a value to an output. You can not "get" that key, as it does not exist.
* Use the **Ignore case** option when checking user inputs, such as True/False in playbook inputs.
* Confirm task changes in all relevant sub-windows. Do not cancel, switch tasks, or navigate to another page, as your changes will not be saved.
* When editing a playbook that has a sub-playbook, if you changed the inputs/outputs of the sub-playbook, the changes are not reflected in the parent playbook, until you refresh the page. Saving the parent playbook and reopening the playbook may not show the changes until you refresh the page.

#### Visual Design

* When visually designing a playbook, the most important factor is to provide a clear understanding of the workflows, followed by overall readability, followed by general aesthetics.
* Group similar tasks.
* Align tasks/headers of the same level.
* Use section headers to split playbook tasks into different phases.
* Avoid headers as timer starts/stoppers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/cortex-xsiam-developer-guide/cortex-xsiam-development-guide/playbooks/playbook-conventions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.