Snippets

Snippets are reusable chunks of markdown that help you build consistent, powerful prompts across your Roll workspace. Think of them as building blocks for your agent instructions—create once, use anywhere.

What are Snippets?

Snippets are named, versioned pieces of markdown content that can be referenced in any prompt field throughout Roll. Whether you’re configuring workspace defaults, team settings, issue-specific instructions, or your profile preferences, snippets let you compose complex prompts from reusable components.

Core Concepts

Referencing Snippets

Reference any snippet using the @@ syntax:

@@username/snippet-name - Uses the latest version
@@username/snippet-name::2 - Uses a specific version (version 2)

When you type @@ in any prompt field, a suggestion menu appears showing:

Your snippets - All snippets you’ve created
Workspace snippets - Snippets shared with your workspace
Starred snippets - Public snippets you’ve starred for quick access

The menu is searchable and updates in real-time as you type.

Visibility Levels

Every snippet has one of three visibility levels:

Private - Only you can see and use these snippets
Workspace - All members of your Linear workspace can reference these
Public - Anyone on Roll can discover, star, and fork these snippets

Versioning

Snippets are immutable—each edit creates a new version while preserving the complete history. This ensures:

Your prompts never break when a snippet is updated
You can pin specific versions for stability
You can review the evolution of a snippet over time

When referencing a snippet without a version (e.g., @@username/api-handler), Roll always uses the latest version. To lock in a specific version, use the version selector in the editor or specify it directly: @@username/api-handler::3.

Working with Snippets

Creating Snippets

Create snippets from the Snippets page in your Roll dashboard. Each snippet includes:

Identifier - A unique, URL-friendly name (e.g., api-response-handler)
Name - A human-readable title
Description - Optional context about what the snippet does
Content - The markdown content, which can include references to other snippets
Tags - Help sort & find snippets
Visibility - Choose who can access this snippet

Composing with Snippets

Snippets can reference other snippets, allowing you to build complex prompt hierarchies:

# API Handler Instructions
 
@@username/error-handling
@@username/rate-limiting
@@shared/coding-standards
 
When working with APIs, always...

Roll automatically resolves all snippet references when executing prompts, handling circular dependencies and permission checks.

Public Snippet Features

Starring

Star any public snippet to add it to your quick-access list. Starred snippets appear in your suggestion menu and library, making them as convenient as your own snippets.

Forking

Fork a public snippet to create your own private copy. This is perfect when you want to customize someone else’s snippet for your specific needs. The forked snippet starts as a private copy with “(fork)” appended to its name.

Best Practices

Use Descriptive Identifiers

Choose clear, searchable identifiers like python-testing-setup rather than generic names like test-1.

Version Strategically

Use unversioned references (@@username/snippet) for snippets you control and want to keep updated
Pin versions (@@username/snippet::2) for external snippets or when stability is critical

Organize with Tags

Tag your public snippets with relevant keywords to help others discover them. Common tags include the programming language, framework, or problem domain.

Build Composable Libraries

Create small, focused snippets that do one thing well, then compose them into larger prompts. This makes your prompt library more maintainable and reusable.

Use workspace-visible snippets to establish team conventions, coding standards, and shared context that all agents should follow.

Advanced Features

Snippet Dependencies

When a snippet references other snippets, Roll tracks these dependencies and ensures they’re all accessible when the prompt is rendered. Dependencies always use the latest version to avoid version conflicts.

Recursive Resolution

Snippets can reference snippets that reference other snippets, creating deep composition chains. Roll handles the recursive resolution automatically, with safeguards against circular dependencies.

Visual Preview

In the editor, snippet references appear as collapsible blocks showing:

The snippet name and owner
Version selector for pinning
Expandable preview of the snippet content
Quick link to view the full snippet

Common Use Cases

Coding Standards

Create snippets for language-specific best practices, then reference them in issue prompts:

@@team/python-standards
@@team/testing-requirements

Project Context

Build comprehensive project context from modular pieces:

@@workspace/architecture-overview
@@workspace/api-documentation
@@workspace/deployment-process

Personal Preferences

Set up your profile with your preferred working style:

@@myusername/communication-style
@@myusername/code-review-process

Reusable Instructions

Share common patterns across your organization:

@@public/error-handling-best-practices
@@public/security-checklist

Tips

Start with private snippets and promote to workspace or public once refined
Use the browse page to discover popular public snippets
Keep snippets focused—it’s better to compose multiple small snippets than maintain one large one
Document your snippets well, especially public ones that others might use
Review snippet versions before updating to avoid breaking changes

Getting Started Prompting