Why Skills?
Agents are increasingly capable, but often lack the context needed to do real work reliably. Skills solve this by giving agents access to:- Domain expertise: Specialized knowledge packaged into reusable instructions
- New capabilities: Extended functionality like creating presentations, building MCP servers, or analyzing datasets
- Repeatable workflows: Consistent, auditable multi-step task execution
- Organizational knowledge: Team and company-specific context in portable, version-controlled packages
How Skills Work in Zencoder
Zencoder automatically discovers and loads skills from these locations:| Location | Scope |
|---|---|
<workspace>/.agents/skills/ | Project-specific skills |
<user-home>/.agents/skills/ | User-level skills |
<workspace>/.claude/skills/ | Claude-compatible skills |
Skills are automatically selected by the agent based on task context. Manual skill selection is not currently supported.
Skill Structure
A skill is a folder containing aSKILL.md file with metadata and instructions:
Creating a Skill
Create aSKILL.md file in your skills folder:
SKILL.md Frontmatter Reference
| Field | Required | Description |
|---|---|---|
name | Yes | Human-readable name for the skill |
description | Yes | What the skill does — the agent uses this to decide when to load it |
paths | No | Glob patterns to scope the skill to specific files (e.g., src/api/**) |
license | No | License identifier (e.g., MIT) |
disable-model-invocation | No | Set to true to prevent the agent from auto-selecting this skill |
Example Skills
PR Review Checklist
PR Review Checklist
A skill that enforces your team’s review standards on every code review request.
Database Migration Generator
Database Migration Generator
A skill that generates migration files following your ORM’s conventions.
API Endpoint Builder
API Endpoint Builder
A skill that creates REST endpoints following your team’s patterns.
Skills vs AI Agents
| Skills | AI Agents | |
|---|---|---|
| What it is | Instruction package the agent loads on demand | A named agent with specific tools and instructions |
| When it activates | Agent decides based on task match | User selects it explicitly |
| Best for | Procedural workflows, domain expertise | Recurring interactive tasks |
| Stored in | .agents/skills/ | Zencoder UI (shareable) |
Tips for Effective Skills
Write descriptions as trigger conditions
Write descriptions as trigger conditions
The agent matches skills to tasks based on the description. Be explicit: “Use when the user asks to generate unit tests for React components” works better than “Testing helper.”
Use paths to narrow scope
Use paths to narrow scope
If a skill only applies to your API layer, add
paths: [src/api/**] so it doesn’t activate for frontend tasks.Include examples in your instructions
Include examples in your instructions
Show the agent what good output looks like. A “before and after” example in the instructions is worth more than a paragraph of explanation.
Version control your skills
Version control your skills
Keep skills in your repo (
.agents/skills/). They evolve with your codebase and benefit from code review like any other file.