Skip to content

feat: Improve skill #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jayan-blutui wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

feat: Improve skill #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f723807
add manually SKILL.md file
jayan-blutui Feb 23, 2026
451f65b
remove SKILL.md checks
jayan-blutui Feb 23, 2026
e2581eb
update reference links
jayan-blutui Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions skills/blutui-project-guidelines/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Each project can have multiple cassettes.

To switch cassettes, update the cassette property within the `courier.json` file. If this property is missing or undefined, prompt the user to provide the specific cassette handle.

Reference: [Link to documentation](https://dev.blutui.com/docs/cassettes/getting-started)
Reference: [Link to documentation](https://docs.blutui.com/docs/cassettes/getting-started)

### 0.3 Collections

Expand Down Expand Up @@ -83,7 +83,7 @@ To create, retreive and list collection or collection entries or links, the agen
</div>
```

Reference: [Link to documentation](https://dev.blutui.com/docs/collections/getting-started)
Reference: [Link to documentation](https://docs.blutui.com/docs/collections/getting-started)

### 0.4 Courier

Expand All @@ -95,7 +95,7 @@ Courier is a command-line interface tool to interact with a project. It allows u

Courier must be installed and configured on the user's machine to enable full functionality. `courier version` command can be used to check if the user has courier installed.

Reference: [Link to documentation](https://dev.blutui.com/docs/courier/getting-started)
Reference: [Link to documentation](https://docs.blutui.com/docs/courier/getting-started)

### 0.5 Form Standards

Expand Down Expand Up @@ -150,7 +150,7 @@ Ensure your `views` directory is organized as follows:
- Do not attempt to use custom field types. If a type is not on this list, default to `text` and notify the user.
- Always transmit field types to the MCP in lowercase format.

Reference: [Link to documentation](https://dev.blutui.com/guides/create-form)
Reference: [Link to documentation](https://docs.blutui.com/guides/create-form)

### 0.6 MCP

Expand Down Expand Up @@ -188,7 +188,7 @@ The agent must never skip the MCP step. A layout file without a corresponding pa
Reference:

- [Link to documentation - Connect to Blutui MCP](https://docs.blutui.com/docs/getting-started/agentic-development)
- [Link to documentation - Connect to Figma MCP](https://dev.blutui.com/guides/figma-to-blutui)
- [Link to documentation - Connect to Figma MCP](https://docs.blutui.com/guides/figma-to-blutui)

### 0.7 Routing Pattern Standards

Expand Down Expand Up @@ -236,7 +236,7 @@ The `cassette` property determines which project version is active.

After making changes to the `courier.json`, instruct user to restart their `courier dev` session or the Blutui MCP server if it's running.

Reference: [Courier configuration](https://dev.blutui.com/docs/courier/configuration)
Reference: [Courier configuration](https://docs.blutui.com/docs/courier/configuration)

### 1.2 File Structure

Expand Down Expand Up @@ -335,7 +335,7 @@ Reference: [How to create a layout](https://docs.blutui.com/guides/create-layout
Canvas serves as the template engine for Blutui, combining HTML, CSS, and JavaScript with unique Canvas logic to create fully customized project designs.

- The template is a regular text file. It can generate any text-based format (HTML, XML, CSV, LaTeX, etc.). The file extension is ".canvas".
- A template contains variables, tags, filters, functions, tests, expressions and other templating festures, which get replaced with values when the template is evaluated, and tags, which control the template's logic.
- A template contains variables, tags, filters, functions, tests, expressions and other templating features, which get replaced with values when the template is evaluated.

**Example**

Expand All @@ -348,7 +348,7 @@ Canvas serves as the template engine for Blutui, combining HTML, CSS, and JavaSc

<body>
<ul id="navigation">
{% for item in navigation>%}
{% for item in navigation %}
<li><a href="{{ item.href }}">{{ item.caption }}</a></li>
{% endfor %}
</ul>
Expand Down Expand Up @@ -532,7 +532,7 @@ Layout (`views/layouts/about.html`):
{% endblock %}
```

Reference: [Link to documentation](https://dev.blutui.com/guides/what-is-blutui-canvas)
Reference: [Link to documentation](https://docs.blutui.com/guides/what-is-blutui-canvas)

### 2.2 Including other templates

Expand Down
106 changes: 67 additions & 39 deletions skills/blutui-project-guidelines/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: blutui-project-guidelines
description: Guidelines for building Blutui projects. This skill should be used when writing, reviewing, or refactoring Blutui Canvas code.
description: Blutui project guidelines from the Blutui Engineering team. Use this skill whenever working on ANY Blutui project — writing or editing templates, layouts, components, or partials; creating or querying Collections; building or handling forms; configuring routing or Courier; working with Canopy or Cassettes; using the Blutui MCP; or setting up a new Blutui project from scratch. If the user mentions Blutui, Canopy, Cassettes, Courier, or any Blutui-specific concept, always load and follow this skill before writing any code or configuration.
license: MIT
metadata:
author: Blutui
Expand All @@ -9,60 +9,88 @@ metadata:

# Blutui Project Guidelines

Contains 12 rules across 3 categories, prioritized by impact to guide automated refactoring and code generation.
Rules for building high-quality Blutui projects. Always read this skill in full before generating any Blutui code or configuration. Then load the specific rule files that apply to your task (see **Rule Index** below).

## When to Apply
---

## Quick Decision: Which Rules to Load

| Your task | Load these rule files |
| -------------------------------------------------------- | --------------------------------------------------- |
| Creating/editing any template, layout, or component | `foundation-templates-and-layouts.md` |
| Writing Canvas template syntax (tags, filtes, functions) | `templating-canvas.md` |
| Working with Collections (querying, displaying data) | `collections.md` |
| Building or processing forms | `forms.md` |
| Setting up routing or URL patterns | `route-patterns.md` |
| Configuring Courier | `courier.md`, `foundation-courier-configuration.md` |
| Project file structure / starting a new project | `foundation-file-structure.md` |
| Version control / deployment | `cassettes.md` |
| Calling the Blutui MCP or writing MCP integrations | `mcp.md` |
| Using Canopy (in-page editor) | `canopy.md` |

Rule files live at: `rules/<rule-name>.md`

**Always load ALL rules that apply.** Multiple rules often overlap for a single task — for example, adding a contact form in a template requires `forms.md` + `foundation-templates-and-layouts.md`

---

## Core Principles (Apply to Every Task)

These apply regardless of which specific rules you load:

Reference these guidelines when:
### 1. Understand the templates → layouts relationship

- Writing new Blutui project templates, layouts, components, and more
- Refactoring existing frontend code
Blutui project have two distinct layers — **templates** and **layouts** — and it's important not to confuse them:

## Rule Categories by Priority
- **`templates/`** — The base Canvas files that define the full HTML shell of the page. Then define the `{% block %}` regions that layouts fill in. Think of these like the root layout files — developers own them, editors never touch them.
- **`layouts/`** — Built on top of templates by extending them. Layouts define the visual structure of a page as a content editor would think about it — e.g. a full-width page, a page with a sidebar, a landing page with no navigation. **In the project dashboard, editors select a layout when creating or editing a page**, so every layout a developer creates becomes an option available to editors.

| Priority | Category | Impact | Prefix |
| -------- | ---------- | -------- | ------------- |
| 0 | Section 0 | MEDIUM | `undefined-` |
| 1 | Foundation | CRITICAL | `foundation-` |
| 2 | Templating | CRITICAL | `templating-` |
The mental model: **templates are for developers** (HTML shell, global regions), **layouts are for editors** (page shape, content zones).

## Quick Reference
### 2. Use Canvas for all templating logic

### 0. Section 0 (MEDIUM)
Blutui uses Canvas as its templating language. Use Canvas filters, functions, and tags. See the **Templating** category in the **Rule Index** for more information.

### 3. Collections are the data layer

Store structured content (team members, products, etc.) in **Collections**, not hardcoded in templates. Query collections via the `cms.collection('<handle>')` function or using Blutui MCP.

### 4. Forms must use Blutui's form helpers

Never build raw HTML forms for data submission. Use Blutui's built-in form tags. See `rules/forms.md` for the full pattern.

### 5. Follow the established file structure

Don't invent new top-level directories. See `rules/foundation-file-structure.md` for the canonical layout of a Blutui project.

---

- `canopy` - Canopy
- `cassettes` - Cassettes - Project Version Control
- `collections` - Collections
- `courier` - Courier
- `forms` - Form Standards
- `mcp` - MCP
- `route-patterns` - Routing Pattern Standards
## Rule Index

### 1. Foundation (CRITICAL)
All rules are grouped by category:

- `foundation-courier-configuration` - Courier Configuration
- `foundation-file-structure` - File Structure
- `foundation-templates-and-layouts` - Templates and Layouts
### Foundation (CRITICAL — affects all projects)

### 2. Templating (CRITICAL)
- `rules/foundation-file-structure.md` — Directory layout, naming conventions
- `rules/foundation-templates-and-layouts.md` — Template/layout inheritance, blocks
- `rules/foundation-courier-configuration.md` — Courier setup and config

- `templating-canvas` - Canvas
- `templating-including-templates` - Including other templates
### Templating (CRITICAL — applies when writing any template)

## How to Use
- `rules/templating-canvas.md` — Canvas templating language: syntax, tags, filters, functions
- `rules/templating-including-templates.md` — `include`, `embed`, `extends` patterns

Read individual rule files for detailed explanations and code examples:
## What Each Rule File Contains

```
rules/canopy.md
rules/foundation-courier-configuration.md
rules/templating-canvas.md
```
Each rule file in `rules/` includes:

Each rule file contains:
- **Why it matters** — the problem it solves
- **The rule** — concise statement of what to do
- **Code examples** — correct and incorrect patterns
- **Common mistakes** — antipatterns to avoid

- Brief explanation of why it matters
## Full Reference

## Full Compiled Document
For all rules compiled in one document: `AGENTS.md`

For the complete guide with all rules expanded: `AGENTS.md`
Use `AGENTS.md` when you need a comprehensive reference or when you're unsure which rules apply — it's faster to scan then loading files individually.
2 changes: 1 addition & 1 deletion skills/blutui-project-guidelines/rules/cassettes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,4 @@ Each project can have multiple cassettes.

To switch cassettes, update the cassette property within the `courier.json` file. If this property is missing or undefined, prompt the user to provide the specific cassette handle.

Reference: [Link to documentation](https://dev.blutui.com/docs/cassettes/getting-started)
Reference: [Link to documentation](https://docs.blutui.com/docs/cassettes/getting-started)
2 changes: 1 addition & 1 deletion skills/blutui-project-guidelines/rules/collections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ To create, retreive and list collection or collection entries or links, the agen
</div>
```

Reference: [Link to documentation](https://dev.blutui.com/docs/collections/getting-started)
Reference: [Link to documentation](https://docs.blutui.com/docs/collections/getting-started)
2 changes: 1 addition & 1 deletion skills/blutui-project-guidelines/rules/courier.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,4 @@ Courier is a command-line interface tool to interact with a project. It allows u

Courier must be installed and configured on the user's machine to enable full functionality. `courier version` command can be used to check if the user has courier installed.

Reference: [Link to documentation](https://dev.blutui.com/docs/courier/getting-started)
Reference: [Link to documentation](https://docs.blutui.com/docs/courier/getting-started)
2 changes: 1 addition & 1 deletion skills/blutui-project-guidelines/rules/forms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,4 +56,4 @@ Ensure your `views` directory is organized as follows:
- Do not attempt to use custom field types. If a type is not on this list, default to `text` and notify the user.
- Always transmit field types to the MCP in lowercase format.

Reference: [Link to documentation](https://dev.blutui.com/guides/create-form)
Reference: [Link to documentation](https://docs.blutui.com/guides/create-form)
2 changes: 1 addition & 1 deletion skills/blutui-project-guidelines/rules/foundation-courier-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,4 @@ The `cassette` property determines which project version is active.

After making changes to the `courier.json`, instruct user to restart their `courier dev` session or the Blutui MCP server if it's running.

Reference: [Courier configuration](https://dev.blutui.com/docs/courier/configuration)
Reference: [Courier configuration](https://docs.blutui.com/docs/courier/configuration)
2 changes: 1 addition & 1 deletion skills/blutui-project-guidelines/rules/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,4 @@ The agent must never skip the MCP step. A layout file without a corresponding pa
Reference:

- [Link to documentation - Connect to Blutui MCP](https://docs.blutui.com/docs/getting-started/agentic-development)
- [Link to documentation - Connect to Figma MCP](https://dev.blutui.com/guides/figma-to-blutui)
- [Link to documentation - Connect to Figma MCP](https://docs.blutui.com/guides/figma-to-blutui)
8 changes: 4 additions & 4 deletions skills/blutui-project-guidelines/rules/templating-canvas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@
title: Canvas
impact: CRITICAL
impactDescription: High Impact (90%) - The Template Engine serves as the critical logic layer, binding HTML elements to Blutui-specific concepts. Strict adherence to this syntax is mandatory for data interactivity; without it, the project will fail to render or process dynamic data.
tags: canvas, variables, tags, filters, functions, tests, expressions, templating festures
tags: canvas, variables, tags, filters, functions, tests, expressions, templating features
---

Canvas serves as the template engine for Blutui, combining HTML, CSS, and JavaScript with unique Canvas logic to create fully customized project designs.

- The template is a regular text file. It can generate any text-based format (HTML, XML, CSV, LaTeX, etc.). The file extension is ".canvas".
- A template contains variables, tags, filters, functions, tests, expressions and other templating festures, which get replaced with values when the template is evaluated, and tags, which control the template's logic.
- A template contains variables, tags, filters, functions, tests, expressions and other templating features, which get replaced with values when the template is evaluated.

**Example**

Expand All @@ -21,7 +21,7 @@ Canvas serves as the template engine for Blutui, combining HTML, CSS, and JavaSc

<body>
<ul id="navigation">
{% for item in navigation>%}
{% for item in navigation %}
<li><a href="{{ item.href }}">{{ item.caption }}</a></li>
{% endfor %}
</ul>
Expand Down Expand Up @@ -205,4 +205,4 @@ Layout (`views/layouts/about.html`):
{% endblock %}
```

Reference: [Link to documentation](https://dev.blutui.com/guides/what-is-blutui-canvas)
Reference: [Link to documentation](https://docs.blutui.com/guides/what-is-blutui-canvas)
6 changes: 1 addition & 5 deletions skills/blutui-project-guidelines/skill.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,12 @@
{
"name": "blutui-project-guidelines",
"title": "Blutui Project Guidelines",
"description": "Guidelines for building Blutui projects. This skill should be used when writing, reviewing, or refactoring Blutui Canvas code.",
"description": "Blutui project guidelines from the Blutui Engineering team. Use this skill whenever working on ANY Blutui project — writing or editing templates, layouts, components, or partials; creating or querying Collections; building or handling forms; configuring routing or Courier; working with Canopy or Cassettes; using the Blutui MCP; or setting up a new Blutui project from scratch. If the user metions Blutui, Canopy, Cassettes, Courier, or any Blutui-specific concept, always load and follow this skill before writing any code or configuration.",
"license": "MIT",
"sections": {
"foundation": 1,
"templating": 2
},
"whenToApply": [
"Writing new Blutui project templates, layouts, components, and more",
"Refactoring existing frontend code"
],
"metadata": {
"author": "Blutui",
"version": "1.0.0"
Expand Down
Loading