Building Skills

Documentation Index

Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt

Use this file to discover all available pages before exploring further.

A skill is a reusable analytical methodology the agent follows step by step when invoked with /skill_name. The Context Builder is where you create new skills, edit existing ones, and refine them based on real usage. You can provide a full methodology or just describe the analysis you want to capture. The agent structures the skill for you — writing the content, defining clarifications, and setting up the todo list.

​

Starting a Skill

You can start a new skill from three places:

• Skills page — Click Add Skill in the top right. ClarityQ opens a Builder chat with the command pre-filled.
• Builder chat directly — Type /skill add in any Builder chat.
• From an Ask Anything conversation — If you’ve just run an analysis in Ask Anything that you’d like to make repeatable, continue in the Builder. The agent already has the context and can encode the methodology into a skill.

​

What the Agent Creates

The agent builds a skill with the following fields:

• Name — A snake_case identifier that becomes the slash command (e.g., /cohort_analysis)
• Description — A one-line summary shown in the slash command picker. This is what triggers the agent to import the skill, so it includes what the skill does, when to use it, and trigger phrases
• Content — The methodology itself in structured Markdown — rules, steps, constraints, SQL patterns, and gotchas specific to your data
• Clarifications — Questions the agent asks the user before running the skill, to gather any required inputs
• Todo list — The checklist the agent works through during execution

Before writing anything, the agent checks for existing skills that cover the same topic. If one exists, it suggests editing it instead of creating a near-duplicate.

​

Clarifications, Todo List, and References

Skills have three supporting mechanisms that control how the agent behaves when running them. You can use clarifications, a todo list, or both — depending on what the skill needs.

​

Clarifications

Questions the agent asks the user before executing the skill. Use clarifications when the skill needs one or two small inputs that change the analytical path — for example, which date range to use or which user segment to focus on. Keep clarifications minimal. If you find yourself adding more than two or three, the skill’s content should handle the branching instead.

​

Todo List

A checklist the agent works through during execution. Each todo item maps to a step or rule in the skill’s content, keeping the agent on track as it progresses through the analysis. When the agent creates a skill, it typically generates the right todo list automatically based on the content. You can review and adjust the items if needed. In chat, the todo list appears as a visible checklist with checkboxes. As the agent completes each step, it checks off the corresponding item — so you can follow along and see exactly where the agent is in the workflow. Use a todo list when the skill has multiple steps and you want to ensure none are skipped.

​

References

Supplementary documentation that loads on demand. When the agent imports a skill, it sees the names and descriptions of its references — but the full content only loads when the agent decides it needs more detail. This keeps skills concise while supporting deep documentation when needed. References are ideal for information that’s too detailed or too long to put in the skill’s content but that the agent may need to consult during execution — business logic edge cases, known data quirks, analysis guidelines, or output formatting rules. Example: A /funnel_analysis skill’s content defines the general methodology — how to build a funnel query, how to calculate drop-off rates, and how to present results. Its references contain special requirements for specific funnels: “Onboarding funnel” might document that step 2 must exclude users who skipped the tutorial, while “Purchase funnel” might note that the checkout step has a known 30-second delay before the event fires. The agent loads the relevant reference only when the user asks about that particular funnel.

​

The Description Matters Most

The description is the only thing the agent reads on every message to decide whether to import a skill. The content and hooks only load if the description triggers first. The agent usually writes a good description automatically, but it’s worth reviewing to make sure it captures the right scope — specific enough to trigger on relevant questions, but not so broad that it fires on unrelated ones. A good description follows this pattern: what it does + when to use it + trigger phrases. For example: “Analyze user retention by cohort. Use when: ‘retention’, ‘cohort analysis’, ‘D7 retention’.”

​

Editing Skills

Edit an existing skill from the Skills page (click Edit in the row menu) or type /skill edit <skill_name> in a Builder chat. The agent loads the current definition and walks you through the changes. Each save creates a new version.

​

Testing and Iterating

Before deploying a skill, test it in Ask Anything by invoking it with /skill_name. Review the agent’s output — did it follow the right steps? Did it miss anything? Did it produce the answer you expected? If something is off, go back to the Builder and refine the skill. Repeat until the results are consistent and accurate. First drafts rarely come out perfect, and that’s fine — the iteration is what makes a skill reliable.

​

Skill Scope

All custom skills are scoped to the product level — once deployed, they’re available to everyone working on the product.