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.
See a 15-second example
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’.”
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 simplest way to understand skills is to imagine you just hired someone new.
What you give them
Agent equivalent
What it does
Job description & company handbook
System prompt
Defines who they are, their tone, and universal rules. Always active.
Software logins (Gmail, Salesforce, Slack)
Tools
Gives them the raw ability to take actions.
Training materials & SOPs
Skills
Teaches 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.”
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.
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).
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
Create With AI (Recommended)
The easiest way to get started. Click Create Skill → Create With AI, and a chat opens where the AI walks you through skill creation step by step.You describe what you want the skill to do, and the AI:
Helps you nail down the scope and name
Writes the instructions based on your description
Adds any necessary scripts or reference files
Validates everything to make sure it’s properly formatted
Best for: Anyone who isn’t sure where to start, or wants a quick way to turn ideas into skills.
Write Skill Instructions
A simple form where you fill in three fields: Name, Description, and Instructions. Click Create and you’re done.
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 Files
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.
Best for: Technical users with existing documentation, SOPs, or code they want to package as 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.
The directory structure isn’t just organizational — it reflects how the agent uses each part:
Component
What it’s for
How the agent uses it
SKILL.md
Instructions, decision logic, context
Loaded directly into the agent’s context window. Keep it under 500 lines for token efficiency and focus.
references/
Detailed documentation, lookup tables, API specs
Read on demand when the agent needs specific details. Keeps SKILL.md lean.
scripts/
Deterministic logic — calculations, data transforms, API calls
Executed 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, images
Referenced 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.
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:
Copy
Ask AI
---name: email-outreach-playbookdescription: Draft personalized cold outreach emails for sales prospects. Use when the user asks to contact or email a prospect.---## OverviewThis 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.
Optional frontmatter fields
Beyond name and description, you can add these optional fields to your frontmatter:
Field
What it does
Example
icon
Sets the skill’s icon in the UI. Uses Lucide icon names in kebab-case.
icon: chart-line
color
Sets the skill’s accent color in the UI.
color: Blue
related_server_ids
Links 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
Copy
Ask AI
---name: weekly-sales-summarydescription: Generate a weekly sales performance summary from Google Sheets data.icon: chart-linecolor: Greenrelated_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.
Once you’ve created a skill, attach it to the agents that should use it.
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.
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.
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.
Fixing a template
Learning from experience
Creating a skill from scratch
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.
Conversation 1: You ask the agent to summarize your emails. It does a basic job. You: “Group them by sender.” Agent:[creates an email-summary skill with the grouping rule]
Conversation 2: You ask the agent to summarize your emails. It groups by sender automatically. You: “Also flag anything from my boss as urgent.” Agent:[updates the skill to add the urgent-flagging rule]
Conversation 3: You ask the agent to summarize your emails. It groups by sender AND flags your boss’s emails. No corrections needed.
You: “Every Monday I need you to pull last week’s support tickets from Zendesk, categorize them, and post a summary to #support-updates in Slack.” Agent: “I’ll create a skill to remember this workflow.” [Creates a weekly-support-summary skill with the full process, automatically attached to this agent]
The agent now remembers this process for every future Monday.
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.
Every correction, every new instruction, every “actually, do it this way” compounds over time:
Timeline
What the skill looks like
Day 1
A basic outreach skill with a simple template.
Week 1
Includes templates for 3 scenarios and an updated greeting.
Month 1
Has 10 templates, a research checklist, follow-up rules, and a scoring script.
Month 6
Essentially 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.
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.
Why did my agent not use a skill I created?
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.)
Why did my skill update not save after I corrected the agent?
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.
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.
Example: Summarize a Google Sheet and post to Slack
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:
Copy
Ask AI
---name: weekly-sales-summarydescription: 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]---## Steps1. Run: python3 scripts/generate_summary.py2. Review the printed output3. Post the summary to the #sales Slack channel (or present to the user)
scripts/generate_summary.py does the heavy lifting:
Copy
Ask AI
import json, osfrom gumcp_client import Clientdef 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.
Example: Read a Google Doc and extract action items
A skill that reads meeting notes from Google Docs and pulls out the to-do items:scripts/extract_action_items.py:
Copy
Ask AI
import json, osfrom gumcp_client import Clientdef 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.
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 calls
Scripts in the sandbox
Best for
Simple, one-off actions
Multi-step processing, large data, exact calculations
Example
”Send this email”, “Post to Slack"
"Read 500 rows from Sheets, compute totals, format a report”
Agent sees
The full tool response — can reason about it, ask follow-ups
Only the printed output — data stays in the sandbox
Repeatability
Agent decides approach each time
Script runs identically every time, saved in the skill
Token cost
Full response goes into context window
Data processed in sandbox, only summary enters context
Flexibility
Agent can adapt based on what it gets back
Logic 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.
See detailed examples for each skill type
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
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.
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.
Keep skills focused
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.
Include examples in your instructions
Show the agent what good output looks like. Include sample inputs and expected outputs in your SKILL.md.
Copy
Ask AI
## ExampleInput: "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.
Use scripts for things that must be exact
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:
SKILL.md describes when and why to run the script (e.g., “After collecting the sales data, run the commission calculator to compute payouts”)
The script handles the how — deterministic logic that produces the same correct result every time
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:
Copy
Ask AI
## Computing CommissionsWhen 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.json3. Present the results in a table, highlighting any reps above quota
scripts/calculate_commission.py handles the actual math:
Copy
Ask AI
# 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.
Start simple, let the agent improve it
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.
Don't duplicate the system prompt
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.
Keep SKILL.md under 500 lines
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.
Be mindful of skill scale
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.
Avoid these common mistakes
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.
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.
Sharing skills
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.
Downloading skill files
You can download a skill’s files directly from the Skills page. Click the three-dot menu on any skill and select Download.
Renaming and deleting
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.