Skip to main content
Skills teach your agents how to do specific work your way, and get better at it over time.
The Skills page in Gumloop showing skill management and creation options

What is a skill?

A skill is a reusable set of instructions (and optionally templates and scripts) that teaches an agent how to do a specific task. Think of a skill as a playbook your agent can pull out when it needs it:

Example: outreach emails

A step-by-step outreach process, your templates, and follow-up rules.

Example: support triage

An escalation checklist, severity rules, and response templates.

Example: weekly reporting

Which KPIs to include, the exact format, and optional scripts to compute metrics.
Skills can feel like memory, because the agent can update them after you give feedback. Technically, it is not remembering your conversation. It is updating a shared playbook that gets reused in future conversations.
This is the superpower: when your agent makes a mistake and you correct it, the agent can update the relevant skill so it does it right next time.
You: “Reply to this customer email. Keep it short and friendly.”
Agent: [replies, but uses the wrong sign-off]
You: “We never sign off with ‘Best’. Use ‘Thanks’ instead.”
Agent: “Got it. I updated the relevant skill so future replies use ‘Thanks’.”

Why Skills?

When you set up an agent, you typically give it two things:

System Prompt

Defines who the agent is. “You’re a sales assistant. Be professional.” Always active, always loaded.

Tools

Gives the agent hands. Gmail, Salesforce, Slack, etc. The raw ability to take actions.
That gets you an agent that can send emails and update your CRM. But it doesn’t know your outreach process, your email templates, or your follow-up rules. It’s winging it every time.
Skills fill that gap. A skill is a set of instructions, templates, and even executable scripts that teach your agent exactly how to do a specific task. Your agent can read, follow, improve, and even create skills on its own.

The New Employee Analogy

The simplest way to understand skills is to imagine you just hired someone new.
What you give themAgent equivalentWhat it does
Job description & company handbookSystem promptDefines who they are, their tone, and universal rules. Always active.
Software logins (Gmail, Salesforce, Slack)ToolsGives them the raw ability to take actions.
Training materials & SOPsSkillsTeaches them your specific processes, templates, and best practices.
Without skills, your agent has access to email and CRM but improvises every time. It might send a decent email, but it won’t follow your specific outreach sequence, use your templates, or log things the way you want. Skills are the difference between “an AI that can send emails” and “an AI that follows our exact outreach process.”

When Do You Need a Skill?

Not everything needs to be a skill. Here’s a quick guide:
Put it in the system prompt if it applies to every single conversation:
  • Agent personality and tone
  • Universal guardrails (“Never share pricing without approval”)
  • Response format rules
The system prompt is always loaded in full. Keep it short and universal.
Rule of thumb: If your instructions are over 200 words and don’t apply to every single conversation, they belong in a skill, not the system prompt.
ScenarioSystem PromptToolSkill
”Be friendly and professional”
“Send this email for me”
“Draft outreach emails using our 5-step sequence”
“Generate a weekly sales report with specific KPIs”
“Never delete customer data without confirmation”
“Triage support tickets using our escalation matrix”

How Agents Use Skills

Here’s what happens behind the scenes:
Skill-Tool Dependencies: If a skill is designed to use a specific integration (e.g., Salesforce, Gmail) but that integration is not connected to the agent, the skill will load successfully but fail at execution. There is no automatic dependency enforcement — make sure any integration a skill depends on is also connected to the agent.
1

Conversation starts

Your agent loads up and sees a list of all attached skills, but only the names and descriptions (not the full instructions). This keeps things fast and lightweight.
2

You ask something

You send a message like “Draft an outreach email to the VP of Sales at Acme Corp.”
3

Agent finds the right skill

The agent scans the skill descriptions and finds email-outreach-playbook is relevant. It reads the full skill from the sandbox.
4

Agent follows the instructions

Now the agent has the complete playbook in context. It follows the step-by-step process: researches the prospect, personalizes the email using your template, and drafts it exactly the way you want.
5

Conversation ends

If the agent made any changes to skills during the conversation (more on that below), those changes are automatically saved.
Key insight: Skills are only loaded when needed. If you have 20 skills attached to an agent but the user asks a simple question, the agent doesn’t waste time or tokens loading irrelevant skills. This is fundamentally different from a system prompt, which is always loaded in full.

