> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarion.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Authoring best practices

> How to write triage and remediation skills that agents pick at the right time and follow correctly.

<Note>
  Skills are the backbone of our platform. Authoring good skills will make a huge difference in both the triage result, and also the duration.
</Note>

These practices follow the skill templates we ship as part of Clarion. Open any of them from the [skill library](/learn/skills/our-skills) to see an example.

## What is a skill

A skill is a set of instructions written in natural language that belong to one or multiple agents. They are primarily used as part of the triage and remediation phases, thus authoring your own skills gives you control over how different alerts are being handled.

## How agents use skills

Every agent has access to its own skills plus any skills referenced by those. Also, it has access to any skills referenced in the workspace instructions or in the scheduled task prompt.

When starting, the agent gets the title and description of each of those skills. It will then decide which ones to follow, and read their full body. After that, it will proceed to follow the instructions in those skills it read.

<Note> We don't inject the full skill body in the agent context, to prevent bloat. That's why good titles and descriptions are essential to make sure the agent picks the right one. </Note>

## Title

A good title should name the category of this task, not the agent or author. As a reader scanning the catalog, we should know what the skill is for from the title alone.

| Good | Weak |
| - | - |
| Identity Entitlement Review | Wiz skill 2 |
| Vercel Exposure Sweep | Weekly check |
| Credential harvesting triage | Claude Code agent playbook |

<Tip> Include the vendor when the skill only works against one vendor's data. Keep it generic if it's provider neutral </Tip>

## Description

The description will be used by the Agent when to decide what skill to follow, so it must include two things:

* a short summary of what the skill does
* instructions of when to use this skill

<Tip> Keep the description short, ideally 2 or 3 sentences. A long description bloats the context of every agent run </Tip>

Good description examples:

* Investigates GCP service account key creation as potential credential compromise or attacker persistence. Use when a new service account key is created, especially outside expected workflows.
* Investigates failed-sign-in bursts on a 1Password user as brute force, credential stuffing, or targeted account takeover. Use when an alert fires for multiple failed 1Password sign-in attempts for the same user in a small period.
* Remediates Dependabot vulnerabilities end-to-end and escalates high/critical findings in place. Use when a Clarion alert fires for one or more Dependabot vulnerabilities in a repository.

Bad description examples:

* Handles Wiz findings.
* Investigates suspicious activity and takes the appropriate action.
* First fetch the issue, then query the audit logs for the last 24 hours, check the user in Okta, and post a summary to Slack.

## Body

The body represents the instructions for the agent to follow. Try authoring it like guidance from the most experienced person on the team, thus saying what matters, what to check, what the evidence means, and what to do about it.

<Tip> Agents are smart so this doesn't need to be a very specific step-by-step list. Keep it generic when the flow is not clear, so the agent can follow its own reasoning </Tip>

### Common template

Most templates follow the same outline. Keep the sections your skill needs and drop the rest.

| Section | Purpose |
| - | - |
| Opening framing | One to three sentences on the goal and on what does and does not count as a finding |
| Ground rules | Rules that hold across every step, each with its reason |
| Workflow | Usually numbered steps, each naming what to check, and how/if the result changes the next step |
| Outcome | The evidence that decides the verdict and severity, then what to do once decided: escalate or set the status, and write what was learned to the Brain |
| Remediation | What the agent may fix itself and under which verdict (open a PR, revert a record, contain a host) and what it leaves to a human as a follow-up task |

### What to put in the skill

1. Specify what the goal is and what isn't

> The goal is to find deployments open to the internet that were **not meant to be**: internal dashboards, admin panels, stale proofs-of-concept. Intentionally public marketing sites, blogs, and products that enforce their own login are not findings.

2. Give every rule its reason so the agent can generalise

> Do not escalate Dependabot issues that are related to dev-only packages. They create noise and unnecessary work for the team. The priority should be on actual packages used in the production deployment.

3. Mention the required evidence

Say what counts as actual proof and what does not. The correctness of the alert details cannot be guaranteed, that's why the agent needs to correlate with actual evidence by using the available tools.

4. Keep it concise and clear

Think whether or not this skill makes sense if read by a colleague. If not, probably won't make sense if read by an agent.

<Tip>
  Split a skill when its triggers differ, or when the evidence that decides the verdict differs. Two skills that each do one job route better, and read better, than one skill with a branch at the top.
</Tip>

### What not to put in the skill

1. Do not mention tools by name. They are internal and may change freely, thus your skills will be outdated. Instead specify what the agent should do, not how.
2. Do not mention tool categories. By default each agent has access to all tools connected in your workspace. You can configure this from the agent page if you want granular control.
3. Do not give instructions about where or when to post notifications. Configure both under **Settings → Agents → Escalation & notifications**: see [Notifications](/learn/notifications/introduction) and [Severities that escalate](/learn/settings/workspace#severities-that-escalate).
4. Do not give instructions regarding asking for approvals. Those are set up once under **Settings → Tool policies** and they apply to all agents.
5. Do not put inside skills general knowledge about your business, the systems you use or the clients you have. This knowledge belongs in the Clarion Brain not in skills.
6. Do not put inside skills instructions that apply across all agents. Those belong in the workspace instructions. A good example of such a rule is always creating a Linear task before starting triage of an issue.

## References inside a skill

The skill editor turns references into pills. Each kind behaves differently at runtime, and two of them change what the agent is allowed to do.

| Pill | Editor trigger | What it does at runtime |
| - | - | - |
| Skill | `$` | Adds the referenced skill to the agent's catalog, even when that skill is not linked to the agent, so the agent can fetch it at the step that needs it. References are followed up to three levels deep. |
| Knowledge | `$` | Declares a Brain knowledge element the skill depends on. The agent is told to fetch its live content by id instead of searching for it. The `$` picker lists skills and knowledge together, and offers knowledge only in the skill editor. |
| Channel or person | `#`, `@` | Points the agent at a Slack or Teams channel or person. Although notification settings are set up once per workspace, this can be useful to point the agent at channels to read or people to coordinate with during the investigation. |
| Tool | `/` | DEPRECATED. Names the tool the step should use. It is no longer needed, as the agent can use every connected integration its agent settings allow. |

<Note>
  Edit the skill to change how an agent handles an issue. The agent's own settings decide which tool groups it may use and which model it runs on, so check those when an agent cannot take an action its skill asks for.
</Note>

## Final recommendations

Always review the skills you write, even if written by an AI. Good skills are essential for a good Clarion experience.

Before saving them, ask Clarion to review them, it will provide actionable feedback.