Skill Editor

The Skill Editor is a dataset-level configuration that allows you to customize, manage, and optimize skills such as Text-to-SQL, summarization, synonym generation, and more.

It is primarily used within datasets to control how Athena interprets and answers user queries. By configuring prompts, instructions, and calculations, dataset admins can tailor Athena’s responses to match business rules, domain-specific language, and reporting needs.

This makes the Skill Editor especially useful when:

• Different departments (e.g., Sales, Finance, Operations) have unique terminologies or reporting rules.

• Queries require custom formulas (e.g., margin percentage, customer lifetime value) that don’t exist in the raw schema.

• Consistency is needed in responses—for example, applying a fixed financial year across all date-related queries.

Until now, these prompts and rules had to be manually adjusted by the engineering team. With the Skill Editor, dataset admins can directly edit prompts, instructions, and calculations—making the system more flexible, self-service, and responsive to business needs.

Accessing Skill Editor

The following are the steps to access the Skill Editor:

Step 1: Access the Data Management located in the Data Workbench section.

Data Management

Step 2: Select the Dataset for which you want to configure the Skill Editor.

Dataset

Step 3: In the Actions menu, click on the Settings icon and choose Skill Editor, where you can configure prompts, instructions and calculations.

Settings

Step 4: The Skill Editor includes three main types of configurations:

• Prompt Editor – to define and refine the prompts that guide Athena in interpreting user queries.

• Instructions – to set domain-specific rules or guidelines that shape Athena’s responses.

• Calculations – to create or adjust formulas and metrics for business reporting.

NOTE
Modifying prompts, instructions, or calculations in the Skill Editor directly impacts how Athena interprets and responds to queries. Incorrect or overly broad changes may lead to unexpected outputs or hallucinations.

Skill Editor

Prompt Editor

The Prompt Editor allows you to define and manage the way Athena interprets and responds to the queries. Prompts guide the model by providing structure, context and rules, ensuring responses are accurate and aligned with business needs.

The Prompt Editor contains three tabs each serving a unique purpose:

• System Template

• Assistant Template

• User Template

Prompt Editor

System Template

The System Template contains static instructions that remain consistent across all queries. It includes details such as dataset summaries, SME information, table and column metadata, and relationships like joins or dependencies. Since this information does not change with every user question, it provides a strong and stable foundation for Athena to interpret queries accurately.

System Template

Code Breakdown

The following is the code breakdown for the System Template.

Personality

### Personality
You are a translator who translates query to Postgres SQL using table schema provided.

• This defines Athena’s role. For example, Athena is positioned as a translator that converts natural language into SQL.

• Fixed: Cannot be edited.

Response JSON Format

### Response JSON Format
{ 
  "msg": "The Message to be shown to the user in human language", 
  "sql": "The Output of the SQL statement to be executed", 
  "chartType": "Type of the chart based on user request and columns of the SQL query" 
} 

• This specifies the structure Athena must use when answering. It ensures that all responses include a message, SQL, and chart type.

• Fixed: Cannot be edited.

Rules

Rule 1: Follow the provided JSON response format exactly.  

Rule 2: Do not use square brackets for column or table names in PostgreSQL.  

Rule 3: Apply joins only if listed in "Table Joins" or strictly necessary.  

Rule 4: Output the SQL as a single line with no breaks, extra spaces, formatting, comments, or code blocks.  

Rule 5: If the schema is insufficient, explain and request the missing metrics or information.  

Rule 6: When using DATE_TRUNC, cast the second argument as TIMESTAMP. 

Rule 7: Interpret MoM, QoQ, YoY, and DoW as month-over-month, quarter-over-quarter, year-over-year, and day-of-week.  

Rule 8: Aggregate metrics with a default precision of 2.  

Rule 9: Use lowercase aliases and description fields instead of IDs. 

Rule 10: Include all ORDER BY fields in the SELECT clause and append NULLS LAST.  

