HomeGuru CommunityProduct TrainingSupport PortalDeveloper Network
Guides

📘 Best practices: Building Agent Skills

Agent Skills are configurable behavior modes that define how a Knowledge Agent handles a class of questions or workflows. A single Knowledge Agent can hold many Skills — the agent reads each Skill's description and automatically routes user messages to the best match.

This article walks through how to plan, write, and refine a Skill that works reliably from day one.

👥

Access Required

You must be a Knowledge Agent Owner, Admin, or relevant custom role to create or edit Skills.

Start with the workflow, not the Skill

Before writing anything in Guru, map the workflow you want the Skill to handle. Every effective Skill starts from a clear answer to four questions:

  1. What outcome does the user need? Frame this as a result, not a feature. "Get a troubleshooting resolution for a VPN issue" is an outcome. "Use the IT knowledge base" is a feature.
  2. What steps does the workflow require? Write out the sequence a human expert would follow to produce that outcome. This becomes the backbone of your Skill instructions.
  3. What tools and sources does the Skill need? Determine whether it pulls from Guru sources, takes action via MCP connections, uses built-in tools like the user profile tool, or some combination. Built-in tools don't require separate setup — you reference them directly in the Skill instructions.
  4. Does this belong on an existing Knowledge Agent or a new one? If permissions aren't a concern, adding the Skill to an existing agent is usually better for adoption — users don't need to learn a new agent exists.
💡

Tip

If you can't describe the outcome in one sentence, the Skill's scope may be too broad. Consider splitting it into two Skills.

Write the description first

The description is the most important field on a Skill. The agent uses it — not the instructions — to decide which Skill to invoke for a given message. A vague description causes misfires. A precise one produces reliable routing.

A strong description answers three things in one or two sentences: what the Skill does, when it should activate, and what its key capabilities are.

Weak vs. strong descriptions

❌ Weak: "Helps with customer questions."

The agent can't distinguish this from any other Q&A Skill. It will fire unpredictably or compete with other Skills for the same messages.

✅ Strong: "Creates a customer case study from a Gong transcript. Use when someone says 'write up the [customer] story' or 'turn this into a case study.' Extracts problem statement, measurable outcome, and customer quote."

This description names the specific artifact (case study), the specific input (Gong transcript), the trigger phrases a user would actually type, and the key elements the Skill produces. The agent knows exactly when to invoke it — and when not to.

Description checklist

  • Names the specific task or artifact the Skill produces.
  • Lists trigger phrases — the actual words a user would type to activate this workflow.
  • States the input type (transcript, Slack thread, ticket, etc.) if the Skill expects one.
  • Does not overlap with any other Skill's description on the same Knowledge Agent. Test this by asking: if someone typed a sample request, would this description and another Skill's description both seem like a match? If yes, tighten the language until the boundary is unambiguous.

Structure the instructions

Instructions control what the agent does once a Skill is invoked. Write them like onboarding documentation for a new hire — explicit enough that someone unfamiliar with the workflow could follow them without guessing.

📘 Best practices

  • Be explicit about expected outputs. Don't just say "create a case study." Define what sections the Skill should produce, how long each should be, and what counts as a good response versus a bad one.
  • Use numbered steps. Define the workflow as a sequence. Show expected outputs at each stage and call out critical validations explicitly.
  • Build in error handling. Anticipate what can go wrong and tell the agent what to do when it happens. If a required input is missing, should the agent ask the user, skip the section, or flag it? Spell it out.
  • Keep reference data in sources, not instructions. If the Skill requires deep domain knowledge (product specs, policy details, pricing), reference Guru Cards as sources rather than pasting large blocks of facts into the instructions. Instructions control behavior; sources control content.
  • Include examples. The Examples section of the prompt template is one of the highest-leverage parts. A single concrete input/output pair often does more for consistency than a paragraph of rules.

Follow three design principles

One Skill, one job

When a Skill only handles one task, you always know which one to fix when something breaks. If the agent produces a different type of output, that should be a different Skill.

✅ "Draft a case study from a Gong transcript"

❌ "Handle all content creation, outreach, and follow-up"

A good test: if you removed this Skill, would users lose exactly one capability? If they'd lose several, the Skill is doing too much.

No description overlap

If two Skills on the same agent could both match the same user message, the agent can't route reliably. Before adding a Skill, compare its description against every existing Skill on that agent.

Example of overlap to fix:

  • Skill A: "Answers questions about company policies and HR topics."
  • Skill B: "Helps employees understand their benefits, PTO, and leave options."

A question like "How much PTO do I have left?" would match both. The fix: narrow Skill A to exclude benefits/PTO/leave topics, and make Skill B the explicit owner of that territory.

Start small, then expand

Test one Skill on a narrow use case before building a library. Enable AI Agent Center tracking on the Skill, observe the results over a few days, and refine before adding the next one.

Connect MCP tools because they fill a real gap in the workflow — not because the option is available. Each added connection is a new surface area to maintain and debug.

Keep your sources healthy

