Composing Agents & Skills

This guide ties the pieces together: how Skills, an Agent's instructions, and Chat's MCP tools combine into a purpose-built chat experience, and how to design an Agent deliberately.

The mental model

An Agent is a composition of three layers, each doing a distinct job:

1. Instructions: the persona. Who the assistant is, how it talks, what it's for, and the rules it always follows.
2. Skills: the capabilities. The specific, executable tasks the assistant can perform.
3. Recommended prompts: the starting points. Ready-made prompts that show users what to ask and lead the assistant to the right Skill.

These layers combine at runtime with Chat's Skill MCP tools. When someone chats with the Agent:

• The instructions are injected into the system prompt for the whole conversation.
• The Agent's Skills become the only Skills the chat can see. The Skill tools are scoped to exactly the Skills you attached. The assistant discovers them with skill_list, then runs each one either inline in the conversation (load_skill) or in its own isolated session (skill_execute), at its discretion.
• The recommended prompts pre-fill the chat input to start a user down a path that naturally invokes one of those Skills.

In short: you build Skills to do the work, write instructions to set the persona, and add recommended prompts to point users at the right Skill. Chat's MCP tools wire it together at runtime.

Two independent levers

An Agent gives you two levers, and they work independently:

1. Instructions change the system prompt for the whole conversation. This is the persona, tone, expertise, and rules.
2. Skills define the set of executable capabilities the chat can reach (and nothing outside that set).

Use either or both. Reach for Instructions when the value is in how the assistant behaves, and Skills when it's in what specific tasks it can run.

Agents are useful with no Skills at all

An Agent with instructions but no Skills is already valuable. All it does is reshape the system prompt, but that's often exactly what you want: a "Brand Voice Editor" that rewrites anything you paste in your house style; a "Socratic Tutor" that only ever answers with guiding questions; a "Contract Reviewer" that reads with a specific risk lens. These need no packaged capability, just a durable persona applied to an open-ended conversation.

Reach for an instructions-only Agent when the job is a way of thinking or responding rather than a set of discrete tasks. You can always add Skills later.

Add Skills when you need packaged, repeatable execution

Add Skills when the Agent needs to do specific things the same way every time: produce a defined output (an artifact of a set type) or perform a side effect (a write through an integration), with the right model and tools already wired in. A Skill is a self-contained capability the Agent can invoke; the Agent supplies the persona, the Skill supplies the packaged execution.

How a turn flows

When a user sends a message to an Agent (for example, by clicking a recommended prompt and hitting send):

1. The Agent's instructions are already in the system prompt, so the assistant responds in character.
2. If the request matches one of the Agent's Skills, the assistant calls skill_list / skill_get (scoped to the Agent's Skills) to find it, then runs it.
3. The assistant picks how to run it: load_skill pulls the Skill's instructions into the conversation itself, so the work is driven by the ongoing discussion and uses everything already said; skill_execute runs the Skill in its own isolated session with the Skill's own model and tools, and returns the result into the conversation. Conversation-driven work favors inline; large or context-free work favors isolation.
4. The assistant can chain Skills, feeding one Skill's output into another, or combine a Skill's output with other MCP tools (Knowledge search, web search, artifact creation) before replying.

Because the Skill tools are scoped, the assistant never wanders off into unrelated Skills, and the experience stays focused on the job the Agent was built for.

Skill or recommended prompt?

When you want to give an Agent a specific capability, you have two very different tools, and picking the right one is the core composition decision:

• A Skill is executable. The Agent can run it inline in the conversation (load_skill) or as an isolated, subagent-style session (skill_execute) with its own context, model, and tools. Use a Skill to encapsulate a reusable unit of work that should run reliably and identically wherever it's invoked.
• A recommended prompt is just text. It pre-fills the chat input to start the user down a path; nothing executes on its own. Use it as a suggested starting point, not as the mechanism that does the work.

Choose a Skill when…	Choose a recommended prompt when…
The work is a repeatable, well-defined task	You just want to suggest a good way to start a conversation
It needs specific tools, a specific model, or a defined output type	The main chat's tools and model are fine
The work should be packaged and repeatable, whether run inline or in isolation	You just want to shape how the conversation starts
The same capability is reused across Agents, Workflows, or the API	It's specific to how this Agent should be kicked off

