Why Isn't My Agent Using the Skill I Created?

Last updated: March 21, 2026

The most common reason is that the skill's description doesn't match what you're asking the agent to do — the agent uses the description to decide which skill to load. Other causes include the skill not being attached to the right agent, or the required integration not being connected.

How Skill Loading Works

Before diving into fixes, it helps to understand how the agent decides to use a skill:

  1. When a conversation starts, the agent sees a list of available skill names and descriptions — not the full instructions.

  2. When you send a message, the agent scans those descriptions to decide if any skill is relevant.

  3. If a match is found, the agent reads the full SKILL.md from the sandbox and follows the instructions inside.

If the agent never gets past step 2 — i.e., the description doesn't seem relevant to your request — the skill is never loaded.

Cause 1: The Skill Description Is Too Vague

This is the #1 reason. The agent matches skills based on their description field in the SKILL.md frontmatter. A vague description means the agent can't tell when to use the skill.

❌ Bad description

✅ Good description

Helps with reports

Generate weekly sales performance reports from Google Sheets data, formatted as Markdown tables with week-over-week comparisons. Use when the user asks for sales reports, weekly metrics, or team performance.

Email stuff

Draft personalized cold outreach emails for sales prospects. Use when the user asks to contact, email, or reach out to a prospect.

How to fix: Edit the skill's description to be specific about what it does and when to use it. Include the keywords a user would naturally use when asking for this task.

Cause 2: The Skill Isn't Attached to the Agent (Custom Agents)

Custom agents only see skills that are explicitly attached to them. Creating a skill in your workspace does not automatically make it available to all your custom agents.

How to check: Open your custom agent's configuration → scroll to the Skills section → verify the skill is listed there.

How to fix: Click + Skill in the agent's configuration and select the skill from the list.

Note: The general agent (the default chat at gumloop.com/chat) works differently — it has access to all skills in your workspace automatically. You don't need to attach skills to it. See the next article for details on this difference.

Cause 3: Your Request Doesn't Trigger the Skill

Even with a good description, the agent might not load the skill if your message doesn't seem related to it.

Example: You have a skill called weekly-sales-summary with a description about generating sales reports. If you say "give me numbers from last week," the agent might not connect that to a sales report skill.

How to fix: Be more explicit in your request. Try: "Generate a weekly sales summary using the sales summary skill." You can directly reference the skill name to make it unambiguous.

Cause 4: The Skill Depends on an Integration That Isn't Connected

If a skill's instructions tell the agent to call Google Sheets, Slack, Salesforce, etc., but that integration isn't connected to the agent, the skill will load successfully but fail at execution. There is no automatic dependency check — the skill loads, the agent tries to use the tool, and then gets an error.

How to check: Open the agent's configuration → Tools section → verify that the integration the skill depends on is listed and connected.

How to fix: Add the required integration to the agent from the Tools panel. The skill's related_server_ids frontmatter field (if set) is a hint about what integrations it needs, but it's not enforced automatically.

Cause 5: Too Many Skills Attached (Token Overhead)

Each skill attached to a custom agent adds roughly 50–100 tokens to the system prompt (for its name and description). If you have a very large number of skills attached, the agent's context window gets crowded, which can make skill matching less reliable.

How to fix: Keep the number of attached skills focused and relevant to the agent's purpose. If you need access to a large skill library, use the general agent instead — it uses semantic search to find skills dynamically rather than listing all of them in the system prompt.

Tip: Use the System Prompt to Guarantee Skill Usage

If there's a skill your agent should use every time for a specific type of request, add an explicit instruction in the agent's system prompt. The system prompt loads with every conversation — unlike skills, which are loaded on demand — so instructions there are always active.

For example, adding this to your system prompt:

When the user asks to draft an outreach email, always load and follow the "email-outreach-playbook" skill.

This removes the guesswork from skill matching. The agent no longer has to infer which skill to use from the description — you've told it directly.

When to do this:

  • A critical skill that the agent should never skip for certain tasks

  • A skill whose description is hard to make unique (e.g., multiple similar skills)

  • A skill the agent has previously failed to pick up on its own

When not to do this:

  • Skills that only apply occasionally — keep the system prompt lean and universal. If a skill only applies to 1 in 10 conversations, let the agent discover it naturally from the description.

Quick Checklist

  1. ☐ Is the skill's description specific about what it does and when to use it?

  2. ☐ Is the skill attached to the correct agent? (Custom agents only — general agent has all skills.)

  3. ☐ Does your message clearly relate to what the skill's description says?

  4. ☐ Are the integrations the skill depends on connected to the agent?

  5. ☐ For critical skills, have you added an explicit reference in the system prompt?

Related Docs

Still Need Help?

If this didn't resolve your issue, reach out to support at support@gumloop.com.