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.

​

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.

​

Write one clear outcome per step

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 what should happen in the step and what “done” looks like.
• 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.

​

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.

​

Keep Plans short

A Plan works best as a short, focused sequence. The more steps it has, the more room there is for the agent to drift, and the harder it is to maintain. As a guide, aim for around 10 steps or fewer per Plan. This isn’t a hard limit, Mindset AI doesn’t enforce one, but shorter Plans run more reliably, which matches what works across agent platforms generally. If a process needs more, split it into smaller Plans that each do one job. Keeping an agent’s set of Plans and Skills focused also helps the agent choose between them cleanly.

​

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