Built-in System Skills

Every Gumloop team comes with two built-in system skills that are automatically available to your agents:

skill-creator

Powers the Create With AI flow. When skill creation is enabled on an agent and you click Create With AI, the agent uses this skill to guide you through skill creation step by step — naming, scoping, writing instructions, and validating the result.

gumcp-client

Enables agents to call your connected integrations (Gmail, Salesforce, Slack, Google Sheets, etc.) directly from Python scripts in the sandbox. This is what makes it possible to build skills that combine custom logic with real tool calls — e.g., a script that reads from Sheets, processes the data, and posts a summary to Slack.
Both system skills are read-only — they are maintained by Gumloop and updated automatically. You cannot edit or delete them. The skill-creator skill is only active when skill creation is enabled on the agent (via the Skill Editing & Creation toggle in Tools).

Creating Skills

There are three ways to create a skill. Pick whichever feels most natural.
Naming Rules: Skill names are validated by the backend and must follow these constraints:
  • Lowercase letters, digits, and hyphens only
  • No spaces, underscores, or uppercase letters
  • Maximum 64 characters
  • Cannot start or end with a hyphen
  • No consecutive hyphens
my-cool-skill · ❌ My_Skill, my skill, mySkill
Skills page showing the three creation methods: Create With AI, Upload Files, and Write Skill Instructions
A simple form where you fill in three fields: Name, Description, and Instructions. Click Create and you’re done.
The Write Skill Instructions form showing name, description, and instructions fields
Best for: Simple skills that are just instructions (no scripts or extra files needed). Great for brand voice guidelines, email templates, response formatting rules, etc.
Upload a .md, .zip, or .skill file containing a properly formatted SKILL.md. If you’re uploading a .zip, it can include scripts, references, and assets alongside the SKILL.md.
Upload Skill File
Best for: Technical users with existing documentation, SOPs, or code they want to package as a skill.

What’s Inside a Skill?

At its core, a skill is a folder containing a SKILL.md file with instructions your agent can read. Some skills also include helper scripts, reference docs, and templates.
email-outreach-playbook/
  SKILL.md              ← Required: the instructions
  scripts/              ← Optional: executable code
    personalize_email.py
  references/           ← Optional: detailed docs
    email_templates.md
    prospect_research_checklist.md
  assets/               ← Optional: templates and files
    signature_template.html
Most skills only need the SKILL.md file. You can always add scripts and references later as the skill grows.

Why This Structure Exists

The directory structure isn’t just organizational — it reflects how the agent uses each part:
ComponentWhat it’s forHow the agent uses it
SKILL.mdInstructions, decision logic, contextLoaded directly into the agent’s context window. Keep it under 500 lines for token efficiency and focus.
references/Detailed documentation, lookup tables, API specsRead on demand when the agent needs specific details. Keeps SKILL.md lean.
scripts/Deterministic logic — calculations, data transforms, API callsExecuted in the sandbox and the output is used in the agent’s response. Never left to the agent to reason through.
assets/Static files used in output — templates, imagesReferenced by instructions or scripts when producing output.
Rule of thumb: If the agent needs to reason through something (decisions, steps, context), it belongs in SKILL.md instructions. If the agent needs to calculate or process something and the result must be correct every time, it belongs in a scripts/ file.The 500-line soft limit on SKILL.md is enforced as a validation warning — skills exceeding it still work, but you should move detailed content to references/ to keep the agent’s context focused.

The SKILL.md File

Every skill starts with a short header (called “frontmatter”) that tells the agent what the skill does and when to use it, followed by the actual instructions:
---
name: email-outreach-playbook
description: Draft personalized cold outreach emails for sales prospects.
  Use when the user asks to contact or email a prospect.
---

## Overview
This skill guides the outreach process for cold prospects.

## Step 1: Research the Prospect
- Look up the prospect's company and role
- Note recent news or achievements to personalize the email

