--- title: "Use Custom Instructions and Skills" slug: "use-custom-instructions-skills" description: "Learn how Custom instructions and Skills tailor Pigment Agents with company context, repeatable workflows, access controls, and reliable outputs." tags: ["AI Agent Skills", "Custom Instructions"] updated: 2026-11-12T12:24:55Z published: 2026-11-12T12:24:55Z canonical: "kb.pigment.com/use-custom-instructions-skills" --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.pigment.com/llms.txt > Use this file to discover all available pages before exploring further. # Use Custom Instructions and Skills Custom instructions and Skills tailor Pigment Agents to how your company works, so Members never have to repeat context in each Chat. ## Before you begin ### What are Custom instructions and Skills? **Custom instructions** are standing guidance applied to every Chat, like the brief you give a new colleague on day one. Use them for: - Company context, such as definition of fiscal year, business units, currencies - Internal vocabulary and naming conventions - Default answer style and guardrails **Skills** are playbooks for specific tasks. They give the Agent knowledge it could not have learned on its own, such as your internal methods, your naming conventions or how your Application is set up. The Agent loads one only when a request requires it or when a Member calls it. Use them for: - Repeatable workflows, such as month-end variance commentary - Output standards, such as brand guidelines for Frames - Specialized methods, such as your allocation rules | | Custom instructions | Skills | | --- | --- | --- | | **When it applies** | Every Chat, always | Only when relevant or when invoked by a Member | | **Who triggers it** | Applied automatically | The Agent (based on the Skill description) or a Member (on demand) | | **Best for** | Context and rules true for everything | Step-by-step know-how for one type of task | | **Typical length** | A few short paragraphs | As long as the task needs; detail is only loaded when used | | **Example** | "Our fiscal year starts in February. Amounts are in EUR thousands." | "Brand guidelines for Frames": colors, fonts and layout rules applied whenever a Frame is built | > [!WARNING] > ⚠️ Important > > A simple rule of thumb: if it should be true in every conversation, write it as an instruction. If it only matters for a specific kind of task, make it a Skill. The two work together: instructions set the baseline and Skills add depth on demand. ### Who can configure them and how Only Members with the **Owner**, **Security Admin** or **Workspace Admin** [account types](/v1/docs/account-types-management#account-types) can configure custom instructions and Skills. To configure and manage custom instructions and Skills for an Agent: 1. In your Application, open Settings, the three-dot menu at the bottom of the left sidebar, then **All settings**. 2. Under Workspace settings, select **AI agents management**. The main pane shows tiles with the AI Agents enabled for your Workspace. 3. Select **Edit** on the Agent tile you wish to customize instructions and Skills for. 4. Here you can perform the following: 1. **Instructions**. Create and edit. For more information, see [How to write custom instructions](/v1/docs/use-custom-instructions-skills#how-to-write-custom-instructions). 2. **Skills**. Create, upload, enable or disable. > [!NOTE] > ℹ️ Note > > - **Scope**. Custom instructions and Skills apply to all Chats and all Members of the Workspace. Write them for everyone, not for one team or one person. > - **Access rights**. Instructions and Skills change how the Agent works, not what it can see. A Member only gets answers based on the data their own access rights allow. > - **Effect**. Changes only apply to new messages. Updated instructions and Skills are picked up on the next message the Agent processes. > - **Confidentiality**. Do not store secrets, passwords, API keys or personal data in instructions or Skills; every Member's Agent reads them. ## How to write custom instructions Custom instructions are a free text field. Each Agent has its own instructions, so tailor them to what it does. ### What to include 1. **Context**. Industry, organization, calendar, units. 2. **Vocabulary**. Internal terms and the Metrics, Lists or Applications they map to. 3. **Conventions**. Naming, number formats, reference Version. 4. **Answer style**. Level of detail, language, when to ask for clarification. 5. **Guardrails**. What to check or confirm before acting. ### Best practices - **Be specific.** "Show amounts in EUR thousands" works. "Be precise" does not. - **Explain why.** Reasons help the Agent handle cases you did not anticipate. - **Say what to do.** Avoid listing what not to do. - **Keep it structured and short.** Use headings, bullets and a "When X, do Y" format. Move task-specific procedures into Skills. - **Test after each change**. Remove contradictory rules. ## How to write custom Skills A good Skill: - Solves one specific, repeatable task. - Tells the Agent clearly when to use it. - Shows what a good result looks like. ### How the Agent uses a Skill 1. The Agent always sees the **name** and **description** of every enabled Skill, but not its full content. 2. When a request matches a Skill's description, the Agent loads that Skill's **instructions** and follows them. A Member can also call a Skill directly in a Chat. 3. The Agent can combine several Skills in one answer, for example a variance analysis Skill and a brand guidelines Skill. Because only the name and description are always visible, you can enable many Skills without overloading the Agent. The description decides whether a Skill is used, the instructions drive how well. > [!NOTE] > ℹ️ Note > > **Agents reason about instructions.** The Agent reads your Skill, thinks about it and then decides how to act, so it is not fully predictable. It will usually follow a Skill, but it may occasionally choose a different approach. Treat a new Skill like instructions given to a new colleague: be clear, then check the first results. See [Write a Skill with the Agent](/v1/docs/use-custom-instructions-skills#write-a-skill-with-the-agent) to test and refine your Skill. ### Create a new Skill Open the **Skills** tab in step 2 of [the guidance above](/v1/docs/use-custom-instructions-skills#who-can-configure-them-and-how). Fill in three fields: | Field | What to put in it | How it is used | | --- | --- | --- | | **Name** | A short, clear label for the task, e.g. "Monthly variance commentary" | Shown to Members in the Skill library and when calling a Skill in a Chat; helps the Agent identify the Skill | | **Description** | What the Skill does and when to use it, in one or two sentences | Read by the Agent on every request to decide whether to load the Skill. See below for more information. | | **Instructions** | The full procedure: steps, rules, formats, examples | Loaded only when the Skill is used; the Agent follows it to complete the task | ### Writing the description The description is the single most important field. State both **what** the Skill does and **when** to use it, using the words Members would actually type. Use the comparison of weak and strong descriptions below to improve your Skill writing. | Weak description | Strong description | | --- | --- | | "Variance analysis" | "Writes monthly Actuals vs Budget variance commentary by cost center. Use when asked to explain, comment or summarize variances, or to prepare month-end commentary." | | "Branding" | "Applies the company brand guidelines (colors, fonts, layout) to Frames. Use whenever creating or restyling a Frame." | | "Helps with headcount" | "Reviews a headcount plan against hiring policy and flags issues. Use when asked to check, validate or review headcount or hiring plans." | ### Writing Skill instructions - **Start with the goal.** One or two sentences on what a good result looks like and who reads it. - **Separate knowledge from workflow.** Many Skills combine both. Describe background knowledge, such as your business drivers, in plain language. Write the workflow as clear, numbered steps, each starting with a trigger. - **Give the steps in order.** Numbered steps for a workflow; "When X, do Y" for conditional rules. - **Point to your model.** Name the Applications, Boards, Widgets, Metrics, Lists and Versions to use, exactly as they appear in Pigment. Exact names make an instruction clearer, so the Agent follows it more reliably. - **Specify the output format.** Length, structure, units, tone. - **Include an example.** A short sample of a good output is the fastest way to get consistent results. - **Explain the why behind rules.** Say what to do, why it matters and what goes wrong if it is skipped. The Agent reasons about your instructions, so a reason and a consequence help it handle edge cases sensibly. The example below shows how exact names turn a vague step into one the Agent can follow. The names are illustrative. | Weak step | Strong step | | --- | --- | | "When the user asks, open the OPEX board and fill the budget for each department based on historicals." | "When the user asks to fill the OPEX budget, open the Board 'OPEX Budget' and the Widget 'Input OPEX'. For each Department, enter a value on every line, based on the historical values in the Metric 'OPEX Actuals'." | ### Manage your Skills All the Skills created in or uploaded to your Application are listed in the **Skills** tab. To find this, follow [the guidance above](/v1/docs/use-custom-instructions-skills#who-can-configure-them-and-how), selecting **Skills** in step 2. Here you can: - Select a Skill created for one Agent and share it to another Agent. - Activate/deactivate Skill in this Workspace. - Edit or download the Skill - Upload a replacement Skill To edit or share a Skill: 1. In the **Skills** tab, hover over the Skill you want to manage. 2. Select the blue **Edit** button that appears. 3. Make your changes in the Edit Skill dialog. 4. (*Optional*) Under **Agent access**, select Agents from the drop-down to have access to the Skill. To upload or delete a Skill, or download a replacement: 1. In the **Skills** tab, hover over the Skill you want to manage. 2. Select the blue three-dot menu that appears. 3. Choose your action from the menu. ### Best practices - **One Skill, one workflow.** Several focused Skills work better than one large Skill that tries to do everything. - **Tune the description first.** If the Agent does not pick up the Skill, the description is usually the cause. - **Do not repeat your custom instructions.** Context that applies everywhere already lives in instructions; keep Skills task-specific. - **Disable rather than delete** a Skill you want to pause, so you can turn it back on later. ### Write a Skill with the Agent You do not have to write every detail yourself. The Agent can draft the Skill for you, and then test it on a real task. Pigment also provides a template Skill, `writing-a-skill`, that guides the Agent through this process. You stay in charge throughout: the Agent helps, but you decide what goes into the Skill. 1. **Outline the Skill in plain language.** List the background knowledge the Agent needs and, for a workflow, the steps in order. Start with a few lines. 2. **Ask the Agent to write the Skill.** Ask it to rewrite your outline in Markdown, with the exact technical details, such as Board, Metric and List names. This gives you a first version. 3. **Test it.** Ask the Agent to perform the task using the Skill. Review how it works and the result, then ask it to report what should improve. Try several phrasings that should trigger the Skill and one or two that should not. 4. **Review and repeat.** Check each suggested change before you apply it, then run the test again. Generic or padded wording can creep in when the Agent writes alone, so keep only what is accurate and useful. 5. **Finish when the results are consistently good.** Add detail only where the results fall short. As with a new colleague, a first version rarely does the job perfectly. Testing and refining is what makes the Skill reliable. ## Upload a Skill You can upload a Skill as a Markdown (`.md`) file instead of filling in the form. This may be useful when versioning Skills outside Pigment or reusing them across Workspaces. The file must start with a YAML header holding the name and description. Files without a valid header are rejected. ### File format | Part | Required | Content | | --- | --- | --- | | `name` (in the header) | Yes | Same as the Name field | | `description` (in the header) | Yes | Same as the Description field | | body (below the header) | Yes | Same as the Instructions field, in Markdown | Formatting rules: - Save the file with a `.md` extension. - Start with a line containing only `---`, then the `name` and `description` lines, then a closing `---` line. - Put quotes around header values that contain a colon (`:`) or start with a special character such as `#`. - Write the instructions as regular Markdown below the closing `---`. ### Skill library Pigment adds new Skills to this library as they become ready. The first Skill, `writing-a-skill`, helps you optimize your Skill-writing. Upload this Skill and ask your Agent to use it when you’re writing. **`writing-a-skill`** ```markdown --- name: writing-a-skill description: Guides the user through writing, testing and improving a custom skill for the Pigment agent. Use whenever the user wants to create, write, draft, rewrite, test or improve a skill, or says "teach the agent how to do X", "save this as a skill", or "make this repeatable". --- Writing a skill A skill is a short markdown file the agent loads when a task matches it. It turns "how we do X here" into steps the agent follows the same way every time. What a good skill contains Front matter — `name` (kebab-case) and `description`. The description is the only part the agent reads before deciding to load the skill, so it must say what the skill does AND when to use it, with the words a user would actually type. Weak: `description: Budget skill.` Strong: `description: Builds the yearly OPEX budget by cost center. Use when the user asks to create, rebuild or extend the OPEX budget, or mentions cost center budgeting.` Workflow steps — numbered, one action per step, in the order they must happen. Each step says what "done" looks like. Triggers and tool calls — this is what makes a step reliable. Instead of "check the data", write when to do it and which tool to call. Weak: `Make sure the list items are right.` Strong: `Before writing any formula that filters on a list item, call get_list_items on that list and use the exact item name returned.` Pattern: `Before / after / when , call to .` Knowledge — the things the agent cannot guess: naming conventions, business rules, which metric is the source of truth, known pitfalls. Keep it as short bullets, after the workflow. Keep the whole skill short. If a section does not change what the agent does, cut it. Workflow Follow these steps with the user. Do not skip the test loop. Step 1 — Get the first draft Ask the user for their content as rough bullet points: the task, the steps they follow today, and the rules they always apply. Do not ask for polished text. If they already gave bullets, go to step 2. Step 2 — Rewrite it as a skill Rewrite the bullets into the structure above: Write the front matter. Put the trigger phrases in the description. Turn each bullet into a numbered step. Where a step depends on Pigment data or structure, add the precise trigger and tool call (e.g. `search_metrics_and_lists` before referencing a block, `validate_formula` before saving a formula, `get_views` before editing a view). Move rules and facts into a short Knowledge section. List anything you had to guess as open questions for the user. Show the full skill in one block so the user can copy it. Step 3 — Test it in a fresh session Tell the user to: Copy the current skill. Open a new agent session with the skill enabled. Give it a real task the skill should handle, phrased the way a colleague would. Come back here with the result (what the agent did, what it built, where it went wrong). A fresh session matters: this session already knows the intent, so it cannot tell if the skill is clear on its own. Step 4 — Improve and repeat When the user brings back the result: Compare what happened to what the skill asked for. For each gap, say which step was missing, unclear or ignored. Fix the skill: add the missing trigger or tool call, make the step more explicit, or move a rule higher. Add the user's own comments as-is. Show the updated skill in full. Go back to step 3. Repeat until the user is happy with the result. Step 5 — Save it When the user is happy, remind them to save the skill so it is available in future sessions. Template ```markdown --- name: description: . Use when the user . --- # <One line: what this skill achieves.> ## Workflow 1. <Trigger>: call `<tool>` to <purpose>. 2. <Action>. Done when <check>. 3. ... ## Knowledge - <Rule or fact the agent cannot guess.> ``` ``` **`TODAY() function`** ```markdown --- name: building-a-today-date-logic description: Builds a dynamic "today" date in Pigment, which has no native TODAY() function. Use when the user asks for a today() function, the current date, a rolling or dynamic date, "days since/until", ageing, or a date that updates automatically every day. --- # Building a today() logic Creates a Today input metric that is refreshed every day by a scheduled metric-to-metric copy from a Tomorrow metric (Today + 1). ## Workflow 1. Before creating anything, call `search_metrics_and_lists` for "Today", "Tomorrow" and "Import" to reuse existing blocks and avoid duplicates. Done when you know which of the three already exist. 2. Before creating blocks, call `search_folders` with `path_regexes` such as `admin|settings|config` to find a settings folder. Use it for all three new blocks. If none exists, create the blocks at the root. This overrides the "0. Dimension" folder rule for `Import`. Do not ask the user. 3. Before the first write, call `unlock_toolset` with `block_edits`. This unlocks `create_list`, `add_list_items`, `create_metric`, `bulk_update_metrics`, `set_metric_input` and `create_metric_copy_config`. Load `creating-dimensions-and-hierarchies`, `creating-metrics-and-tables`, `writing-pigment-formulas` and `copying-metric-data` before using them. 4. Create the dimension list `Import` with a unique `Name` property, then add exactly 1 item named "Import" with `add_list_items`, unless it already exists. Done when the list has a single item. 5. Create the metric `Today`: type Date, dimensioned by `Import`, no formula (manual input), with a description. The metric cannot be scalar, which is why it uses the 1-item dimension. Set no default format, no aggregators and no view layout. There is no time dimension and the metric has a single cell. Done when `Today` exists with `Import` as its only dimension. 6. Create the metric `Tomorrow`: type Date, dimensioned by `Import`, created without a formula first, because `validate_formula` needs an existing target metric. 7. Call `validate_formula` with the formula `'Today' + 1` and `target.metric_id` set to Tomorrow. Then call `bulk_update_metrics` on Tomorrow with the formula and the `validation_ticket_id`. Done when the update returns no failure. 8. Seed the initial value. Use the current date from the system prompt's "Today is …" line. If it is not there, call `ask_user` for today's date. Call `set_metric_input` on `Today` for the single `Import` item, using an ISO date (`YYYY-MM-DD`). Done when `Today` shows the current date. 9. Call `get_metric_to_metric_copy_configs` on `Today`. If none exists, call `create_metric_copy_config` with source `Tomorrow`, target `Today` and clear mode `none`. The single `Import` cell is overwritten on each run, so nothing needs clearing. Done when a saved config exists. 10. Scheduling is UI-only. Do not claim it is scheduled. Give the user these steps: **Data Actions and Flows → Scheduling → New schedule → Schedule an import**. Pick `Today` and the saved config, set the start time (shortly after midnight), choose the **time zone** explicitly, and set **Repeat** to daily. They need the Configure Imports and Run Imports permissions. Call `documentation_assistant` to confirm the steps if unsure. 11. Before replying, call `data_validator` with one sentence of intent plus the ids of `Today` and `Tomorrow`. Done when `Today` equals the seed date and `Tomorrow` equals the seed date + 1. ## Knowledge - Pigment has no native TODAY() function. This pattern is the workaround. - Keep the names `Import`, `Today` and `Tomorrow` unless the user objects. - `Today` must never be scalar. It always carries the 1-item `Import` dimension. - `Today` is an input metric (no formula). Its only writer is the scheduled copy from `Tomorrow`. - `Tomorrow` = `Today + 1`. Each daily run copies it into `Today`, so `Today` advances one day per run. - The schedule's time zone is chosen in the schedule itself, not taken from the workspace. Pick the zone the user's "today" should follow. - If the schedule stops running, `Today` stays frozen on the last date. - Out of scope: using `Today` in downstream formulas, formatting, and View layout. ``` ### Common reasons an upload is rejected | Error | Fix | | --- | --- | | Missing or invalid header | Start the file with `---`, then `name` and `description`, then a closing `---` | | Missing required field | Check that `name` and `description` are both present and lower case | | Value cut off or misread | Wrap header values containing `:` in quotes | | Empty instructions | Add the instructions below the closing `---` | | Wrong file type | Save as `.md`, not `.txt` or `.docx` | ## FAQ **The Agent does not use my Skill. What should I check?** First, check that the Skill is enabled for the right Agent. Then rewrite the description so it states clearly when to use the Skill, with the words Members actually type. You can also ask a Member to call the Skill directly to confirm the instructions work. **The Agent ignores one of my custom instructions.** The Agent reasons about every instruction, so it is not fully predictable. Make the instruction more specific, explain why it matters and what goes wrong if it is skipped, and check it does not contradict another rule. If your instructions have grown long, move task-specific parts into a Skill. **Can I set different instructions for one Application or team?** No. Custom instructions and Skills are set at Workspace level and apply to all Chats and Members. For team-specific workflows, create a dedicated Skill with a description that names the team or process. **Do instructions or Skills give the Agent access to more data?** No. The Agent always works within the access rights of the Member using it. **What happens if a Skill and the custom instructions disagree?** The Agent tries to follow both, which can lead to inconsistent results. Keep general rules in instructions, task-specific rules in Skills, and avoid restating the same rule in both places. **Can I edit a Skill I uploaded?** Yes. Uploaded Skills can be edited in the form like any other Skill, or replaced by uploading a new version of the file. ## Related - [Build and Run Custom Agents](/create-custom-agents.md) - [Create experiences with Frames](/create-frames.md) - [Try out these Frames prompts](/frames-prompts-and-techniques.md)