View source for Assista - Analytica AI Assistant/Custom user skills for Assista

[[category:Objects]]
[[category:Concepts]]
[[category:Function libraries]]

''New to [[Analytica 7.1]]''
{{ReleaseBar}}

This page describes how to create your own '''custom user skill''' for Assista — a way to expand Assista's knowledge or capabilities with instructions, conventions, or domain knowledge that are specific to your model, your team, or your workflow.

<div style="border-left:4px solid #4a90e2; background:#eef6ff; padding:0.8em 1em; margin:1em 0;">
'''Tip — Assista can help you author skills.''' The fastest way to write or refine a skill is to ask Assista directly — say something like ''"Help me write a custom skill that …"''. Assista has a built-in '''Authoring-skills''' capability that walks through picking a location, creating the [[#The AssistaSkill class|<code>AssistaSkill</code> object]], filling in each attribute, and adding resources. You don't need to memorize the details on this page — Assista will do most of the mechanical work for you and ask only the questions it needs answered.
</div>

== What is a skill? ==

A '''skill''' is a packaged piece of guidance that Assista loads on demand when it decides the skill is relevant to your prompt. Each skill has:

* A short '''description''' that is always visible to Assista, so it can decide whether to load the skill.
* A set of '''trigger conditions''' (''when-to-use'') that further refine when the skill applies.
* A '''skill body''' — the actual instructions, in markdown — that Assista reads when it loads the skill.
* Optional '''resources''' — supporting reference text (examples, lookup tables, sample data) that the skill body can refer to.

Assista ships with a library of built-in skills. '''Custom user skills''' let you add your own on top of those. Custom skills come in two flavors:

* '''Model-specific''' — embedded in a particular model. Use these when the skill references things only meaningful in that model (specific variables, modules, naming conventions, business rules).
* '''General / model-agnostic''' — placed in a shared linked library (a filed <code>LinkLibrary</code>) so the same skill can be linked from multiple models. Use these for skills that are useful across many models — house style, team conventions, reusable techniques.

Assista discovers your custom skills automatically at the start of each session and merges them with its built-in skills.

=== Where to put a skill ===

A skill object can live anywhere in the model, but the recommended placement is:

{| class="wikitable"
! Skill type !! Where to put it
|-
| Model-specific || Inside a <code>Library</code> (or <code>Module</code>) in the current model.
|-
| Model-agnostic / general || Inside a '''<code>LinkLibrary</code>''' (filed library) saved as its own <code>.ana</code> file, so it can be linked from multiple models.
|}

Co-locating skills in a single library dedicated to skills keeps them tidy and easy to maintain. It's a recommended practice, not a requirement.

== Anatomy of a skill ==

=== The AssistaSkill class ===

A skill is represented by an '''<code>AssistaSkill</code>''' object in the model. <code>AssistaSkill</code> is a module-like class — it acts as a private namespace, so identifiers of objects placed inside the skill (typically resources) do not collide with anything outside it.

Every <code>AssistaSkill</code> object should fill in these attributes:

{| class="wikitable"
! Attribute !! Required !! Notes
|-
| <code>Identifier</code> || yes || The skill's name (a valid Analytica identifier). Used in skill listings and lookups.
|-
| <code>Title</code> || optional || Human-readable title.
|-
| <code>Description</code> || yes || '''Very short''' — always included in Assista's context, so keep it to a single line.
|-
| <code>AssistaSkill::SkillCategory</code> || no|| Category name on line 1; optional category description on line 2 and beyond. If omitted its category will be "User_Skills". When multiple skills are in the same category, providing the description or any one of them suffices.
|-
| <code>AssistaSkill::WhenToUse</code> || yes || Trigger conditions describing when the skill is applicable.
|-
| <code>AssistaSkill::SkillBody</code> || yes || The full skill instructions, in markdown.
|}

The three <code>AssistaSkill::</code>-prefixed attributes live in the private '''<code>AssistaSkill::</code> namespace''' — when reading or setting them via expressions, you must use the qualified name (<code>AssistaSkill::SkillBody</code>, not just <code>SkillBody</code>). All three are '''text-only'''.

=== Writing a good Description ===

The <code>Description</code> is included in every Assista call where skills are considered, so it must be '''short''' — typically a single line of 10–25 words. Lead with what the skill does, then a brief ''"use when …"'' cue.

Example: ''"Convert a wide-format table to long-format. Use when the user has data with multiple measurement columns to stack."''

=== Writing SkillCategory ===

The first line is the category name (use the same wording across all skills that share a category). If a second-and-later line is present, it serves as the category's description; it is only used when the category isn't already defined by another skill. For skills joining an existing category, omit the description.

Example:

<pre>
Reporting
Generating reports, exports, and summaries from model results.
</pre>

=== Writing WhenToUse ===

A bulleted list of trigger conditions. Assista reads this when deciding whether to load the skill body. Be specific — vague triggers either over-load the skill or miss valid cases. Include user-phrasing cues where possible (e.g., ''"User mentions 'unpivot' or 'melt'"'').

=== Writing SkillBody ===

The full instructions, in markdown. The body is loaded only when Assista decides the skill is relevant, so there is no hard length limit — but stay focused. Reference '''resources''' (see below) for long examples, lookup tables, or reference data rather than inlining them in the body.

=== Resources ===

Resources are supporting reference text placed '''inside''' the <code>AssistaSkill</code> object. Because <code>AssistaSkill</code> is its own namespace, resource identifiers don't collide with anything outside the skill.

Use the <code>Constant</code> class for the typical case (literal text). Other variable classes are also recognized when you need them, but stick with <code>Constant</code> unless there's a reason not to.

A resource needs:

* An '''<code>Identifier</code>''' — the resource name Assista will use to fetch it.
* A '''<code>Description</code>''' — what the resource contains (short).
* A '''<code>Definition</code>''' — the resource's content (typically a quoted text literal).

A resource's <code>Definition</code> may be a computed expression — it can even depend on the current model. Two caveats:

# It must evaluate to an atomic text string.
# By default the value is '''cached''', so later changes to the model won't show up in the resource. To recompute on every access, set <code>CachingMethod</code> to <code>4</code> (never cache).

Use computed resources sparingly — literal text is simpler and almost always sufficient.

== How to create a skill ==

=== The easy way: ask Assista ===

The recommended way to create or edit a skill is to '''ask Assista'''. Open the Assista panel and say something like:

* ''"Help me write a custom skill that …"''
* ''"Create a skill that teaches you about our naming conventions in this model."''
* ''"Turn this prose into a proper skill: …"''
* ''"Edit my <code>Convert_wide_to_long</code> skill to also mention the new <code>StackIndex</code> function."''

Assista's built-in '''Authoring-skills''' capability will:

# Help you decide where the skill should live (model-specific vs. shared library).
# Create the <code>AssistaSkill</code> object with a valid identifier.
# Set <code>Title</code>, <code>Description</code>, <code>SkillCategory</code>, <code>WhenToUse</code>, and <code>SkillBody</code> for you, asking only the questions it needs answered.
# Add any resources you want inside the skill.

Assista takes care of the mechanical details — including the namespace-qualified attribute names and Analytica's text-literal quoting rules — that would otherwise be easy to get wrong.

=== The manual way ===

If you'd rather create a skill by hand in Analytica:

==== Step 1: Pick or create the parent module ====

Decide where the new skill will live:

* For '''shared / general''' skills, create or reuse a <code>LinkLibrary</code> (filed library).
* For '''model-specific''' skills, create or reuse a <code>Library</code> (or <code>Module</code>) in the current model.

==== Step 2: Create the AssistaSkill object ====

Add a new object of class <code>AssistaSkill</code> inside the parent module. Give it a descriptive identifier and fill in <code>Title</code> and <code>Description</code>.

==== Step 3: Set the namespaced attributes ====

<code>AssistaSkill::SkillCategory</code>, <code>AssistaSkill::WhenToUse</code>, and <code>AssistaSkill::SkillBody</code> are namespace-qualified, so you set them via expressions using the fully qualified name. For example, to set the category:

<pre>
AssistaSkill::SkillCategory of Convert_wide_to_long := 'Reporting
Generating reports, exports, and summaries from model results.'
</pre>

All three attributes are text-only. Remember Analytica's quoting convention: a literal single quote inside a single-quoted string is doubled (<code><nowiki>''</nowiki></code>).

==== Step 4 (optional): Add resources ====

Add <code>Constant</code> objects (or other variable-class objects) '''inside''' the <code>AssistaSkill</code> object. Set each resource's <code>Description</code> and <code>Definition</code>. The <code>Definition</code> is typically a literal text string.

== Guidelines for effective skills ==

A well-written skill is far more useful than a sketchy one. Aim for:

* '''Concrete triggers in <code>WhenToUse</code>.''' Specific user-phrasing cues beat abstract descriptions.
* '''Show, don't only tell.''' Include short examples for any action the skill recommends.
* '''Prefer dedicated tools over <code>Eval</code>.''' When the skill recommends an action Assista should take in the model, point at the relevant Assista tool/callback rather than ad-hoc <code>Eval</code> expressions. Fall back to <code>Eval</code> only when no dedicated tool covers the operation.
* '''Keep the Description tight.''' It is the one piece always in Assista's context.
* '''Be terse.''' Don't pad with motivation or general advice Assista already has.
* '''Move long material into resources.''' Lookup tables, sample data, and long reference text belong in resources, not inlined in the body.

=== Using libraries within a skill ===

Custom skills can reference functions or variables defined in linked libraries — useful when the skill leans on reusable building blocks. A few guidelines:

* Document any required library in the skill body, including how to link it if it isn't already linked.
* Prefer well-known or co-distributed libraries over ad-hoc dependencies, so the skill keeps working across users and models.
* For shared, model-agnostic skills, package the skill itself in a <code>LinkLibrary</code> so it travels alongside its supporting code.

== Quick checklist ==

Before considering a new skill done, verify:

* <code>Identifier</code> is a valid, descriptive Analytica identifier.
* <code>Description</code> is a single short line, leading with what the skill does.
* <code>AssistaSkill::SkillCategory</code> has the category name on line 1 (description optional on line 2+).
* <code>AssistaSkill::WhenToUse</code> lists specific trigger conditions, ideally with user-phrasing cues.
* <code>AssistaSkill::SkillBody</code> is markdown, focused, with concrete examples for any recommended actions.
* If the skill is model-agnostic, it lives in a <code>LinkLibrary</code> saved to its own file.
* Resources (if any) live inside the <code>AssistaSkill</code> object and use <code>Constant</code> (or another text-yielding class), with both <code>Description</code> and <code>Definition</code> set.

== See also ==

* [[Assista - Analytica AI Assistant|Assista — Analytica AI Assistant]]
* [[Modules_and_Libraries#Filed_Library|Filed libraries (aka LinkLibrary)]]
* [[User-Defined_Functions#Libraries|Library]]