## Step 2: Draft the Email
- Use the greeting: "Hey {first_name},"
- Reference something specific about their company
- Keep it under 150 words
...
The description is the most important part. Your agent uses it to decide whether to load the skill for the current task. Be specific about what the skill does and when to use it. A vague description means the agent might never find your skill.Description constraints: Maximum 1,024 characters. No angle brackets allowed.
Beyond name and description, you can add these optional fields to your frontmatter:
FieldWhat it doesExample
iconSets the skill’s icon in the UI. Uses Lucide icon names in kebab-case.icon: chart-line
colorSets the skill’s accent color in the UI.color: Blue
related_server_idsLinks the skill to specific integrations, enabling integration-scoped discovery. When set, agents working with that integration are more likely to find the skill.related_server_ids: [gsheets, slack]
Available colors: Grey, Blue, Green, Orange, Red, Yellow, Teal, Pink, Purple, Bronze, Black
---
name: weekly-sales-summary
description: Generate a weekly sales performance summary from Google Sheets data.
icon: chart-line
color: Green
related_server_ids: [gsheets, slack]
---
Server IDs must match the actual integration identifiers, not display names. For example, Google Sheets is gsheets, not google-sheets. The agent can discover correct IDs by running python3 /home/user/skills/gumcp-client/scripts/list_tools.py in the sandbox.

Attaching Skills to Agents

Once you’ve created a skill, attach it to the agents that should use it.
The Skills section in agent configuration showing the + Skill button
1

Open agent configuration

Go to your agent’s configuration page.
2

Find the Skills section

Scroll down to the Skills section.
3

Add a skill

Click + Skill and select a skill from the list (or create a new one right there).
That’s it. Your agent can now find and use that skill whenever it’s relevant.
Personal assistant agents (the general agent you chat with) automatically have access to all skills in your space. You don’t need to attach skills manually for those.General Agent vs. Custom Agent skill behavior: The general agent discovers skills from your full library dynamically using semantic search — it finds skills by matching your request against skill descriptions. Custom agents only see skills explicitly attached to them (listed in the system prompt). A practical consequence: when an agent creates a new skill during a conversation, on a custom agent it gets auto-attached; on the general agent it is added to your library but not auto-attached to anything.

Skills That Improve Over Time

This is the most powerful part of skills, and what makes them fundamentally different from static instructions. Your agent can edit, improve, and create skills on its own. This behavior is controlled by the Skill Editing & Creation toggle in your agent’s Tools configuration. It’s enabled by default.
Skill Editing & Creation toggle enabled in agent tools
  • Enabled (default): The agent can create new skills, update existing ones, and fix its own mistakes. This is the recommended option because it lets the agent iterate, learn from corrections, and continuously improve.
  • Disabled: The agent can still read and use skills you’ve already attached, but cannot create or modify skills. Choose this for tighter control over your skill library.
This toggle is global — it applies to all skills on the agent, not per-skill. There is no way to lock individual skills while keeping others editable. If you need certain skills to be immutable, disable the toggle entirely.
Keep this enabled to unlock the full compound learning effect described below. An agent that can refine its own playbooks gets better with every conversation.
You: “Draft an outreach email to the VP at Acme Corp.”
Agent: [drafts email using the outreach-playbook skill]
You: “Actually, we don’t use that greeting anymore. Use ‘Hey {first_name}’ instead.”
Agent: “Got it. I’ve updated the outreach playbook skill with the new greeting.”
Next time the agent drafts an outreach email, it uses the corrected greeting. The fix is permanent. It’s saved back to the skill.
No version history: Skills are overwritten in place with no rollback. If an agent edits a skill and breaks it, there is no undo. We recommend manually copying your skill instructions before enabling free agent editing on critical skills.
Concurrent edits: If two conversations edit the same skill simultaneously, the last one to complete wins and overwrites the other. Teams with multiple users on shared agents should be aware of this race condition.

The Compound Effect

Every correction, every new instruction, every “actually, do it this way” compounds over time:
TimelineWhat the skill looks like
Day 1A basic outreach skill with a simple template.
Week 1Includes templates for 3 scenarios and an updated greeting.
Month 1Has 10 templates, a research checklist, follow-up rules, and a scoring script.
Month 6Essentially a senior salesperson’s playbook.
This happens naturally through normal usage. You just tell the agent what to do differently, and it updates its own playbook.
Think of skills as a living knowledge base. Every interaction is a chance for the agent to learn and get better. System prompts are static. Tools are static. Skills are alive.

