> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-in-ai/17.latest/mcp/cms-developer-mcp/best-practice/example-instructions.md).

# Example Instructions File

Custom instructions help guide your AI assistant to follow your specific Umbraco development practices and conventions. By creating an instructions file in your project, you can ensure consistent behavior across all interactions with the MCP server.

The example below demonstrates a comprehensive instruction file that covers tool usage, content structure, templates, and other best practices. The version of Umbraco (v16.2.0) is explicitly specified in the title. This helps AI assistants use version-specific documentation sources like Context7 to provide accurate guidance for your Umbraco installation.

Created by [Tom Madden](https://github.com/TwoMoreThings)

## Example Instruction File

```markdown
# Umbraco Development Guidelines (v16.2.0)

## Tool Usage

- Use Context7 to retrieve Umbraco v16.2.0 documentation
- Use the Umbraco MCP tool for ALL Umbraco interactions - make multiple calls as needed, never try to optimize with bulk operations
- Use create-media MCP tool for media items, referencing files in wwwroot/media/my-folder

## Content Structure

- Always use Block List over Block Grid for composable pages
- All navigable content pages must be nested under the Home page
- All Content Type properties must belong to either a tab or a group

## Block List Configuration

- Items require a contentKey in UUID/GUID format
    - Define labels using the Umbraco Flavored Markdown format, e.g. {umbValue: propertyAlias} (not {{$propertyAlias}})

## Templates & Content Types

- For web page content types (non-element types):
    - Create corresponding template via Management API first
    - Assign template to content type
    - Set as default template

## Data Types

- Save new Data Types in 'Custom Data Types' folder
- Use 'Rich Text Editor [Tiptap]' for formatted text content
- Use Link Picker instead of multiple TextString properties for links

## File Handling

- Never modify file metadata/dates (preserves Git change tracking)
- Add static assets to wwwroot subdirectories
- When downloading images, exclude favicon.png and apple-icon.png
- Look for CSS/inline style images, not just src attributes

## Models & Publishing

- STOP and prompt user to generate models and restart site (never generate manually)
- Verify the node Layout is set correctly when saving/publishing pages


## Adding New Blocks

1. Create the content type in Umbraco backoffice (requires user interaction or the umbraco-mcp tool)
2. Models auto-generate in `Website.Core/Models/`
3. Create rendering partial in `Website.Web/Views/Partials/blockgrid/Components/`
4. Add SCSS styling in `Website.Web.Assets/Client/src/scss/blocks/`
5. Import SCSS in `Client/src/scss/blocks/_blocks.scss`
6. Add the new block to the "grid main" Block Grid Editor data type in Umbraco with appropriate label and setup for areas and resizing

```

This example demonstrates how to create project-specific guidelines that your AI assistant can consistently follow throughout your development workflow.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/umbraco-in-ai/17.latest/mcp/cms-developer-mcp/best-practice/example-instructions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.