Rule 11: Clarify metrics and periods if uncertain.  

Rule 12: For help-type questions, list possible queries (newline-separated) based on schema and rules.  

Rule 13: Apply default precision of 2 for custom calculations unless overridden.  

Rule 14: Use the financial year in "Default Date" if provided, otherwise use the calendar year. 

• Rules ensure Athena follows SQL standards. These are set by the system.

• Fixed: Cannot be edited.

Domain Context

{{ domain_context }} 

This section passes the business/domain background. Users can edit this to reflect your dataset’s context, like Sales or Inventory.

Example:

# Domain Context: 
Sales 

If domain context is set to Sales, Athena interprets “Top customers” as top customers by sales revenue instead of any other measure.

Table Schema

{{ table_schema }} 

This defines the structure of tables and columns Athena can use. Users can edit the schema updates as per dataset.

Example:

orders(order_id, customer_id, order_date, revenue, cost) customers(customer_id, cust_name, region) Example: When a user asks “Show revenue by region”, Athena looks at the customers.region field and links it to the orders.revenue column.

Adding a new column like discount_rate here makes it available in queries.

Table Joins

{{ table_joins }} 

Specifies how different tables relate to each other. Users can add or modify joins.

Example:

orders.customer_id = customers.customer_id   

When a user asks, “Revenue by customer”, Athena joins the two tables through customer_id to produce the correct result.

Default Date

{{ default_date }} 

This sets the default date range. Users can edit the dates, when not specified Athena uses the default(Jan-Dec).

Example:

Apr – Mar (Financial Year) 

When a user asks, “Sales in the last year”, Athena uses Apr–Mar instead of Jan–Dec as the default year range.

Best Practices

• Do not edit core rules or JSON response format. Only update editable parts like domain_context, table_schema, table_joins, and default_date.

• Keep schema and joins up to date when data model changes.

Assistant Template

The Assistant Template handles dynamic instructions that adapt based on the context of each query, including sections, calculations, synonyms, or logic that shift depending on how the user frames their question. These instructions are embedded at the template level and act as guiding rules for how Athena interprets queries overall—for example, rounding percentages, setting naming conventions, or handling specific formats—ensuring responses are accurate, context-aware, and tied directly to the query translation process.

Assistant Template

Code Breakdown

The following is the code breakdown for the Assistant Template.

Instructions

### Instructions:
{{ instructions }} 

Users can add special rules for Athena.

Example:

Always round percentages to 2 decimals 

A query like “What is the profit margin?” will be returned as 12.45% instead of 12.451923%.

Formulae for Calculations

Formulae for calculating metrics which are not provided in the schema: 
{{ calculations }} 

Used to define metrics that are not directly available in the schema.

Example:

profit_margin = (revenue - cost) / revenue * 100  

If schema doesn’t directly store profit margin, Athena can compute it whenever the user asks, “Show me profit margin by product”.

Column Aliases

{{ column_aliases }} 

Provides synonyms or alternate names for columns.

Example:

cust_name → Customer 

If the schema has cust_name, but the user asks, “Show revenue by Customer”, Athena recognizes Customer as an alias.

Column Values

{{ column_values }} 

Specifies predefined mappings for column values.

Example:

US → United States 

If the user asks, “Show revenue for United States”, Athena maps it to the value US in the dataset.

Best Practices

• Use Instructions for consistent formatting (e.g., rounding).

• Keep formulas separate from SQL schema (don’t overload Assistant with raw SQL).

• Use aliases for business-friendly column names.

User Template

The User Template represents the user’s actual query along with its immediate context. It allows for adding instructions that clarify intent, such as handling time references (“today,” “this month”) or domain-specific phrasing. By capturing and interpreting the query in its natural form, the User Template ensures responses feel more personalized and precise.

User Template

Code Breakdown

The following is the code breakdown for the User Template.

Context:

### Context: 
{{ context }} 

Keeps track of conversation history to make queries flow better.

Example:

