Skip to main content
Skills are the backbone of our platform. Authoring good skills will make a huge difference in both the triage result, and also the duration.
These practices follow the skill templates we ship as part of Clarion. Open any of them from the skill library 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.
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.

​
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.
Include the vendor when the skill only works against one vendor’s data. Keep it generic if it’s provider neutral

​
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
Keep the description short, ideally 2 or 3 sentences. A long description bloats the context of every agent run
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.
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

​
Common template

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

​
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.
  1. 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.
  1. 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.
  1. 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.
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.

​
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 and 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.
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.

​
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.