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:
Add a SKILL.md file with your instructions:
The skill is now available to invoke during your session.
Builder discovers skills from these locations:
.builder/skills/: primary location for skills.claude/skills/: alternative
Here's example directory structure for skills in .builder/skills/:
Be 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.
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:
To invoke the accessibility skill, instruct the AI in the Builder prompt:
For more about the skills format, see the official specification at Agent Skills.
Use nested directories to organize related skills:
Only SKILL.md files are loaded—other files are ignored:
This 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
Full skill examples are included below.
When configuring your project, be sure to follow AI instructions best practices.