FAQs

Skills can feel like memory because your agent can update a skill after you correct it.Technically, skills are not conversation memory. Skills are saved playbooks your agent can reuse later, and the agent still needs to load the skill again in future conversations when it is relevant.
Skills are loaded on demand. Your agent sees skill names and descriptions first, then decides what to load based on relevance.Common fixes:
  • Make the skill description more specific about what it does and when to use it.
  • Make sure the skill is attached to the right agent. (Personal assistant agents can access all skills in your space. Custom agents only see attached skills.)
A few edge cases can prevent changes from being saved:
  • Invalid SKILL.md frontmatter: If SKILL.md is missing required fields like name or description, or the YAML is malformed, the skill update is skipped and the previous version stays intact.
  • Rename mismatch: If the skill folder name and the name: field do not match, saving is skipped.
  • Concurrent edits: If two conversations edit the same skill at the same time, the last conversation to finish wins.
  • Conversation ended abnormally: Skill edits are saved at the end of a completed agent turn. If the conversation crashes, is interrupted, or ends before the agent’s turn finishes, any skill changes made during that session may not have been saved. If you suspect this happened, check the skill and re-apply any corrections in a new conversation.
Also note, skills do not have built-in version control right now. When a skill is updated, it is overwritten in place.

What Kinds of Skills Should You Build?

Workflow Skills

Multi-step business processes. Sales outreach sequences, onboarding checklists, content publishing workflows.

Knowledge Skills

Domain expertise. Product features, pricing tiers, competitive positioning, company policies.

Template Skills

Consistent formatting. Email templates, report formats, Slack update structures, CRM field mapping.

Automation Skills

Deterministic code the agent runs in the sandbox. Data transformations, metric calculations, invoice validation.

Calling Integrations From Scripts

Your skill scripts can do more than local calculations — they can call your connected integrations (Google Sheets, Gmail, Slack, Salesforce, etc.) directly from Python using the built-in gumcp-client system skill. In plain terms: you can write a Python script that reads data from one service, processes it, and writes the result to another — all in one go, without the agent needing to figure out each step.
How it works under the hood: The gumcp-client skill provides a Python Client class that’s pre-installed in every agent sandbox. Your script imports it, creates a client with credentials that are already set up as environment variables, and calls tools using the server__tool_name format (e.g. gsheets__read_spreadsheet, slack__send_message). The agent just runs the script and uses the printed output.
GuMCP client tool call screenshot
Say you want a skill that pulls sales data from a Google Sheet, computes totals, and gives the agent a clean summary to post. Here’s how it works:SKILL.md tells the agent when and how:
---
name: weekly-sales-summary
description: Generate a weekly sales summary from the team spreadsheet.
  Use when the user asks for sales numbers, weekly summary, or
  team performance update.
related_server_ids: [gsheets, slack]
---

## Steps
1. Run: python3 scripts/generate_summary.py
2. Review the printed output
3. Post the summary to the #sales Slack channel (or present to the user)
scripts/generate_summary.py does the heavy lifting:
import json, os
from gumcp_client import Client

def get_client():
    return Client(
        user_id=os.getenv("GUMCP_USER_ID"),
        gumcp_api_key=os.getenv("GUMCP_API_KEY"),
        base_url=os.getenv("GUMCP_BASE_URL"),
    )

with get_client() as client:
    # Read the raw data from your team spreadsheet
    raw = client.call_tool(
        "gsheets__read_spreadsheet",
        dict(spreadsheet_id="1ABC...", range="Sales!A1:F100")
    )
    data = json.loads(raw[0])
    rows = data.get("values", [])

    # Process with Python — exact math, no guessing
    total_revenue = sum(float(r[3]) for r in rows[1:])
    top_rep = max(rows[1:], key=lambda r: float(r[3]))

    print("Total revenue: $" + format(total_revenue, ",.2f"))
    print("Top performer: " + top_rep[0] + " ($" + format(float(top_rep[3]), ",.2f") + ")")
