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 these locations:
.builder/skills/: primary location for skills.claude/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.To invoke the accessibility skill, instruct the AI in the Builder prompt:
Check this login form for accessibility issues using the
accessibility-expertFor 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
Full skill examples are included below.
---
name: agents-md-generator
description: "Generate comprehensive agents.md files for Builder.io Fusion projects. Creates project-specific AI instruction files that establish conventions, build commands, testing procedures, design system rules, and coding standards. Use when setting up a new project, onboarding a repository to AI-assisted development, or improving AI code generation quality."
---
# agents.md Generator
You are a specialist in creating `agents.md` files—the configuration files that Builder.io Fusion uses to understand project conventions. A well-crafted agents.md dramatically improves code generation quality by teaching the AI your team's patterns, preferences, and requirements.
## Determine the Workflow
Use AskUserQuestion to clarify which workflow the user needs:
1. **Generate New** - Create agents.md for a project that doesn't have one
2. **Update Existing** - Improve or expand an existing agents.md
3. **Analyze Only** - Review the project and provide recommendations without generating
If the user's intent is clear from their message, proceed directly.
## Quick Start
1. **Check for existing file**: Look for `agents.md` at the repository root
2. **Analyze the repository**: Examine existing patterns, dependencies, and configuration
3. **Identify the project type**: Framework, language, styling approach, testing setup
4. **Read specialized template**: Use the appropriate template for the project type
5. **Generate the agents.md**: Create a comprehensive file at repository root
6. **Validate**: Verify all commands work and paths are correct
## Why agents.md Matters
Without clear instructions, AI assistants guess at conventions. With a good agents.md, generated code looks like your team wrote it. The file should:
- Establish coding standards and naming conventions
- Document build, test, and dev commands
- Specify design system components and usage rules
- Define approved/forbidden dependencies
- List common pitfalls to avoid
## Section Priority Guide
| Section | Purpose | Priority |
|---------|---------|----------|
| Project Overview | Context about the app/repo | Required |
| Dev Environment | Setup, install, run commands | Required |
| Code Style | Formatting, naming, patterns | Required |
| Design System | Components, tokens, usage rules | High |
| Testing | Test commands, coverage requirements | High |
| File Structure | Where things go | Medium |
| Dependencies | What to use, what to avoid | Medium |
| Common Pitfalls | Mistakes to avoid | Medium |
| Git Workflow | Branching, commits, PRs | Optional |
## Specialized Resources
Read the appropriate template based on project type:
| Project Type | Resource | When to Use |
|-------------|----------|-------------|
| Monorepo | `monorepo-template.md` | Turborepo, Nx, pnpm workspaces |
| Next.js App Router | `nextjs-app-router-template.md` | Next.js 13+ with app directory |
| Standard project | `assets/complete-example.md` | General reference for any project |
## Repository Analysis Workflow
Before generating an agents.md, analyze the codebase systematically:
### Step 1: Package Manager & Scripts
Examine `package.json` for:
- Package manager (npm, pnpm, yarn, bun)
- Scripts: dev, build, test, lint commands
- Key dependencies (framework, styling, testing)
### Step 2: Framework & Structure
Identify by checking for these directories and files:
- `src/`, `app/`, `pages/`, `components/` directories
- Config files: `.eslintrc*`, `.prettierrc*`, `tsconfig.json`, `tailwind.config.*`, `biome.json`
- Framework indicators: `next.config.*`, `vite.config.*`, `nuxt.config.*`
Look for:
- React, Vue, Svelte, or other framework
- App Router vs Pages Router (Next.js)
- TypeScript configuration
- Styling approach (Tailwind, CSS Modules, etc.)
### Step 3: Design System
Search for:
- Design system imports (patterns like `from '@company/ui'`)
- Component library references in package.json (shadcn, radix, mui, chakra, mantine)
- Design token files or CSS variables
### Step 4: Testing Setup
Identify by looking for:
- Test files: `*.test.*`, `*.spec.*`
- Test config: `jest.config.*`, `vitest.config.*`, `playwright.config.*`
- Test libraries in package.json (testing-library, jest, vitest, playwright)
### Step 5: Monorepo Detection
Check for monorepo indicators:
- `turbo.json`, `nx.json`, `pnpm-workspace.yaml`, `lerna.json`
- `packages/`, `apps/`, `libs/` directories
- Workspaces configuration in package.json
If monorepo detected, read `monorepo-template.md` for additional sections.
## agents.md Template Structure
Generate the file at the repository root as `agents.md` with these sections:
```markdown
# agents.md
## Project Overview
[Brief description of what this application does]
**Tech Stack:**
- Framework: [Next.js 14 / React 18 / Vue 3 / etc.]
- Language: [TypeScript / JavaScript]
- Styling: [Tailwind CSS / CSS Modules / etc.]
- Testing: [Jest / Vitest / Playwright / etc.]
---
## Dev Environment
### Setup
[Package manager] install
cp .env.example .env.local
### Common Commands
| Command | Purpose |
|---------|---------|
| `[pm] dev` | Start development server |
| `[pm] build` | Production build |
| `[pm] test` | Run test suite |
| `[pm] lint` | Run linter |
---
## Code Style
### Naming Conventions
| Type | Convention | Example |
|------|------------|---------|
| Components | PascalCase | `UserProfile.tsx` |
| Hooks | camelCase with use prefix | `useAuth.ts` |
| Utilities | camelCase | `formatDate.ts` |
### File Organization
[Directory structure]
---
## Design System
[If applicable - component library, usage rules, tokens]
---
## Testing
[Test patterns, requirements, file locations]
---
## Common Pitfalls
[Project-specific mistakes to avoid]
```
See `assets/complete-example.md` for a fully-fleshed example.
## Handling Existing agents.md
If the project already has an `agents.md`:
1. **Read and analyze** the existing file
2. **Identify gaps** - missing sections, outdated commands, vague rules
3. **Propose updates** - show what would be added or changed
4. **Ask before replacing** - confirm with user before overwriting
## Validation Checklist
Before finalizing an agents.md, verify:
- [ ] File is named `agents.md` (lowercase) at repository root
- [ ] Package manager commands match actual scripts in package.json
- [ ] Build and dev commands actually exist
- [ ] Design system package name is accurate (if referenced)
- [ ] File structure matches actual repository
- [ ] No references to non-existent packages or files
- [ ] Under 500 lines total
## Best Practices
### Do:
- Start simple, add detail based on actual AI behavior issues
- Use specific file paths and real examples from the codebase
- Include actual component names from the design system
- Reference real configuration files (tsconfig paths, etc.)
- Update when conventions change
### Don't:
- Write vague guidance ("write clean code")
- Create rules that conflict with each other
- Exceed 500 lines—keep it focused
- Include sensitive information (API keys, internal URLs)
- Duplicate information that's in other config files
## Iteration Pattern
After creating the initial agents.md:
1. Generate code using the AI
2. Note where AI deviates from conventions
3. Add specific rules to address deviations
4. Repeat until AI output matches expectations
## Resources
| Resource | When to Use |
|----------|-------------|
| `assets/complete-example.md` | Full reference example |
| `monorepo-template.md` | Turborepo/Nx/pnpm workspaces |
| `nextjs-app-router-template.md` | Next.js 13+ App Router |
## Output Format
When generating an agents.md, provide:
1. **Analysis Summary**: Key findings from repository analysis
2. **Generated agents.md**: The complete file content
3. **Validation Notes**: Any commands to verify or potential issues found---
name: ai-rules-reviewer
description: "Review, fix, and create Builder.io Fusion rules files (.builderrules, .mdc, agents.md) for maximum AI effectiveness. Use to: (1) audit existing rules and get feedback, (2) fix rules that AI is ignoring, (3) get guidance when writing new rules."
---
# AI Rules Reviewer
You are a specialist in Builder.io Fusion rules files (`.builderrules`, `.mdc`, `agents.md`). You help users audit, fix, and create effective rules.
## Determine the Workflow
Use AskUserQuestion to clarify which workflow the user needs:
1. **Review & Audit** - Feedback on existing rules
2. **Fix Existing Rules** - Rules aren't working well
3. **Create New Rules** - Writing rules for the first time
If the user's intent is clear from their message, proceed directly.
## Why Rules Quality Matters
Every character in rules files consumes the AI's context window:
- Excessive rules lead to "rule fatigue" where AI ignores instructions
- Vague rules produce inconsistent code generation
- Conflicting rules confuse the AI
## File Size Limits
| File Type | Line Limit | Character Limit |
|-----------|-----------|-----------------|
| `.builderrules` | 200 lines | 6,000 chars |
| `.builder/rules/*.mdc` | 200 lines | 6,000 chars |
| Combined always-on | 500 lines | — |
| `alwaysApply: true` files | Max 3-5 | — |
**Thresholds:**
- **Good**: < 150 lines / < 5,000 chars
- **Warning**: 150-200 lines / 5,000-6,000 chars
- **Critical**: > 200 lines / > 6,000 chars
## Analysis Workflow
### Step 1: Find Rules Files
Search the project for:
- `.builderrules` (root and nested directories)
- `.builder/rules/*.mdc`
- `agents.md`
- Common mistakes: `.builderrule` (missing s), `AGENTS.md` (wrong case)
### Step 2: Analyze Each File
For each file, check:
- **Size**: Line count and character count
- **Frontmatter** (for `.mdc`): Has `---` block with `description`, `globs`, `alwaysApply`
- **Content quality**: Specific vs vague rules, bullets vs paragraphs
- **Conflicts**: Contradictory instructions across files
### Step 3: Report Findings
Use the template from `assets/review-template.md` to structure your report.
## Common Issues Checklist
| Issue | Severity |
|-------|----------|
| File > 200 lines | Critical |
| > 5 alwaysApply files | Critical |
| Wrong file naming | Critical |
| Missing frontmatter | High |
| Missing description | High |
| Vague rules | High |
| Verbose rules (paragraphs) | Medium |
| No code examples | Low |
See `common-issues.md` for detailed diagnostics and fixes.
## Frontmatter Requirements
Every `.builder/rules/*.mdc` file needs:
```yaml
---
description: Clear description of rule purpose
globs:
- "src/components/**/*.tsx"
alwaysApply: false
---
```
**Issues to detect:**
- Missing `description` field
- Missing frontmatter entirely
- `alwaysApply: true` overuse
- Overly broad `globs` patterns (`**/*`)
## Best Practices
### Do:
- Start simple, add detail based on actual AI behavior issues
- Use specific file paths and real examples from the codebase
- Use clear section headers and bullet points
- Scope rules with `globs` patterns when possible
### Don't:
- Write vague guidance ("write clean code")
- Exceed 200 lines per file
- Use more than 3-5 `alwaysApply: true` rules
- Include sensitive information (API keys, internal URLs)
- Write long paragraphs when bullets would work
## Resources
| Resource | When to Use |
|----------|-------------|
| `common-issues.md` | Detailed diagnostics and fixes |
| `file-organization.md` | Restructuring rules across files |
| `assets/review-template.md` | Output format for reviews |
| `assets/examples.md` | Good vs bad rule examples |
## When Rules Are Fine
If analysis finds no significant issues, report:
- Summary of files analyzed
- Confirmation that sizes are within limits
- Note any minor optional improvements
- Recommend continuing to monitor AI behavior
Don't force issues where none exist.
## Next Steps by Workflow
**Review/Audit:** Scan all rules files, analyze against criteria above, present findings using the review template.
**Fix Rules:** After identifying issues, edit files directly. Ask before major structural changes like splitting files.
**Create Rules:** Ask about the project structure and pain points, then guide through creating focused rules with proper frontmatter.---
name: applying-brand-guidelines
description: This skill applies consistent corporate branding and styling to all generated documents including colors, fonts, layouts, and messaging
---
# Corporate Brand Guidelines Skill
This skill ensures all generated documents adhere to corporate brand standards for consistent, professional communication.
## Brand Identity
### Company: Acme Corporation
**Tagline**: "Innovation Through Excellence"
**Industry**: Technology Solutions
## Visual Standards
### Color Palette
**Primary Colors**:
- **Acme Blue**: #0066CC (RGB: 0, 102, 204) - Headers, primary buttons
- **Acme Navy**: #003366 (RGB: 0, 51, 102) - Text, accents
- **White**: #FFFFFF - Backgrounds, reverse text
**Secondary Colors**:
- **Success Green**: #28A745 (RGB: 40, 167, 69) - Positive metrics
- **Warning Amber**: #FFC107 (RGB: 255, 193, 7) - Cautions
- **Error Red**: #DC3545 (RGB: 220, 53, 69) - Negative values
- **Neutral Gray**: #6C757D (RGB: 108, 117, 125) - Secondary text
### Typography
**Primary Font Family**: Segoe UI, system-ui, -apple-system, sans-serif
**Font Hierarchy**:
- **H1**: 32pt, Bold, Acme Blue
- **H2**: 24pt, Semibold, Acme Navy
- **H3**: 18pt, Semibold, Acme Navy
- **Body**: 11pt, Regular, Acme Navy
- **Caption**: 9pt, Regular, Neutral Gray
### Logo Usage
- Position: Top-left corner on first page/slide
- Size: 120px width (maintain aspect ratio)
- Clear space: Minimum 20px padding on all sides
- Never distort, rotate, or apply effects
## Document Standards
### PowerPoint Presentations
**Slide Templates**:
1. **Title Slide**: Company logo, presentation title, date, presenter
2. **Section Divider**: Section title with blue background
3. **Content Slide**: Title bar with blue background, white content area
4. **Data Slide**: For charts/graphs, maintain color palette
**Layout Rules**:
- Margins: 0.5 inches all sides
- Title position: Top 15% of slide
- Bullet indentation: 0.25 inches per level
- Maximum 6 bullet points per slide
- Charts use brand colors exclusively
### Excel Spreadsheets
**Formatting Standards**:
- **Headers**: Row 1, Bold, White text on Acme Blue background
- **Subheaders**: Bold, Acme Navy text
- **Data cells**: Regular, Acme Navy text
- **Borders**: Thin, Neutral Gray
- **Alternating rows**: Light gray (#F8F9FA) for readability
**Chart Defaults**:
- Primary series: Acme Blue
- Secondary series: Success Green
- Gridlines: Neutral Gray, 0.5pt
- No 3D effects or gradients
### PDF Documents
**Page Layout**:
- **Header**: Company logo left, document title center, page number right
- **Footer**: Copyright notice left, date center, classification right
- **Margins**: 1 inch all sides
- **Line spacing**: 1.15
- **Paragraph spacing**: 12pt after
**Section Formatting**:
- Main headings: Acme Blue, 16pt, bold
- Subheadings: Acme Navy, 14pt, semibold
- Body text: Acme Navy, 11pt, regular
## Content Guidelines
### Tone of Voice
- **Professional**: Formal but approachable
- **Clear**: Avoid jargon, use simple language
- **Active**: Use active voice, action-oriented
- **Positive**: Focus on solutions and benefits
### Standard Phrases
**Opening Statements**:
- "At Acme Corporation, we..."
- "Our commitment to innovation..."
- "Delivering excellence through..."
**Closing Statements**:
- "Thank you for your continued partnership."
- "We look forward to serving your needs."
- "Together, we achieve excellence."
### Data Presentation
**Numbers**:
- Use comma separators for thousands
- Currency: $X,XXX.XX format
- Percentages: XX.X% (one decimal)
- Dates: Month DD, YYYY
**Tables**:
- Headers in brand blue
- Alternating row colors
- Right-align numbers
- Left-align text
## Quality Standards
### Before Finalizing
Always ensure:
1. Logo is properly placed and sized
2. All colors match brand palette exactly
3. Fonts are consistent throughout
4. No typos or grammatical errors
5. Data is accurately presented
6. Professional tone maintained
### Prohibited Elements
Never use:
- Clip art or stock photos without approval
- Comic Sans, Papyrus, or decorative fonts
- Rainbow colors or gradients
- Animations or transitions (unless specified)
- Competitor branding or references
## Application Instructions
When creating any document:
1. Start with brand colors and fonts
2. Apply appropriate template structure
3. Include logo on first page/slide
4. Use consistent formatting throughout
5. Review against brand standards
6. Ensure professional appearance
## Scripts
- `apply_brand.py`: Automatically applies brand formatting to documents
- `validate_brand.py`: Checks documents for brand compliance
## Notes
- These guidelines apply to all external communications
- Internal documents may use simplified formatting
- Special projects may have exceptions (request approval)
- Brand guidelines updated quarterly - check for latest versionWhen configuring your project, be sure to follow AI instructions best practices.
Was this article helpful?