Plans and Skills best practices

These tips come from how the agent actually uses Plans and Skills. Following them helps your agent pick the right Plan, work through it cleanly, and reach for the right knowledge. For Plans that call tools, see the companion guide Using tools in Plans.

​

Name, handle, and description: write each for its reader

A Plan has three fields, and they serve two different audiences. Knowing who reads each one tells you how to write it.

• Name is for your end users. It’s what they see on the welcome card or in the prompt menu, so make it clear and friendly to them.
• Handle is for the agent. It’s how the agent identifies the Plan, so make it a clear, meaningful name for what the Plan does, like onboard_new_employee, not plan_1.
• Description is also for the agent. It’s what the agent reads to decide when to run the Plan, so be specific about the situation or request that should trigger it.

The handle and description are both read by the agent, and together they’re how it picks the right Plan, so getting both clear makes triggering predictable. A vague handle or description makes the agent fire the wrong Plan, or miss it entirely.

• Weak description: “Onboarding.”
• Strong description: “Use this when a manager wants to onboard a new team member, covering account setup, team assignment, and orientation.”

Skills work the same way for the agent: its handle and description are what the agent reads to decide when to use it. Users don’t see Skills directly, so there’s no user-facing name to worry about there.

​

Keep every name and handle unique

This is the one to get right, because a clash can surface as an error to your end users, or quietly change how your agent behaves. A Plan’s handle, a Skill’s handle, and the name of every tool an agent uses all live in one shared namespace, and the AI model behind your agent (such as Anthropic or OpenAI) requires every name in that set to be unique. If an agent is assigned two items that share a name, for example a Plan and an external tool, or a Skill and a tool, the model provider rejects the request when the agent goes to use them. Your end user then sees an error that comes from the AI provider, not from Mindset AI, which makes it confusing to trace. To reduce that risk, Mindset AI removes one of the clashing items before the request reaches the model, so the model doesn’t receive a duplicate. The trade-off is that you don’t control which one is kept and which is dropped. Your agent can end up reaching for the wrong Plan, Skill, or tool, or missing the one you meant it to use, so the experience becomes unpredictable. This safeguard also can’t be guaranteed on every path, so in some cases the end user can still see the provider’s error. Either way, a name clash means you no longer know exactly what your agent will do. External tool names aren’t something Mindset AI controls, since those tools come from your integrations, so a clash with a Plan or Skill is possible. The Agent Management Studio warns you when it spots one, so it’s easy to catch and fix. Keeping names distinct is the simplest way to avoid surprises. To stay safe:

• Give every Plan, Skill, and tool on an agent a distinct, descriptive name and handle.
• When the Agent Management Studio warns you about a name clash on an agent, take it seriously and resolve it before you rely on that agent. It checks across the agent’s Plans, Skills, and tools.
• Avoid generic handles like search or lookup that an external tool might also use.

​

Make sure the Plan actually starts

The agent picks a Plan by matching what the user said against each Plan’s description. That match is the part that most often catches people out. Two things make it reliable. First, give users a clear way in. Add the Plan to a welcome card or the prompt menu (the sparkle icon). Both send the Plan’s exact name into the chat as the user’s message, so you control the words the agent has to work with. That’s far more reliable than hoping a user free-types something the agent has to interpret against the description. Second, keep the description specific and the name distinct. The description is the trigger, so be explicit about the scenario or user request that should run the Plan. And because the name is what a welcome card or prompt menu sends as the user’s message, keep names clear, instruction-like, distinct from each other, and away from topic- or knowledge-sounding words. A Plan called “Search courses”, for example, could read to the agent as a knowledge-search request rather than a Plan-triggering one. For vague requests, add a short rule to the agent’s Policy Rules:

If a user’s request could be handled by one of your plans but it’s unclear which, ask them to confirm which plan, then start it.

This turns a loose request like “I need to offboard someone” into an offer of the matching Plans, so the user can pick one. Otherwise the agent may answer off the cuff and never start a Plan.

​

Write clear, specific steps

The agent reads each step, works through it, and decides when it’s done before moving on. Steps with a single, clear outcome let it advance cleanly. Steps that are vague, or that bundle several actions together, can make the agent stall or jump ahead.

• Say plainly what should happen in the step and what “done” looks like. Short, direct instructions are the most reliable and easiest to maintain.
• Ask explicitly for any information the agent needs from the user.
• Keep one action per step. If a step is really three things, make it three steps.

Don’t assume the agent knows the specifics. If a step acts on a particular record or Human (an employee, an order), open the Plan with a step that finds or lists the options and asks the user to choose. Otherwise the agent stalls asking for an ID the user doesn’t have. A good shape is list → choose → act.

​

Keep a Plan as short as the job needs

Aim for around 10 steps. Short Plans finish quickly and reliably. Up to around 15 is fine. If a Plan is heading past 20 steps, split it into two Plans (or fewer, larger steps). Very long Plans lean on the conversation continuing turn after turn, and reliability tails off. A Plan can reliably run up to around 30 steps, but treat that as the ceiling, not the target. Keep long Plans simple, and test yours. The length itself matters less than how much each step tries to do. A longer Plan with light steps is more reliable than a short one with heavy steps. See Using tools in Plans for why.

​

Choose strict step order deliberately

The Strict step order setting changes how closely the agent follows your steps.

• On: every step runs, in order, nothing skipped. Use this when each step has to happen every time, such as an intake where you need every detail.
• Off (flexible): the agent can skip a step when the answer is already in the conversation, so it doesn’t ask the user twice.

One thing to watch: if your agent has Memory turned on, a flexible Plan may reuse details the user gave in an earlier conversation and skip that step. If you always want the agent to ask, turn Strict step order on.

​

Use Plans for process, Skills for knowledge

A Plan is a sequence of steps: what should happen, and in what order. A Skill is knowledge the agent applies: how to do something well. Don’t pack reference material or guidelines into step instructions. Put that in a Skill and attach it to the Plan. It keeps your steps readable and your knowledge in one place. Plans and Skills work together, but they don’t have to. You can give an agent a Plan with no Skills, a Skill with no Plan, or both. Attaching a Skill to a Plan is optional, and when you do, it enhances the Plan by giving the agent extra knowledge while it runs. Write each Skill as a standalone piece of knowledge on a single topic, so you can attach it to several Plans and agents. Update it once, and everywhere it’s used benefits. Remember the two fields do different jobs: the description says when to use the Skill, the content is what the agent draws on. Keep each Skill focused and concise, with one topic per Skill. There’s no character limit on a Skill’s content in Mindset AI, but one to two pages is the sweet spot, and that’s where Skills are most effective. Industry standards treat around 500 lines, roughly 8 to 10 sides of A4, as an upper limit, so if a Skill is approaching that, it’s a sign to split it into separate Skills.

​

Connect the right knowledge

While a Plan runs, the agent can search the knowledge connected to it. Make sure the agent has the knowledge it needs, and keep that knowledge relevant and focused, so the agent retrieves the right thing rather than something loosely related.

​

Test before you roll it out

Because the agent interprets each step and chooses Plans from their descriptions, run each Plan end to end before you rely on it. Check that:

• It triggers when you expect, and doesn’t fire when it shouldn’t.
• The agent works through every step and reaches the outcome you wanted.
• It still behaves well when a user goes off-script or gives information out of order.

Adjust the step wording and the description based on what you see, then test again.

​

Next steps