The agent runs this script in its sandbox, gets the printed output, and uses it in its response. If you want it posted to Slack, the agent can do that as a separate step (or you could add the Slack post directly to the script).Why this is useful: The spreadsheet might have hundreds of rows. If the agent called the Google Sheets tool directly, all that raw data would land in the agent’s context window, costing tokens and potentially getting truncated. With a script, the data stays in the sandbox — only the summary comes back.
A skill that reads meeting notes from Google Docs and pulls out the to-do items:scripts/extract_action_items.py:
import json, os
from gumcp_client import Client

def get_client():
    return Client(
        user_id=os.getenv("GUMCP_USER_ID"),
        gumcp_api_key=os.getenv("GUMCP_API_KEY"),
        base_url=os.getenv("GUMCP_BASE_URL"),
    )

with get_client() as client:
    raw = client.call_tool(
        "gdocs__read_document",
        dict(document_id="1XYZ...")
    )
    content = json.loads(raw[0])

    # Parse the document text with Python
    lines = content.get("text", "").split("\n")
    action_items = [l for l in lines if l.strip().startswith("- [ ]")]

    for item in action_items:
        print(item)
The agent reads the printed output and can then create tasks in your project management tool, send reminders via Slack, or just present them to you.
Server IDs aren’t always obvious. Google Sheets is gsheets, Google Docs is gdocs, Google Calendar is gcalendar, Google BigQuery is gbigquery. The agent can run python3 /home/user/skills/gumcp-client/scripts/list_tools.py in its sandbox to discover the exact IDs and available tools for your connected integrations.

When to use scripts vs. direct tool calls

Your agent can already call integrations directly — “read this spreadsheet” or “send this Slack message” work fine as regular tool calls. You don’t need scripts for most integration tasks. Both approaches have strengths:
Direct tool callsScripts in the sandbox
Best forSimple, one-off actionsMulti-step processing, large data, exact calculations
Example”Send this email”, “Post to Slack""Read 500 rows from Sheets, compute totals, format a report”
Agent seesThe full tool response — can reason about it, ask follow-upsOnly the printed output — data stays in the sandbox
RepeatabilityAgent decides approach each timeScript runs identically every time, saved in the skill
Token costFull response goes into context windowData processed in sandbox, only summary enters context
FlexibilityAgent can adapt based on what it gets backLogic is fixed in code — great for precision, less adaptive
Start with direct tool calls. They’re simpler, and the agent can reason about the results conversationally. Move logic into a script when you hit one of these cases:
  • The tool response is very large and you only need a subset (avoids flooding the agent’s context)
  • You need to chain multiple calls together (read → filter → compute → write) without round-tripping
  • The calculation must be exact every time (Python math vs. the agent estimating)
  • The same process should run identically across conversations — save it once, reuse everywhere
Most skills don’t need scripts or integration calls. The majority of useful skills are just well-written instructions and templates. Integration scripts are a power feature for when you need them, not a starting point.
Workflow Skill: Sales outreach sequence
  • Step 1: Research the prospect
  • Step 2: Personalize the email using a template
  • Step 3: Log the activity in Salesforce
  • Step 4: Set a follow-up reminder for 3 days later
Knowledge Skill: Product knowledge base
  • Product features and pricing tiers
  • Common customer questions and answers
  • Competitive positioning
Template Skill: Email templates by scenario
  • Cold outreach template
  • Follow-up template
  • Meeting request template
  • Thank you template
Automation Skill: Weekly analytics report
  • SKILL.md: Report structure and formatting rules
  • scripts/calculate_metrics.py: Pulls data and computes KPIs
  • assets/report_template.md: The markdown template
Integration-Specific Skill: Salesforce deal management
  • When to create vs update opportunities
  • Required fields for each stage
  • Naming conventions for deals
  • When to notify the team

Skill Examples (Inspiration)

If you want to see real skill folders, complete with SKILL.md files and supporting resources, browse these public examples:
If you have used Claude Skills before, the packaging concept is very similar: a folder with a Skill.md file and optional resources. Gumloop uses SKILL.md and adds agent-specific features like attaching skills to agents and letting agents improve skills over time. For reference, see How to create custom Skills.

Best Practices