The two combine naturally: write a recommended prompt whose text leads the Agent to invoke a Skill. The prompt is the starting point ("Analyze last quarter's sales"); the Skill is what actually runs when the user sends it. Recommended prompts point at capabilities; Skills are the capabilities.

Designing a chat experience

Building an Agent is a design exercise. Work backward from the experience you want:

1. Name the job

Decide what conversation this Agent should be great at: triage a support ticket, draft a project proposal, analyze a spreadsheet. One clear job per Agent beats a vague do-everything assistant.

2. Assemble the Skills (if any)

Decide whether the job even needs Skills. If the value is in how the assistant behaves, an instructions-only Agent may be complete; skip to the next step. If the job involves concrete, repeatable tasks, identify those capabilities and gather or build the Skills for them. Attach only the Skills that belong to this job. A smaller, focused set keeps the experience sharp, since these become the only Skills the chat can run. Reuse existing Skills where you can; an Agent is a good way to bundle Skills your team already relies on.

3. Write the instructions

Set the persona and the rules. Cover tone and expertise, and tell the Agent how to use its Skills. For example: "When the user describes a support issue, use the Triage Skill before suggesting a response." See Prompt Engineering → Agent instructions for how to write these well.

4. Add recommended prompts

Write a handful of recommended prompts; one per major Skill is a good rule of thumb. Phrase each so that sending it leads the Agent to the Skill you intend (mirror the Skill's job in the prompt text). For a guaranteed trigger, write the prompt as a slash command (/sprint-summary for the current sprint), which explicitly runs that Skill when sent. Together the prompts teach a new user everything the Agent can do, in the Agent's own voice.

5. Scope the surrounding context

The Agent runs inside the rest of your chat context. Your project, Knowledge access, and any org- or instance-level system prompt still apply. Make sure the Skills' own tool and Knowledge configuration matches what the experience needs.

6. Test it by chatting

Chat with the Agent, click each recommended prompt, and confirm it triggers the Skill you expected and responds in the right voice. Iterate on the instructions and prompts the same way you'd iterate on any prompt.

Worked examples

Brand Voice Editor (instructions only, no Skills)

• Instructions: "You are our brand copy editor. Rewrite anything the user pastes in our house voice: warm, plain-spoken, active, no jargon. Preserve meaning; return only the rewrite."
• Skills: none.
• Recommended prompts: "Rewrite this in our brand voice", "Tighten this paragraph".
• Result: A useful Agent with zero Skills. All of its value is in reshaping the system prompt, applied to whatever text the user provides.

Support Triage Agent

• Instructions: "You are a calm, empathetic support specialist. Always classify the issue before proposing a fix, and never promise a refund without escalation."
• Skills: Classify Ticket, Draft Support Reply, Search Help Center (a Knowledge-backed Skill).
• Recommended prompts: "Triage this customer message", "Draft a reply to an angry customer about a late order".
• Result: A focused conversation where skill_execute only ever reaches the three support Skills, and the assistant stays in support voice throughout.

Proposal Writer Agent

• Instructions: "You are a senior proposal writer for our agency. Use our standard structure and pull facts only from the project Knowledge Base."
• Skills: Draft Proposal, Build Estimate, Executive Summary.
• Recommended prompts: "Start a proposal for a new client engagement", "Summarize this proposal for an executive audience".
• Result: Clicking a prompt kicks off the matching Skill, and the Agent can chain Draft Proposal → Executive Summary in one conversation.

Data Analyst Agent

• Instructions: "You are a data analyst. Explain your reasoning step by step and show the numbers behind every conclusion."
• Skills: a spreadsheet-analysis Skill plus a charting Skill.
• Recommended prompts: "Analyze the attached sales spreadsheet", "Find the top three trends in this data".

Tips & anti-patterns

• Assign one job per Agent. If you're tempted to attach a dozen unrelated Skills, that's usually two or three Agents.
• Recommended prompts are snippets, not Skills. They don't execute anything themselves; they pre-fill text. See Recommended Prompts vs. Skills.
• Keep instructions about behavior, not a single task. Per-task detail belongs in the Skills and the conversation, not the persona.
• Reuse Skills across Agents. A well-built Skill can power several Agents; you don't need to duplicate it.

Next Steps

• Creating & Managing Agents: the mechanics of building an Agent
• Chatting with an Agent: what the experience feels like for users
• MCP Tools → Skill Tools: how Skills are discovered and run in chat
• Building a Skill: create the capabilities you'll compose