|
| 1 | +--- |
| 2 | +title: Agent Skills |
| 3 | +--- |
| 4 | + |
| 5 | +import { Callout } from 'fumadocs-ui/components/callout' |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +## How Skills Work |
| 10 | + |
| 11 | +Skills use **progressive disclosure** to keep agent context lean: |
| 12 | + |
| 13 | +1. **Discovery** — Only skill names and descriptions are included in the agent's system prompt (~50-100 tokens each) |
| 14 | +2. **Activation** — When the agent decides a skill is relevant, it calls the `load_skill` tool to load the full instructions into context |
| 15 | +3. **Execution** — The agent follows the loaded instructions to complete the task |
| 16 | + |
| 17 | +This means you can attach many skills to an agent without bloating its context window. The agent only loads what it needs. |
| 18 | + |
| 19 | +## Creating Skills |
| 20 | + |
| 21 | +Go to **Settings** and select **Skills** under the Tools section. |
| 22 | + |
| 23 | + |
| 24 | + |
| 25 | +Click **Add** to create a new skill with three fields: |
| 26 | + |
| 27 | +| Field | Description | |
| 28 | +|-------|-------------| |
| 29 | +| **Name** | A kebab-case identifier (e.g. `sql-expert`, `code-reviewer`). Max 64 characters. | |
| 30 | +| **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. | |
| 31 | +| **Content** | The full skill instructions in markdown. This is loaded when the agent activates the skill. | |
| 32 | + |
| 33 | +<Callout type="info"> |
| 34 | + 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. |
| 35 | +</Callout> |
| 36 | + |
| 37 | +### Writing Good Skill Content |
| 38 | + |
| 39 | +Skill content follows the same conventions as [SKILL.md files](https://agentskills.io/specification): |
| 40 | + |
| 41 | +```markdown |
| 42 | +# SQL Expert |
| 43 | + |
| 44 | +## When to use this skill |
| 45 | +Use when the user asks you to write, optimize, or debug SQL queries. |
| 46 | + |
| 47 | +## Instructions |
| 48 | +1. Always ask which database engine (PostgreSQL, MySQL, SQLite) |
| 49 | +2. Use CTEs over subqueries for readability |
| 50 | +3. Add index recommendations when relevant |
| 51 | +4. Explain query plans for optimization requests |
| 52 | + |
| 53 | +## Common Patterns |
| 54 | +... |
| 55 | +``` |
| 56 | + |
| 57 | +**Recommended structure:** |
| 58 | +- **When to use** — Specific triggers and scenarios |
| 59 | +- **Instructions** — Step-by-step guidance with numbered lists |
| 60 | +- **Examples** — Input/output samples showing expected behavior |
| 61 | +- **Common Patterns** — Reusable approaches for frequent tasks |
| 62 | +- **Edge Cases** — Gotchas and special considerations |
| 63 | + |
| 64 | +Keep skills focused and under 500 lines. If a skill grows too large, split it into multiple specialized skills. |
| 65 | + |
| 66 | +## Adding Skills to an Agent |
| 67 | + |
| 68 | +Open any **Agent** block and find the **Skills** dropdown below the tools section. Select the skills you want the agent to have access to. |
| 69 | + |
| 70 | + |
| 71 | + |
| 72 | +Selected skills appear as cards that you can click to edit or remove. |
| 73 | + |
| 74 | +### What Happens at Runtime |
| 75 | + |
| 76 | +When the workflow runs: |
| 77 | + |
| 78 | +1. The agent's system prompt includes an `<available_skills>` section listing each skill's name and description |
| 79 | +2. A `load_skill` tool is automatically added to the agent's available tools |
| 80 | +3. When the agent determines a skill is relevant to the current task, it calls `load_skill` with the skill name |
| 81 | +4. The full skill content is returned as a tool response, giving the agent detailed instructions |
| 82 | + |
| 83 | +This works across all supported LLM providers — the `load_skill` tool uses standard tool-calling, so no provider-specific configuration is needed. |
| 84 | + |
| 85 | +## Common Use Cases |
| 86 | + |
| 87 | +Skills are most valuable when agents need specialized knowledge or multi-step workflows: |
| 88 | + |
| 89 | +**Domain Expertise** |
| 90 | +- `api-integration-expert` — Best practices for calling specific APIs (authentication, rate limiting, error handling) |
| 91 | +- `data-transformation` — ETL patterns, data cleaning, and validation rules |
| 92 | +- `code-reviewer` — Code review guidelines specific to your team's standards |
| 93 | + |
| 94 | +**Workflow Templates** |
| 95 | +- `bug-investigation` — Step-by-step debugging methodology (reproduce → isolate → test → fix) |
| 96 | +- `feature-implementation` — Development workflow from requirements to deployment |
| 97 | +- `document-generator` — Templates and formatting rules for technical documentation |
| 98 | + |
| 99 | +**Company-Specific Knowledge** |
| 100 | +- `our-architecture` — System architecture diagrams, service dependencies, and deployment processes |
| 101 | +- `style-guide` — Brand guidelines, writing tone, UI/UX patterns |
| 102 | +- `customer-onboarding` — Standard procedures and common customer questions |
| 103 | + |
| 104 | +**When to use skills vs. agent instructions:** |
| 105 | +- Use **skills** for knowledge that applies across multiple workflows or changes frequently |
| 106 | +- Use **agent instructions** for task-specific context that's unique to a single agent |
| 107 | + |
| 108 | +## Best Practices |
| 109 | + |
| 110 | +**Writing Effective Descriptions** |
| 111 | +- **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" |
| 112 | +- **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") |
| 113 | +- **Keep it under 200 words** — Agents scan descriptions quickly; make every word count |
| 114 | + |
| 115 | +**Skill Scope and Organization** |
| 116 | +- **One skill per domain** — A focused `sql-expert` skill works better than a broad `database-everything` skill |
| 117 | +- **Limit to 5-10 skills per agent** — More skills = more decision overhead; start small and add as needed |
| 118 | +- **Split large skills** — If a skill exceeds 500 lines, break it into focused sub-skills |
| 119 | + |
| 120 | +**Content Structure** |
| 121 | +- **Use markdown formatting** — Headers, lists, and code blocks help agents parse and follow instructions |
| 122 | +- **Provide examples** — Show input/output pairs so agents understand expected behavior |
| 123 | +- **Be explicit about edge cases** — Don't assume agents will infer special handling |
| 124 | + |
| 125 | +**Testing and Iteration** |
| 126 | +- **Test activation** — Run your workflow and verify the agent loads the skill when expected |
| 127 | +- **Check for false positives** — Make sure skills aren't activating when they shouldn't |
| 128 | +- **Refine descriptions** — If a skill isn't loading when needed, add more keywords to the description |
| 129 | + |
| 130 | +## Learn More |
| 131 | + |
| 132 | +- [Agent Skills specification](https://agentskills.io) — The open format for portable agent skills |
| 133 | +- [Example skills](https://github.com/anthropics/skills) — Browse community skill examples |
| 134 | +- [Best practices](https://agentskills.io/what-are-skills) — Writing effective skills |
0 commit comments