ai-rules-reviewer

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 ensure the AI agent follows your preferred patterns every time.

Create a skill directory in your project. In this case the skill is named pdf-processor:

```

.builder/skills/pdf-processor/

```

Add a SKILL.md file with your instructions:

```markdown

---

name: pdf-processor

description: Extract and analyze PDF documents

---

Instructions...

```

The skill is now available to invoke during your session.

Directory Structure

Skills are discovered from three locations:

• .builder/skills/ - Primary location for skills
• .claude/skills/ - Alternative
• .cursor/skills/ - Alternative

```

project/

└── .builder/

└── skills/

├── pdf/

│ └── SKILL.md

├── excel/

│ └── SKILL.md

└── office/

└── word/

└── SKILL.md # Nested skills supported

```

The file must be named SKILL.md (case-insensitive). Other files in the skill directory are ignored, so you can include helper files, READMEs, examples or even scripts alongside your skill.

Skills Format

Skills use a Markdown file with frontmatter that contains agent instructions. The name can be used as a direct reference in a prompt and the description provides context to the agent so that it can decide when to make use of the skill.

```markdown

---

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.

```

#### Frontmatter Fields

| Field | Required | Type | Description |

|-------|----------|------|-------------|

| name | No | string | Skill identifier. Defaults to parent directory name |

| description | No | string | Brief description shown when listing skills |

You can read more about the skills format at the official specification: https://agentskills.io/

Organizing Skills

#### Grouping Related 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.md

```

#### Including Helper Files

Only 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.sh

```

This lets you include supporting materials alongside your skill without affecting discovery. The agent loads these on demand, so smaller files mean less use of context.

Skills vs Rules

Skills and Rules serve different purposes:

| Aspect | Rules | Skills |

|--------|-------|--------|

| Location | .builder/rules/, .cursor/rules/ | .builder/skills/, .claude/skills/ |

| File naming | Any .mdc or .md file | Must be SKILL.md |

| Purpose | Passive context and guidelines | Active, invocable capabilities |

| Invocation | Automatic based on context | Explicit invocation |

Use Rules for project-wide guidelines (coding standards, file conventions). Use Skills for specialized tasks you or the agent can invoke on demand (processing specific file types, running audits).

Best Practices

• Keep skills focused — Each skill should handle one