Agent skills

Agent Skills are reusable packages of instructions that give your AI agents specialized capabilities. Based on the open Agent Skills 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. Click a skill to open its detail page, where you edit, share, and delete it.

Click + Add to Sim to open the skill create page, which takes three fields:

Importing skills

Bring in an existing skill in the open SKILL.md format two ways:

• Import — the Import action on the create page takes a .md file with YAML frontmatter, or a .zip containing a SKILL.md.
• Paste content — paste the SKILL.md straight into Content. 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:

# 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.

Skill Editors

Everyone in the workspace sees and uses every skill — including members who join later. Nobody needs to be added to a skill to use it.

Each skill has an explicit editors list. Editors can edit the skill, delete it, and manage the editors list. Workspace admins can always do this too — they are editors of every skill automatically and cannot be removed from the list. Whoever creates a skill becomes an editor.

Open a skill from the Skills tab to manage it. The detail page has the editable fields, a Share action for adding editors from your workspace members, and the Skill Editors list at the bottom.

Using Skills in Chat

Skills work in Chat too. Type / in the message box to open the skills menu, then pick a skill — or keep typing to filter by name. The skill appears in your message as a tag, e.g. /format-markdown.

Tagging a skill loads its full instructions into the conversation, so Sim follows them for that request — no waiting for Sim to decide the skill is relevant on its own.

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.

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 — The open format for portable agent skills
• Example skills — Browse community skill examples
• Best practices — Writing effective skills