A well-configured Skill still produces bad answers if the content it draws from is outdated, incomplete, or contradictory. Source quality is the single biggest factor in answer quality — more than the description or the instructions.

Turn on quality automations. Automated verification and automated card management (auto-archive and duplicate detection) keep your sources current without manual review cycles. Auto-verify is enabled by default; auto-unverify can be enabled in the Quality tab when you're confident in your rules. Together, these automations ensure that outdated or redundant content is flagged or removed before it affects answers.

Audit your sources regularly. Use the Sources tab in the AI Agent Center to see which documents your Skills are actually citing. Sort by usage to find your most-cited sources (these are worth keeping current), filter to unverified content to find material being relied on without review, and look for connected sources that are never cited — they may be adding noise without value.

Fill gaps, don't just fix errors. When a Skill can't answer a question, the issue is often that the source content doesn't exist yet — not that existing content is wrong. Use the AI Agent Center to identify unanswered questions, then create the Guru Cards or connect the sources needed to close the gap.

Track and improve with the AI Agent Center

Each Skill has an independent AI Agent Center tracking toggle. When tracking is enabled, Guru runs post-processing on each invocation — extracting citations, generating explanations, and labeling the result as answered or unanswered. This creates a reviewable record in the AI Agent Center. Each tracked invocation costs 1 credit. The default Answer Skill has tracking on; the default Research Skill has tracking off.

Diagnose problems with Answer Details

When a Skill produces an unexpected answer, click Answer Details on the question in the AI Agent Center. The panel shows the reasoning behind the answer, which sources were cited, which sources were sent to the model but not cited, the search terms extracted from the user's question, and the most relevant sources in priority order.

This tells you exactly where the breakdown occurred. If the right source was sent but not cited, the content may need to be rewritten for clarity. If the right source wasn't sent at all, the Skill's connected sources or the search terms need attention.

Use AIAC querying to spot patterns

Instead of reviewing questions one by one, query your AI Agent Center data by asking your Knowledge Agents in the chat for insights about questions and answers. Try prompts like:

  • "What are the top trending questions for this agent over the last 30 days?"
  • "Which questions went unanswered in the last 30 days?"
  • "What topics are getting the most thumbs-down feedback?"
  • "Which sources are being cited most frequently in flagged answers?"

These patterns point to systemic issues — content gaps, description overlaps, or instruction weaknesses — that you'd miss looking at individual questions.

Common patterns and fixes

  • Skill fires on the wrong queries. The description is too broad or overlaps with another Skill. Tighten the description language.
  • Skill fires correctly but outputs are weak. The instructions need more specificity — add steps, examples, or constraints. Also check whether the source content supports the output the instructions are asking for.
  • Skill doesn't fire when it should. The description is missing trigger phrases that match how users actually phrase their requests. Review recent questions in the AI Agent Center to find the real language users are typing.
  • Answers are outdated or contradictory. The issue is in the source content, not the Skill. Review the cited sources for accuracy and turn on quality automations to prevent recurrence.
✍️

Note

Enable tracking for Skills where you need quality metrics and improvement signals. For lightweight or experimental Skills, leave tracking off to reduce noise.

For a full walkthrough of the AI Agent Center's monitoring, filtering, and querying capabilities, see Guru's AI Agent Center.

Template gallery

Creating Guru Cards on known issues

Use this template to configure a Skill that turns unstructured sources — Slack threads, support tickets, IT tickets, meeting recordings, call transcripts, or freeform notes — into clean, scannable known-issue Cards.

Troubleshooting issues

Use this template to configure a Skill that deflects IT-related tickets by walking users through dynamic troubleshooting questions. If the issue cannot be solved without IT intervention, this Skill can direct to another Skill to open a ticket in your preferred ticketing tool.

Taking action in other systems

Use this template to configure a Skill that can search, assign, transition, and create items like issues and comments in your IT platform of choice.

Frequently asked questions about Agent Skills

Do users need to select a Skill when they ask a question? No. The agent reads Skill descriptions automatically and routes each message to the best match. Users interact with the Knowledge Agent the same way they always do.

What happens if no Skill matches the user's message? The agent falls back to its default behavior — answering the question using its configured sources and prompt, without invoking a specific Skill.

Can Skills use MCP connections? Yes. Skills can take action in connected tools like Slack, Jira, and Salesforce through MCP connections. The MCP server must be enabled at the workspace level and added to the Knowledge Agent before a Skill can use it.

Where do Skills work? All Guru surfaces — web app, Slack, browser extension, API, and MCP.

How do I know if my Skill is working well? Enable tracking in the AI Agent Center and review invocation records. Look for questions where the Skill fired but the output was weak (instructions or content issue), questions where it didn't fire but should have (description issue), and questions where it fired but shouldn't have (overlap issue). Use Answer Details to diagnose individual answers and AIAC querying to spot patterns over time.

👀

Want a closer look at some key Guru features and best practices?

Check out our events page for demos, workshops, new release roundups, Getting Started bootcamp, guest panelists, and more. For upcoming live events and past recordings: Click here to register


Updated about 4 hours ago