The description is how your agent decides whether to load a skill. Be specific about what it does and when to use it.Good: “Generate weekly sales performance reports from BigQuery data, formatted as Markdown tables with week-over-week comparisons. Use when the user asks for sales reports or weekly metrics.”Bad: “Helps with reports.”A vague description means the agent might never find your skill.
One skill should do one thing well. Don’t create a mega-skill called “everything” with 3,000 lines of instructions.Instead of one “sales-operations” skill, create:
  • outreach-playbook (email sequences)
  • crm-logging (Salesforce field mapping)
  • deal-qualification (scoring criteria)
Focused skills are easier to maintain, share, and compose.
Show the agent what good output looks like. Include sample inputs and expected outputs in your SKILL.md.
## Example
Input: "Draft an email to John at Acme Corp"
Expected output:
- Subject: Quick question about [specific thing]
- Greeting: Hey John,
- Body: 2-3 sentences, personalized
- CTA: One clear ask
Agents learn better from examples than abstract descriptions.
If the skill involves math, data formatting, or any logic that needs to be 100% correct every time, put it in a Python script in the scripts/ directory. Don’t rely on the agent to reason through calculations.The pattern works like this:
  1. SKILL.md describes when and why to run the script (e.g., “After collecting the sales data, run the commission calculator to compute payouts”)
  2. The script handles the how — deterministic logic that produces the same correct result every time
  3. The agent executes the script in its sandbox, reads the output, and uses it in the response
This separation means the agent handles context and judgment (which deals to include, how to present results) while the script handles precision (the actual math).Example: Sales commission calculatorSKILL.md instructions:
## Computing Commissions
When the user asks for commission calculations:
1. Collect the deal data (rep name, deal value, deal stage)
2. Run: python3 scripts/calculate_commission.py --input deals.json
3. Present the results in a table, highlighting any reps above quota
scripts/calculate_commission.py handles the actual math:
# Tiered commission rates, quota thresholds, accelerators
# — all encoded in code, not left to the agent
Other good candidates for scripts: tax calculations, metric aggregations, data transformations, invoice validation, and any formula-driven logic.
You don’t need to write the perfect skill on day one. Create a basic version with core instructions, then let the agent refine it through usage.Create a simple skill via “Write Skill Instructions” → use it a few times → give feedback → the agent updates the skill → repeat.
If your system prompt says “Always be professional” and a skill says “Use casual language,” the agent gets confused.System prompt = who the agent is (always active).Skills = how to do specific tasks (loaded on demand).Keep them separate and non-contradictory.
Skills exceeding 500 lines trigger a validation warning and consume significant tokens when loaded. Move detailed content to the references/ directory instead — the agent can selectively read reference files as needed rather than loading everything at once.
All attached skills are listed in the agent’s system prompt (roughly 50–100 tokens per skill). Attaching a very large number of skills to a single custom agent adds meaningful token overhead on every request. Keep attached skills focused and relevant; use the general agent if you need access to your full skill library.
  • Don’t create catch-all mega-skills with thousands of lines — break them into focused, single-purpose skills.
  • Don’t duplicate system prompt content in a skill — if it applies to every interaction, it belongs in the system prompt.
  • Don’t create skills that just restate tool documentation — skills should add your business logic and process, not explain how Gmail works.
  • Don’t put time-sensitive information in skills without labeling it — “Q4 promotion ends Dec 31” will be wrong in January.

Managing Skills

You can view, search, and manage all your skills from the Skills page in the sidebar. Each skill shows its name, description, connected apps, last edit time, and creator.
The Skills page showing skill search, creation, and management
Skills can be shared with your team:
  • Restricted (default for personal skills): Only you can see it
  • Team: All team members can see and use it
  • Organization: All org members can access it
  • Anyone: Public access (view only)
Click the three-dot menu on any skill → Share to manage access.
You can download a skill’s files directly from the Skills page. Click the three-dot menu on any skill and select Download.
Three-dot menu on a skill showing the Download option
From the three-dot menu on any skill, you can rename or delete it. Deleted skills are soft-deleted (marked inactive rather than permanently removed), so they can potentially be recovered by Gumloop support if needed.

Next Steps