Sales dataset – Retail Division 

If the context is set, a follow-up query like “What about last month?” is understood in relation to the Retail Sales dataset.

Question

{{ question }} 

The direct question asked by the user.

Example:

What were the top 5 products sold last month? 

Best Practices

• Keep questions simple and natural.

• Add domain-specific phrasing for clarity (e.g., “month-to-date” → “current month”).

• Use context to handle follow-ups smoothly.

Copy option makes it easy to reuse configurations, while Reset to Default allows you to revert the system template back to its original platform-level settings if changes are made.

Copy

After updating prompts, it is important to save the changes by clicking on Save Changes. Saving ensures that all configurations are stored at the dataset level and reflected across subject areas.

Save

Once saved, Athena immediately applies the updated logic to subsequent queries without requiring additional setup.

Instructions

Instructions in the Skill Editor are rules or guidelines that direct Athena on how to interpret and respond to queries by adding domain-specific logic, business rules, or calculation guidelines, ensuring accurate, relevant, and context-aware answers across subject areas. Unlike template-level rules, these are dataset-level configurations that dataset admins can add, edit, or delete, offering flexibility through static or dynamic options to enforce business-specific logic without modifying templates.

Instructions

How to Add an Instruction

• Step 1: Click Add Instruction.

Add Instructions

Step 2: Select Static or Dynamic instruction depending on whether it should apply universally or contextually. Static Instructions are applied to all queries, regardless of context, whereas Dynamic Instructions are applied only when relevant to a specific subject area or query context.

Instruction Type

Step 3: Assign a Subject Area.

Subject Area

Step 4: Enter the actual instruction or guideline (e.g., calculation rule, formula, synonym mapping).

Instructions

Step 5: Click Add to add the instruction.

Add Instructions

Step 6: Users can Edit or Delete the added instruction.

Edit and Delete Instructions

Step 7: After all configurations, click Save Changes. It will immediately be available for Athena to use and will reflect in responses where relevant.

Save Instructions

Example Instruction

Best Practices

• Keep Static instructions for universal rules (e.g., always round to 2 decimals).

• Use Dynamic instructions to refine responses for subject areas.

• Keep language precise and unambiguous—avoid vague phrasing.

• Review instructions regularly as business rules evolve.

Calculations

Calculations in the Skill Editor are custom formulas or metrics that Athena uses when answering queries, allowing users to define business-specific computations directly in the platform so results remain accurate without manual SQL modifications. They can be static (used for all queries) or dynamic (applied only in relevant contexts), giving flexibility across subject areas and scenarios. Unlike template-level formulas, these are business-driven and defined directly by dataset admins, who can add, update, or remove them dynamically, tailoring calculations to specific contexts and giving business teams control without relying on engineering changes.

Calculations

How to Add a Calculation

Step 1: Click Add Calculation.

Add Calculations

Step 2: Select Static or Dynamic Type.

Calculation Type

Step 3: Choose the Subject Area.

Subject Area

Step 4: Enter the Name and Description for the calculation (e.g., Margin Percentage).

Calculation Name and Description

Step 5: Enter any mathematical or SQL formula (e.g., (invoiced margin / invoiced revenue) * 100

Calculation Formula

Step 6: Click Save to save the calculation.

Save Calculation

Step 7: Users can Edit or Delete the added calculations.

Edit and Delete Calculation

Step 8: After all configurations, click Save Changes to be available for Athena to use the reference in relevant queries.

Save Calculation

Best Practices & Tips

• Clear names: Use concise, business-friendly names (e.g., Margin %, Customer_LTV).

• Prevent errors: Use NULLIF or CASE to handle zero/NULL denominators in SQL formulas.

• Cast types: Explicitly cast to numeric where required to avoid integer division.

• Precision: Define display precision via Instructions (not in the formula unless necessary).

• Subject area mapping: Use Dynamic type for domain-specific metrics to prevent accidental use in unrelated contexts.