Custom skills
Add a playbook to your project by uploading a .skill archive. The planner follows it, with its own governed tools, for the questions it fits.
A skill is a reusable, versioned analysis written as a playbook: text that tells the planner how to analyse a kind of question, for example "for a change in RTO rate, split it by payment mode, then by customer type; report the largest contribution". Custom skills let you capture an analysis your team repeats and make it part of how your project answers.
A skill no longer runs as code of its own. The planner carries out its playbook with the planner's own governed tools only: metrics computed from your stored definitions, lookups, arithmetic done in code, a question back to you when it needs one, and the answer. Every figure in the answer comes from a stored definition or from code's arithmetic on them, with its lineage.
Where to find it
Sidebar › Skills. The page is the Skill catalogue for the current project. (Settings › Skills redirects here.)
The catalogue reads: "Drop a .skill archive to add a playbook without deploying: guidance the planner follows, with its own governed tools, for the questions a skill fits. A skill's SQL or Python is kept for reading, not run."
- Search with Search by slug, name, description, or filter by category.
- Switch between List and Graph. Graph shows skills with sub-skills on the left, with the sub-skills they name.
Each skill carries a source badge:
| Badge | Meaning |
|---|---|
| seeded | Ships with Tattva. Can't be deleted. |
| uploaded | Added by someone in your project with Upload .skill. |
| forked | A copy made from another skill. |
A skill with upload warnings shows how many (for example 2 warnings); its own page lists them (see Upload warnings).
Under each skill, its kinds header is shown as chips, one per question kind it answers (for example Why something changed); a kind switched off under Answer scope is struck through, and a skill without kinds shows no kinds. When Tattva does not offer the skill, a note says why, the same words the Trail uses:
| Note | Why |
|---|---|
| Deprecated: … | The skill is deprecated, with the reason (the seeded Root Cause Analysis, Forecast, Attribution, Optimize allocation and Foresight skills: the planner answers those questions from your stored definitions). It stays listed, greyed, but is never offered or run. |
| Make flow only: … | The skill runs only in Ontology › Make (the seeded Creative Concepts), never for a question. |
| Not offered while 'why a figure changed' is off | Every kind it declares is switched off in the project. |
Not offered: add kinds to its header | It declares no kinds and some kind is switched off: what it answers is unknown, so it is not offered. |
| Not offered: its text names a definition this project does not have (see its warnings) | Its text names a definition the project does not have (an upload warning, below): the playbook is incomplete, so it is never offered or followed until the definition is added or the text reworded and the skill uploaded again. |
A skill that declares metrics or decompose_by also shows them under its kinds: metrics with the definitions it names (or any metric / any metric with keys), and split by with its keys. Whether it is offered for a given question depends on that question's metric, so the Trail, not the catalogue, says when it was left out for one (see The .skill format).
The skill's own page shows the same chips, the note and its warnings under its description.
What a playbook may and may not do
| May | May not |
|---|---|
| name the definitions and keys to split by, in what order | introduce a figure no stored definition or code arithmetic gives |
| say what to compare, rank and report | write SQL or Python |
| set thresholds for what to point out ("contributions above 10% of the change") | change how figures are named or stated (code writes the claims) |
| ask for an input or confirm a period (the question is written by code) | override the step budget or the answer scope |
When a step needs a figure no definition gives (for example RTO rate by payment mode, when no definition of RTO rate is keyed by payment mode), the answer says that figure is not available, names the definition that would give it ("a definition of RTO Rate keyed by payment mode would answer this"), and the gap is added to Maintain › Feedback. The answer never contains a figure that isn't governed.
Uploading a skill
- Click Upload .skill.
- Pick a
.skillarchive (a zip) of up to 5 MB. It contains the skill definition and any sub-skills. - Tattva installs it into the current project and shows "✓ Imported …" with the number of skills saved, then any upload warnings, per skill.
Uploads are written to the audit log. If the header has fields the format does not have, or retired fields (answer, writer_input_chars), the upload message lists them as ignored. Uploading a skill again also stops the stored answers it wrote from being handed out under Repeat questions: the next time such a question is asked, it is answered in full with the new version.
Upload warnings
At upload, the text of the skill and of each sub-skill is read against the project's ontology. A model lists the definitions and key columns the text names, each with the words it names them in; Tattva keeps only names whose words are in the text, and checks each against the project's stored definitions and their keys. Nothing here refuses the upload: what doesn't fit is a warning, stored on the skill and shown on its page.
| Warning | When |
|---|---|
| "…" is not a metric definition in this project. Closest stored: … | The text names a definition the project does not have. The closest stored definitions are listed, by how alike their slugs and names are. |
| "…" is not a key of any metric definition in this project. Closest stored keys: … | The text names a column to split or filter by that no definition has as a key. |
| Its own runBigQuery code is no longer run … Figures it computed that will need definitions: … | Its tool_allowlist has a tool that runs its own SQL or Python (runBigQuery, runDuckDB, runPython), or its text writes SQL or Python. That code is kept for reading, not run. The figures it computed are listed, except those a stored definition already gives: add a definition for each to have the planner answer it. |
| Its text could not be read against the ontology at upload | The reading failed. Upload the skill again to check it. |
A warning that the text names a definition the project does not have makes the playbook incomplete: it is not offered or followed for any question, and the Skills screen says so (see the notes above). The other warnings leave it offered. A warning about a name is fixed by adding the definition (or a definition keyed by that column) or by rewording the playbook to the stored name, then uploading the skill again.
The .skill format
A .skill file is a zip archive with:
SKILL.mdat the root: a header between---lines, then the playbook in Markdown.- Optional
agents/<slug>.mdfiles: sub-skills, each in the same format. They are installed with the skill and linked to it, and their text is checked at upload like the skill's.
Header fields:
| Field | What it is |
|---|---|
name | Display name. Also the slug when slug is absent. |
slug | Unique id within the project (letters, digits, -, _). |
description | One or two sentences, read when choosing a skill. |
category | For example analysis or forecasting. |
version | A whole number. |
metrics | Optional. The metric definitions the skill works on: a list of definition slugs (metrics: [net_revenue]), or one requirement: any (any metric with a stored definition) or any_keyed (any metric whose definition splits by at least one key). The skill is offered only for a question about a metric that fits. Unless the question names the skill, it is followed only when the definitions its metrics list or its text names include the question's metric, the overall metric that one breaks down or another breakdown of it, or a definition that counts the same thing by fewer of its columns; when several skills do, the planner chooses among them. Leave it out for orchestrators, generic methods and skills that give no figures. |
decompose_by | Optional. The key columns the skill splits the metric by, as a list: decompose_by: [channel, product]. The skill is offered only when the question's metric splits by every one of them: as a key of its own definition, or through a keyed definition that breaks it down (channel_net_revenue for net_revenue). |
kinds | The kinds of question the skill answers, as a list: kinds: [rca, comparison]. Names are the question kinds of Answer scope: definition_lookup, value_query, ranking, comparison, trend, rca, forecast, attribution, optimize, scenario, qualitative, navigation, data_inventory. The skill is offered only for the kinds your project answers; when some kinds are switched off, a skill without kinds is not offered at all. For the analysis kinds (rca, attribution, optimize, forecast, scenario, qualitative) a fitting skill is followed unasked. For the others, which one run of the stored definitions answers, the skill is followed only when a question names it: a plain comparison or ranking stays on the fast path. The upload and the Skills screen say so on such a skill: "Used for 'comparisons' only when a question names it; plain questions stay on the fast path." |
trigger_examples | Example questions, one per line, used to pick the skill. |
sub_skills | Slugs of the skill's sub-skills. Files under agents/ are added automatically. |
tool_allowlist | The tools the skill's code used, kept as written. A playbook runs none of them; a tool that runs its own SQL or Python gives an upload warning. |
max_steps, input_schema, output_schema | Read only when a skill runs on its own, from a Make plan or a function. A playbook ignores them; the planner's own budget applies. max_steps is 1 to 20; a schema is one line of JSON holding an object. |
A max_steps outside 1–20, a kinds entry that is not a question kind, a metrics that mixes a requirement with slugs, or a schema that is not one line of valid JSON holding an object, fails the upload with the reason.
metrics and decompose_by are checked against the project's metric definitions when you upload, for the skill and each sub-skill. The upload is refused, with the reason, when a named definition does not exist in the project ("metrics names gmv, which is not a metric definition in this project"), when a decompose_by key is not a key of a named definition ("decompose_by payment_mode is not a key of rto_rate"), or, without named definitions, when no definition has that key. Add the definition, or a definition keyed by that column, first. (Names in the playbook's text, unlike the header, give warnings, not a refusal.)
When a question's metric does not fit, the skill is not offered for that question, and the Trail says why: "Not offered for this question: its metric is not one the skill's metrics names", or "… its metric's definition lacks the keys the skill splits by".
Retired fields. answer and writer_input_chars are no longer read. A header that still has them uploads as before, and the upload message lists them as ignored.
How to write the values:
- Numbers are plain digits:
max_steps: 8. A quoted number ("8") is rejected. - Lists are one per line under the field (
- channel) or in brackets on one line ([channel, product]). - Schemas are one line of JSON after the colon. The header has no nesting, so a schema spread over several lines is not read.
Example SKILL.md:
---
name: rto-drivers
slug: rto-drivers
description: Explains why the RTO rate changed between two periods, ranked by contribution across payment mode, customer type and channel.
category: analysis
version: 2
kinds: [rca]
metrics: [rto_rate]
decompose_by: [payment_mode, customer_type, channel]
trigger_examples:
- Why did the RTO rate rise in August?
- What drove RTO up last month vs the month before?
---
For a change in RTO rate between two periods:
1. Compare the RTO rate for both periods.
2. Split the change by payment mode, then by customer type, then by channel, one key at a time.
3. Rank each split's rows by their contribution to the change; point out contributions above 10% of the change.
4. Report the largest contribution first.The upload is refused unless the project has an rto_rate definition that splits by payment mode, customer type and channel.
Inside a skill
Open a skill to see its name, slug, version, source, category, kinds, metrics / decompose_by and its upload warnings. The tabs are:
- Overview: trigger examples and Try in Reasoning (not on a deprecated or Make-only skill).
- Playbook: the skill's text, the guidance the planner follows. SQL or Python in it is kept for reading, not run.
- Sub-skills: the skills it names as sub-skills.
- References: examples and material it draws on.
- Tools: its
tool_allowlist, kept as written; a playbook runs none of them. - Schema: its
output_schema. - Runs: recent runs of the skill on its own, from Make plans and functions. Questions in Reasoning follow it as a playbook; their steps are on the answer's Trail.
Trying a skill
On Overview, click Try in Reasoning. Reasoning opens with a question that names the skill already typed in the box ("Use the rto-drivers skill: Why did the RTO rate rise in August?", from its first trigger example). Edit it if you like, then ask.
The planner also follows a skill on its own when an analysis question (why a figure changed, a forecast, …) fits it: its kind, and its metrics / decompose_by. A figure, ranking, comparison or trend question follows a skill only when it names it. When several skills fit, the planner is offered each one's name, description and definitions and chooses one, or combines several, each for the metric it covers; code checks each choice covers its metric. See Answers that follow a playbook.
Naming a skill in a question
You can ask for a skill by its name or slug ("top 5 products last month using Coverage movers"). The question's words must hold the skill's whole name or its whole slug (a plural aside): "Why did revenue drop?" does not name revenue-drivers, and "Why did RTO change?" does not name rto-drivers, so such a question is not held to one skill. Tattva checks the name against the project's uploaded skills:
- The skill is offered for the question: the planner follows it, even if another skill, or none, would have been picked.
- The skill is uploaded but not offered: the answer says why, for example "The skill revenue-drivers isn't used while "why a figure changed" is off in this project", and answers the rest of the question without it. The reasons are the same as on the Skills screen: it is deprecated or runs only in Ontology › Make, every kind it declares is switched off, or it declares no kinds while some kind is off.
- No uploaded skill has that name: the answer says "No skill named "…"; uploaded skills: …", listing them, and answers the question normally.
- The words could mean more than one skill (a word two or more skills' names share, such as "the drivers skill"): Tattva asks which one, listing every uploaded skill and "No skill".
The Trail's How this was answered › Details has a Skill row for the skill the question named: "You named it: used.", or a Not applied row such as "You asked for rto-drivers; it is not available for this question: …" or "No uploaded skill is called "…".", or an Asked you row, "Which skill did you mean?"
A playbook in the Trail
On an answer's Trail tab, How this was answered › Details lists only the skills that could answer this question: those whose kinds include the kind the question was read as or answered as. Each says "offered", or "Not offered for this question: …" with a plain reason. Candidates switched off with their kind are folded into one line, for example "Skills that answer why a figure changed are off with it: revenue-drivers, rto-drivers.", with a Manage skills link to the Skills screen. A deprecated or Make-only skill is said only under Debug, with the Skills screen's note ("Deprecated: …").
An answer that followed a playbook is a planned answer: its Steps show each tool call the planner made, as for any question that needs a plan. The Steps header names the playbooks it followed ("Followed: revenue-drivers v5 for orders"). When several were offered, the first step is the planner's choice ("Followed revenue-drivers v5 for orders"); a choice code rejected is listed under that step in Debug, with the reason and the options.
Deleting a skill
Click Delete on an uploaded or forked skill and confirm. Seeded skills can't be deleted.
Skills and the Workspace Library
A skill uploaded to the Workspace Library is seen by every project in the workspace, as its definitions are, with a Workspace Library chip on the Skills screen; edit or delete it in the Library. A project's own skill of the same slug is used instead of the Library's. A skill uploaded to any other project stays in that project. Each project's answer scope still decides which kinds of question a skill is followed for: with "why a figure changed" off, a Why skill is never followed there.
Writing a step that splits a change
A playbook can ask for a change to be split into effects, for example "split the RTO rate change by payment mode into mix and rate" or "split net revenue's change into orders and AOV". Code does the arithmetic, so the step must name what code needs, as stored definitions:
- the whole: the figure whose change is split (Website RTO Rate, Net Revenue);
- the volume, if any: a count for each period (Orders, Units);
- the mix: each segment's share, from a definition keyed by the segment (Payment Mode Order Share), or counts code turns into shares (Product Units);
- the rate: each segment's value (Payment Mode RTO Rate, AOV), or an amount divided by a count, row by row (Product Net Revenue per Product Unit);
- how a new segment is counted: a segment with no orders in the earlier period has no earlier rate. Say in words which rule applies, for example "a segment with no orders in the earlier period is compared with the overall earlier rate", or "a new product's change is all mix".
Code checks that these inputs cover both periods with the same segments and filters and multiply back to the whole. A part that does not is shown as Not split. Name which splits to rank when the playbook asks for the largest effect; code ranks every row of the splits named. Effects of different splits of one change are never added together.
A playbook cannot make the planner combine rows that don't add up. Rows that overlap (a customer counted under two acquisition products, a distinct count by day) are never summed, never read as parts of their own total for a share, and never subtracted from a total as "the rest": the step is refused, and the refusal names the stored definitions that count the total (or count it by fewer columns) for the planner to run instead. A share of such a row over one of those definitions' totals is allowed, with the note that the shares overlap and do not add to 100%. When no definition counts the total, the planner is told to say so rather than add.
Tips
- Name the definitions and keys the project already has, as they are stored: the upload warns about any it can't find.
- Say what to compare and in what order; leave the figures to the definitions.
- Review uploaded skills like code: they change how your project answers.