---
title: Agent skills
description: Reusable instruction packages your agents load on demand, managed from the Skills tab.
pageType: guide
---

import { Callout } from 'fumadocs-ui/components/callout'

Agent Skills are reusable packages of instructions that give your AI agents specialized capabilities. Based on the open [Agent Skills](https://agentskills.io) format, skills let you capture domain expertise, workflows, and best practices that agents can load on demand.

## How Skills Work

Skills use **progressive disclosure** to keep agent context lean:

1. **Discovery** — Only skill names and descriptions are included in the agent's system prompt (~50-100 tokens each)
2. **Activation** — When the agent decides a skill is relevant, it calls the `load_skill` tool to load the full instructions into context
3. **Execution** — The agent follows the loaded instructions to complete the task

## Creating Skills

Skills live on the **Integrations** page: click **Integrations** in the workspace sidebar, then switch to the **Skills** tab. It lists every skill in the workspace, searchable by name.

![The Skills tab on the Integrations page](/static/skills/skills-tab.png)

Click **+ Add to Sim** to open the **Add Skill** dialog. The **Create** tab takes three fields:

![The Add Skill dialog, Create tab](/static/skills/add-skill-create.png)

| Field | Description |
|-------|-------------|
| **Name** | A kebab-case identifier (e.g. `sql-expert`, `code-reviewer`). Max 64 characters. |
| **Description** | A short explanation of what the skill does and when to use it. This is what the agent reads to decide whether to activate the skill. Max 1024 characters. |
| **Content** | The full skill instructions in markdown. This is loaded when the agent activates the skill. |

<Callout type="info">
  The description is critical — it's the only thing the agent sees before deciding to load a skill. Be specific about when and why the skill should be used.
</Callout>

### Importing skills

The **Import** tab brings in an existing skill in the open [SKILL.md](https://agentskills.io/specification) format, three ways:

![The Add Skill dialog, Import tab](/static/skills/add-skill-import.png)

- **Upload a file** — a `.md` file with YAML frontmatter, or a `.zip` containing a `SKILL.md`.
- **Import from GitHub** — paste a GitHub URL to a `SKILL.md` and click **Fetch**.
- **Paste content** — paste the `SKILL.md` directly. The frontmatter carries the `name` and `description`; the markdown body is the content.

Integration pages suggest **curated skills** for their service — open one (HubSpot, for example) and add a suggested skill with one click.

### Writing Good Skill Content

Skill content follows the same conventions as [SKILL.md files](https://agentskills.io/specification):

```markdown
# SQL Expert

## When to use this skill
Use when the user asks you to write, optimize, or debug SQL queries.

## Instructions
1. Always ask which database engine (PostgreSQL, MySQL, SQLite)
2. Use CTEs over subqueries for readability
3. Add index recommendations when relevant
4. Explain query plans for optimization requests

## Common Patterns
...
```

**Recommended structure:**
- **When to use** — Specific triggers and scenarios
- **Instructions** — Step-by-step guidance with numbered lists
- **Examples** — Input/output samples showing expected behavior
- **Common Patterns** — Reusable approaches for frequent tasks
- **Edge Cases** — Gotchas and special considerations

Keep skills focused and under 500 lines. If a skill grows too large, split it into multiple specialized skills.

## Adding Skills to an Agent

Open any **Agent** block and find the **Skills** dropdown below the tools section. Select the skills you want the agent to have access to.

![Add Skill](/static/skills/add-skill.png)

Selected skills appear as cards that you can click to edit or remove.

### What Happens at Runtime

When the workflow runs:

1. The agent's system prompt includes an `<available_skills>` section listing each skill's name and description
2. A `load_skill` tool is automatically added to the agent's available tools
3. When the agent determines a skill is relevant to the current task, it calls `load_skill` with the skill name
4. The full skill content is returned as a tool response, giving the agent detailed instructions

This works across all supported LLM providers — the `load_skill` tool uses standard tool-calling, so no provider-specific configuration is needed.

## Common Use Cases

Skills are most valuable when agents need specialized knowledge or multi-step workflows:

**Domain Expertise**
- `api-integration-expert` — Best practices for calling specific APIs (authentication, rate limiting, error handling)
- `data-transformation` — ETL patterns, data cleaning, and validation rules
- `code-reviewer` — Code review guidelines specific to your team's standards

**Workflow Templates**
- `bug-investigation` — Step-by-step debugging methodology (reproduce → isolate → test → fix)
- `feature-implementation` — Development workflow from requirements to deployment
- `document-generator` — Templates and formatting rules for technical documentation

**Company-Specific Knowledge**
- `our-architecture` — System architecture diagrams, service dependencies, and deployment processes
- `style-guide` — Brand guidelines, writing tone, UI/UX patterns
- `customer-onboarding` — Standard procedures and common customer questions

**When to use skills vs. agent instructions:**
- Use **skills** for knowledge that applies across multiple workflows or changes frequently
- Use **agent instructions** for task-specific context that's unique to a single agent

## Best Practices

**Writing Effective Descriptions**
- **Be specific and keyword-rich** — Instead of "Helps with SQL", write "Write optimized SQL queries for PostgreSQL, MySQL, and SQLite, including index recommendations and query plan analysis"
- **Include activation triggers** — Mention specific words or phrases that should prompt the skill (e.g., "Use when the user mentions PDFs, forms, or document extraction")
- **Keep it under 200 words** — Agents scan descriptions quickly; make every word count

**Skill Scope and Organization**
- **One skill per domain** — A focused `sql-expert` skill works better than a broad `database-everything` skill
- **Limit to 5-10 skills per agent** — More skills = more decision overhead; start small and add as needed
- **Split large skills** — If a skill exceeds 500 lines, break it into focused sub-skills

**Content Structure**
- **Use markdown formatting** — Headers, lists, and code blocks help agents parse and follow instructions
- **Provide examples** — Show input/output pairs so agents understand expected behavior
- **Be explicit about edge cases** — Don't assume agents will infer special handling

**Testing and Iteration**
- **Test activation** — Run your workflow and verify the agent loads the skill when expected
- **Check for false positives** — Make sure skills aren't activating when they shouldn't
- **Refine descriptions** — If a skill isn't loading when needed, add more keywords to the description

## Learn More

- [Agent Skills specification](https://agentskills.io) — The open format for portable agent skills
- [Example skills](https://github.com/anthropics/skills) — Browse community skill examples
- [Best practices](https://agentskills.io/what-are-skills) — Writing effective skills

import { FAQ } from '@/components/ui/faq'

<FAQ items={[
  { question: "How many skills can I attach to a single agent?", answer: "You can attach as many skills as you want, but the recommended limit is 5-10 per agent. More skills mean more decision overhead for the agent when scanning descriptions. Since only the names and descriptions are included in the system prompt (about 50-100 tokens each), many skills will not dramatically increase context usage, but they can slow down the agent's decision-making." },
  { question: "How does the agent decide when to load a skill?", answer: "The agent sees an available_skills section in its system prompt listing each skill's name and description. When the agent determines that a skill is relevant to the current task, it calls the load_skill tool with the skill name. The full skill content is then returned as a tool response. This is why writing a specific, keyword-rich description is critical -- it is the only thing the agent reads before deciding whether to activate a skill." },
  { question: "Do skills work with all LLM providers?", answer: "Yes. The load_skill mechanism uses standard tool-calling, which is supported by all LLM providers in Sim. No provider-specific configuration is needed. The skill system works the same way whether you are using Anthropic, OpenAI, Google, or any other supported provider." },
  { question: "When should I use skills vs. agent instructions?", answer: "Use skills for knowledge that applies across multiple workflows or changes frequently. Skills are reusable packages that can be attached to any agent. Use agent instructions for task-specific context that is unique to a single agent and workflow. If you find yourself copying the same instructions into multiple agents, that content should be a skill instead." },
  { question: "Can permission groups disable skills for certain users?", answer: "Yes. On Enterprise-entitled workspaces, any workspace admin can create a permission group with the disableSkills option enabled. When a user is assigned to such a group in a workspace, the skills dropdown in agent blocks is disabled and they cannot add or use skills in workflows belonging to that workspace." },
  { question: "What is the recommended maximum length for skill content?", answer: "Keep skills focused and under 500 lines. If a skill grows too large, split it into multiple specialized skills. Shorter, focused skills are more effective because the agent can load exactly what it needs. A broad skill with too much content can overwhelm the agent and reduce the quality of its responses." },
  { question: "Where do I create and manage skills?", answer: "Click Integrations in the workspace sidebar and switch to the Skills tab. Add Skill creates one from a name (kebab-case, max 64 characters), description (max 1024 characters), and markdown content — or imports an existing SKILL.md from a file, a GitHub URL, or pasted content. Existing skills are edited and deleted from the same tab." },
]} />
