mirror of
https://github.com/simstudioai/sim.git
synced 2026-02-12 07:24:55 -05:00
474b1af145
* improvement(ui): improved skills UI, validation, and permissions * stronger typing for Skill interface * added missing docs description * ack comment
135 lines
6.4 KiB
Plaintext
135 lines
6.4 KiB
Plaintext
---
|
|
title: Agent Skills
|
|
---
|
|
|
|
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
|
|
|
|
This means you can attach many skills to an agent without bloating its context window. The agent only loads what it needs.
|
|
|
|
## Creating Skills
|
|
|
|
Go to **Settings** and select **Skills** under the Tools section.
|
|
|
|
|
|
|
|
Click **Add** to create a new skill with three fields:
|
|
|
|
| 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>
|
|
|
|
### 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.
|
|
|
|
|
|
|
|
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
|