> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom instructions

> Always-on guidance the agent follows across every prompt. Coding style, brand voice, defaults — set once, applied everywhere.

Custom instructions are **rules the agent follows on every prompt**. Use them for things you'd otherwise restate in every prompt: coding style preferences, default behaviors, things to never do.

## Where they live

| Scope | Where | Applies to |
| - | - | - |
| Workspace-wide | Workspace settings → Custom instructions | Every project in the workspace |
| Project-specific | Project settings → Custom instructions | This project only |

Project-specific instructions override workspace-wide on conflicts.

## Examples

### Coding style

```
- Use named functions, not arrow functions, for top-level components
- Prefer for-of over forEach
- Never use `any` in TypeScript; if you need an escape hatch, use `unknown` and narrow
- File names: kebab-case
- Imports: external first, then internal absolute, then relative — alphabetized within each group
```

### Brand and copy

```
- Tone is warm but professional. Don't use exclamation marks.
- Refer to ourselves as "we" not "the company"
- All currency is USD; format with Intl.NumberFormat, two decimals
- Dates: full month name + day + year ("April 18, 2026"), not numeric
```

### Defaults

```
- All forms use react-hook-form + zod for validation
- All toasts come from sonner, with the default duration 5 seconds
- All loading states use the shared <Skeleton /> component, not spinners
```

### Don'ts

```
- Don't add tests unless I explicitly ask
- Don't add TODO comments — open a tracking task instead
- Don't reformat or refactor code that's not part of the prompt
- Don't add console.log statements in production code paths
```

## Anatomy of a good instruction

<CardGroup cols={2}>
  <Card title="✅ Specific and actionable" icon="check-circle">
    "Use 4-space indentation in TypeScript files." Verifiable.
  </Card>

  <Card title="✅ Reasoned (when non-obvious)" icon="check-circle">
    "Prefer Convex actions over fetch() in components — it keeps API calls server-side." The 'why' helps the agent generalize.
  </Card>

  <Card title="❌ Vague" icon="x-circle">
    "Write good code." Unactionable.
  </Card>

  <Card title="❌ Contradictory" icon="x-circle">
    "Use functional components" + "Always use class components for forms". Pick one.
  </Card>
</CardGroup>

## Workspace-wide vs. project-specific

Use **workspace-wide** for rules that apply to all your work: coding style, naming conventions, etc.

Use **project-specific** for rules tied to one app: "This project uses Tailwind v4. The brand color is #FF6600. Reference the design system at [https://design.thisapp.com](https://design.thisapp.com)."

## Tips

<Tip>
  **Start small. Add as you correct.** Every time you reverse a vly decision, ask: "Could a custom instruction prevent this next time?" If yes, add it.
</Tip>

<Tip>
  **Use Markdown.** Custom instructions are parsed as markdown. Use bullets, code blocks, and headers for clarity.
</Tip>

<Tip>
  **Don't replicate the [knowledge base](/building/knowledge-base).** Custom instructions are *rules*. Knowledge is *reference*. If it's a fact ("our color is #6D28D9"), it's knowledge. If it's an action ("use this color"), it's an instruction.
</Tip>

## Related

<CardGroup cols={3}>
  <Card title="Knowledge base" icon="book" href="/building/knowledge-base">
    Reference material the agent reads.
  </Card>

  <Card title="Templates" icon="file-stack" href="/building/templates">
    Pre-built starting points.
  </Card>

  <Card title="Prompting fundamentals" icon="message-square" href="/prompting/fundamentals">
    The basics of writing a prompt.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.