Skills are specialized knowledge and workflows that you or the AI agent can invoke during code generation sessions. Each skill defines specialized instructions for a domain such as processing PDFs, analyzing data, or reviewing code.
Use skills when you have recurring tasks that benefit from consistent, specialized behavior. Skills help the AI agent follow your preferred patterns every time.
Create a skill directory in your project. In this example the skill is named pdf-processor because the directory name should reflect the specific skill:
.builder/skills/pdf-processor/Add a SKILL.md file with your instructions:
---
name: pdf-processor
description: Extract and analyze PDF documents
---
Instructions...The skill is now available to invoke during your session.
Builder discovers skills from three locations:
.builder/skills/: primary location for skills.claude/skills/: alternative.cursor/skills/: alternative
Here's example directory structure for skills in .builder/skills/:
project/
└── .builder/
└── skills/
├── pdf/
│ └── SKILL.md
├── excel/
│ └── SKILL.md
└── office/
└── word/
└── SKILL.md # Nested skills supportedBe sure to name your file SKILL.md (case-insensitive). Builder ignores other files in the /skills directory, so you can include helper files, READMEs, examples, or even scripts alongside your skill.
Skill files are in markdown with frontmatter that contains the skill name and description:
name: the name of the skill. See as a direct reference in an AI prompt.description: context so the agent can decide when to make use of the skill
The example below shows the correct syntax for delineating the frontmatter and where to place the instructions that follow it.
---
name: skill-name
description: Brief description of what the skill does
---
Your skill instructions go here.
This content defines how the AI should behave when using this skill.Make sure you are as detailed as possible. In the following example, which configures an accessibility skill, the file provides specific instructions with good and bad examples, the types of questions the agent should be considering, as well as what to do when an issue arises:
---
name: accessibility-expert
description: Adopts the mindset of an accessibility expert when reviewing or generating UI. Use when creating components, forms, interactive elements, or reviewing any user-facing code.
---
You are an accessibility expert. Evaluate all UI through the lens of users with diverse abilities—screen reader users, keyboard-only navigation, low vision, cognitive differences.
**Always ask:**
- Can someone navigate this without a mouse?
- Can a screen reader convey what this does?
- Is meaning communicated without relying on color alone?
**Common issues to catch:**
```
Bad: <img src="photo.png">
Good: <img src="photo.png" alt="Description of image">
Bad: <button><Icon /></button>
Good: <button aria-label="Close"><Icon /></button>
Bad: <div onClick={handleClick}>
Good: <button onClick={handleClick}>
```
When you spot an issue, briefly explain *who* it affects and *why* it matters.For more about the skills format, see the official specification at Agent Skills.
Use nested directories to organize related skills:
.builder/skills/
├── office/
│ ├── pdf/
│ │ └── SKILL.md
│ ├── excel/
│ │ └── SKILL.md
│ └── word/
│ └── SKILL.md
├── database/
│ ├── migrations/
│ │ └── SKILL.md
│ └── queries/
│ └── SKILL.md
└── testing/
└── SKILL.mdOnly SKILL.md files are loaded—other files are ignored:
.claude/skills/pdf/
├── SKILL.md # The skill definition (required)
├── README.md # Documentation (ignored)
├── examples/ # Example files (ignored)
│ └── sample.pdf
└── scripts/ # Helper scripts (ignored, but can be referenced)
└── convert.shThis gives you a way to include supporting materials alongside your skill without affecting discovery. The agent loads these on demand, so smaller files mean less use of context.
While skills and rules might seem similar at first, they serve different purposes in your development workflow.
Know when to use each feature to help you organize your project effectively:
- Use Rules for project-wide guidelines, such as coding standards and file conventions.
- Use Skills for specialized tasks you or the agent can invoke on demand, such as processing specific file types or running audits.
| Context | Skills | Rules |
|---|---|---|
Location |
|
|
File name | Must be | Any |
Purpose | Active, invocable capabilities | Passive context and guidelines |
Invocation | Explicit invocation | Automatic based on context |
For more general information on configuring your project, see Project configuration files. For specific information on rules, see Builder rules.
When designing your skills, keep these characteristics in mind.
- Keep skills focused: each skill should handle one domain or task type well.
- Use descriptive names: the name should clearly indicate what the skill does.
- Document capabilities: be explicit about what the skill can and cannot do.
- Include examples: show example usage or expected output in the instructions
- Consider safety: for destructive operations, include confirmation steps in the instructions
When configuring your project, be sure to follow AI instructions best practices.