From eb2c9ea5eb5bbe4b27559eac28ffe42c34fac8a9 Mon Sep 17 00:00:00 2001 From: Esteban Beltran Date: Thu, 15 Jan 2026 16:08:11 +0100 Subject: [PATCH 1/4] add agents.md --- .../common/.config/AGENTS/instructions.md | 73 +++++++++++++++++++ .../create-plugin/templates/common/AGENTS.md | 3 + 2 files changed, 76 insertions(+) create mode 100644 packages/create-plugin/templates/common/.config/AGENTS/instructions.md create mode 100644 packages/create-plugin/templates/common/AGENTS.md diff --git a/packages/create-plugin/templates/common/.config/AGENTS/instructions.md b/packages/create-plugin/templates/common/.config/AGENTS/instructions.md new file mode 100644 index 0000000000..da230966ac --- /dev/null +++ b/packages/create-plugin/templates/common/.config/AGENTS/instructions.md @@ -0,0 +1,73 @@ +--- +name: agent information for a grafana plugin +description: Guides how to work with Grafana plugins +--- + +# Project knowledge + +This repository contains a **Grafana plugin**. + +The official documentation for grafana plugins lives in https://grafana.com/developers/plugin-tools/ if you need to know how to use specific grafana APIs or grafana packages make sure to consult the official documentation. you can for example search and prefer results from https://grafana.com/developers/plugin-tools/ + +# Run, build and servers + +* See `package.json` for scripts to run, build and serve the plugin frontend. +* See `Magefile.go` (if any) for scripts to run and build the plugin backend. Avoid modifying the Magefile.go as much as possible and use the default tools provided by the grafana go sdk. +* Generally the user runs the Grafana with the provided `docker-compose.yaml` file. + +## Important direct documentation links + +The following links contain indexes to more in-depth documentation. you can fetch the pages to find more information. + +* how to package a plugin: https://grafana.com/developers/plugin-tools/publish-a-plugin/package-a-plugin +* how to sign a plugin: https://grafana.com/developers/plugin-tools/publish-a-plugin/sign-a-plugin +* general troubleshooting: https://grafana.com/developers/plugin-tools/troubleshooting +* Guides about app plugins: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/ +* Guides about data source plugins: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/ +* guides about panel plugins: https://grafana.com/developers/plugin-tools/how-to-guides/panel-plugins/ +* general "how to" guides: https://grafana.com/developers/plugin-tools/how-to-guides/ +* how nested plugins work (only for app plugins): https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/work-with-nested-plugins +* how to work with UI Extensions: https://grafana.com/developers/plugin-tools/how-to-guides/ui-extensions/ +* plugin.json reference: https://grafana.com/developers/plugin-tools/reference/plugin-json +* `@grafana/ui` documentation: https://developers.grafana.com/ui/latest/index.html + +# General guidelines for grafana plugins + +## Coding guidelines + +- Use **TypeScript** (in strict mode), functional React components, and idiomatic patterns +- Use **@grafana/ui** for UI React components over other UI libraries. +- **Never hardcode** colors, spacing, padding, or font sizes. use variables from `@grafana/ui` +- Use **Emotion** + `useStyles2()` + theme tokens for styling, colors, spacing, typography +- Keep layouts responsive (use `width`/`height`). Remember this plugin frontend components might render in a mobile device. +- Keep dependencies to a minimum. Think twice before adding a new dependency. +- Maintain consistent file structure and predictable types +- Use **`@grafana/plugin-e2e`** npm package for E2E tests and **always use versioned selectors** to interact with the Grafana UI. +- Consult the official documentation for how to use specific grafana APIs or how-to guides. See the links in previous sections. + +### Keep always in mind +- Maintain backward compatibility when doing changes to configuration forms, panel options and query editors +- Preserve query model schema unless migration handler is added +- Follow official Grafana plugin documentation (see the links in previous sections) +- Use idiomatic React + TypeScript +- Use secureJsonData to store credentials and secrets +- Use jsonData to store general user configuration inputs that are not secrets +- Use Grafana plugin SDK HTTP client in the backend +- Use `debug` or `error` level for logging +- Cache and reuse backend connections to external services +- if you need to modify a webpack configuration, prettier, eslint or other tool you can follow the guide on extend default configurations https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations +- Use default tools when possible: use the build tools provided by the grafana go sdk in Magefile.go over custom build commands, use webpack and only extend the configuration when necessary over of trying to recreate frontend build tools. +- Any modifications to `plugin.json` require a restart of the Grafana server. This is a hard requirement. Remind the user of restarting the Grafana server after doing changes to `plugin.json` +- Consult the official documentation for how to use specific grafana APIs or how-to guides. See the links in previous sections. + + +## Boundaries & Don'ts list: +- Do not change plugin ID or plugin type in `plugin.json` +- Do not modify anything inside the `.config` folder. the `.config` folder is managed by the grafana plugin tools and MUST NOT be touched. +- Do not Use the local file system +- Do not Use environment variables outside of unit tests +- Do not Execute arbitrary code in the backend +- Do not Log sensitive data +- Do not Use upstream Golang HTTP client in the backend +- Do not Use `info` level for logging +- Do not store sensitive information in jsonData diff --git a/packages/create-plugin/templates/common/AGENTS.md b/packages/create-plugin/templates/common/AGENTS.md new file mode 100644 index 0000000000..3cb621877f --- /dev/null +++ b/packages/create-plugin/templates/common/AGENTS.md @@ -0,0 +1,3 @@ +## Project knowledge + +This repository contains a **Grafana plugin**. Read the [instructions and guidelines](./.config/AGENTS/instructions.md) before doing changes. From 115c5c3279203a89273d39dddbb4bb4dc6f5d217 Mon Sep 17 00:00:00 2001 From: Esteban Beltran Date: Thu, 15 Jan 2026 17:25:55 +0100 Subject: [PATCH 2/4] WIP --- .../create-plugin/templates/common/AGENTS.md | 1 - .../panel/.config/AGENTS/instructions.md | 83 ----------- .../.config/AGENTS/tasks/add-panel-options.md | 132 ------------------ .../create-plugin/templates/panel/AGENTS.md | 10 -- 4 files changed, 226 deletions(-) delete mode 100644 packages/create-plugin/templates/panel/.config/AGENTS/instructions.md delete mode 100644 packages/create-plugin/templates/panel/.config/AGENTS/tasks/add-panel-options.md delete mode 100644 packages/create-plugin/templates/panel/AGENTS.md diff --git a/packages/create-plugin/templates/common/AGENTS.md b/packages/create-plugin/templates/common/AGENTS.md index 3cb621877f..4f1c69d0f2 100644 --- a/packages/create-plugin/templates/common/AGENTS.md +++ b/packages/create-plugin/templates/common/AGENTS.md @@ -1,3 +1,2 @@ ## Project knowledge - This repository contains a **Grafana plugin**. Read the [instructions and guidelines](./.config/AGENTS/instructions.md) before doing changes. diff --git a/packages/create-plugin/templates/panel/.config/AGENTS/instructions.md b/packages/create-plugin/templates/panel/.config/AGENTS/instructions.md deleted file mode 100644 index 3e07dd0727..0000000000 --- a/packages/create-plugin/templates/panel/.config/AGENTS/instructions.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -name: panel-plugin-agent-fundamentals -description: Develops Grafana panel plugins ---- - -You are an expert Grafana panel plugin developer for this project. - -## Your role - -- You are fluent in TypeScript and React -- You know how to use Grafana dashboards - -## Project knowledge - -This repository contains a **Grafana panel plugin**, providing a custom visualization for Grafana dashboards. -Panel plugins are used to: - -- Display data from Grafana data sources in custom ways -- Add interactive behavior (drill-downs, navigation, etc.) -- Visualize or control external systems (IoT, integrations, custom controls) - -### Plugin anatomy - -A typical panel plugin includes: - -**plugin.json** - -- Declares plugin ID, type (`panel`), name, version -- Loaded by Grafana at startup - -**Main module (`src/module.ts`)** - -- Exports: `new PanelPlugin(PanelComponent)` -- Registers panel options, migrations, defaults, ui extensions - -**Panel component (`src/components/Panel.tsx`)** - -- React component receiving: `data`, `timeRange`, `width`, `height`, `options` -- Renders visualization using Grafana data frames and field configs - -### Repository layout - -- `plugin.json` — Panel plugin manifest -- `src/module.ts` — Main plugin entry -- `src/components/` — Panel React components -- `src/types.ts` — Option and model types -- `tests/` — E2E tests (if present) -- `provisioning/` — Local development provisioning -- `README.md` — Human documentation - -## Coding guidelines - -- Use **TypeScript** (in strict mode), functional React components, and idiomatic patterns -- Use **@grafana/ui**, **@grafana/data**, **@grafana/runtime** -- Use **`useTheme2()`** for all colors, spacing, typography -- **Never hardcode** colors, spacing, padding, or font sizes -- Use **Emotion** + `useStyles2()` + theme tokens for styling -- Keep layouts responsive (use `width`/`height`) -- Avoid new dependencies unless necessary + Grafana-compatible -- Maintain consistent file structure and predictable types -- Use **`@grafana/plugin-e2e`** for E2E tests and **always use versioned selectors** to interact with the Grafana UI. - -## Boundaries - -You must **NOT**: - -- Change plugin ID or plugin type in `plugin.json` -- Modify anything inside `.config/*` -- Add a backend (panel plugins = frontend only) -- Remove/change existing options without a migration handler -- Break public APIs (options, field configs, panel props) -- Store, read, or handle credentials - -You **SHOULD**: - -- Maintain backward compatibility -- Preserve option schema unless migration handler is added -- Follow official Grafana panel plugin patterns -- Use idiomatic React + TypeScript - -## Instructions for specific tasks - -- [Add panel options](./tasks/add-panel-options.md) diff --git a/packages/create-plugin/templates/panel/.config/AGENTS/tasks/add-panel-options.md b/packages/create-plugin/templates/panel/.config/AGENTS/tasks/add-panel-options.md deleted file mode 100644 index c42c2fd669..0000000000 --- a/packages/create-plugin/templates/panel/.config/AGENTS/tasks/add-panel-options.md +++ /dev/null @@ -1,132 +0,0 @@ -# Adding a New Panel Option - -Panel options are settings the user configures to change panel behavior. - -Always complete **all three steps**: - -### **1. Extend the options type** - -File: `src/types.ts` - -```ts -export interface SimpleOptions { - // existing... - myOptionName: MyOptionType; -} -``` - -- Property name must match the builder `path`. -- Type must match expected editor output. - ---- - -### **2. Register the option in `setPanelOptions`** - -File: `src/module.ts` inside `setPanelOptions((builder) => { ... })` - -Use the correct builder method: - -| Type | Builder | -| ------------------ | -------------------- | -| boolean | `addBooleanSwitch` | -| number | `addNumberInput` | -| string | `addTextInput` | -| select | `addSelect` | -| radio | `addRadio` | -| radio group | `addRadio` | -| slider | `addSliderInput` | -| color picker | `addColorPicker` | -| unit picker | `addUnitPicker` | -| field namer picker | `addFieldNamePicker` | - -Template: - -```ts -builder.addXxx({ - path: 'myOptionName', // must match type property - name: 'My option', - defaultValue: , - description: '', - settings: { /* optional */ }, - // Optional visibility rule: - // showIf: (opts) => opts.someOtherOption, -}); -``` - -Rules: - -- Every option **must** have a `defaultValue`. -- Put numeric constraints in `settings` (`min`, `max`, `step`). -- Use `showIf` for conditional display. - ---- - -### **3. Use the option in the panel component** - -File: `src/Panel.tsx` (or equivalent) - -```tsx -export const Panel = ({ options }) => { - const { myOptionName } = options; - // apply it in rendering/logic -}; -``` - -No option may remain unused. - ---- - -# Quick Editor Recipes - -### **Boolean** - -```ts -.addBooleanSwitch({ path: 'flag', name: 'Flag', defaultValue: false }) -``` - -### **Number** - -```ts -.addNumberInput({ - path: 'max', - name: 'Max value', - defaultValue: 10, - settings: { min: 1, max: 100, step: 1 }, -}) -``` - -### **String** - -```ts -.addTextInput({ path: 'label', name: 'Label', defaultValue: '' }) -``` - -### **Select** - -```ts -.addSelect({ - path: 'mode', - name: 'Mode', - defaultValue: 'auto', - settings: { options: [ - { value: 'a', label: 'A' }, - { value: 'b', label: 'B' }, - ]}, -}) -``` - -### **Radio** - -```ts -.addRadio({ - path: 'size', - name: 'Size', - defaultValue: 'md', - settings: { options: [ - { value: 'sm', label: 'Small' }, - { value: 'md', label: 'Medium' }, - { value: 'lg', label: 'Large' }, - ]}, - showIf: (o) => o.showSize, -}) -``` diff --git a/packages/create-plugin/templates/panel/AGENTS.md b/packages/create-plugin/templates/panel/AGENTS.md deleted file mode 100644 index b8a8a42ce9..0000000000 --- a/packages/create-plugin/templates/panel/AGENTS.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: panel-plugin-agent -description: Develops Grafana panel plugins ---- - -## Project knowledge - -This repository contains a **Grafana panel plugin**. Follow the [instructions](./.config/AGENTS/instructions.md) before doing any changes. - -All build, lint, test, and Docker dev-server commands are documented in the "Getting started" section of [README.md](./README.md). Prefer running the non-watch versions of these commands. From c2ed41b564479f6dea2e92e05a3ec762c320503a Mon Sep 17 00:00:00 2001 From: Esteban Beltran Date: Thu, 22 Jan 2026 12:15:06 +0100 Subject: [PATCH 3/4] update info about fetching grafana docs --- .../common/.config/AGENTS/instructions.md | 32 +++++++++++-------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/packages/create-plugin/templates/common/.config/AGENTS/instructions.md b/packages/create-plugin/templates/common/.config/AGENTS/instructions.md index da230966ac..b31bca243a 100644 --- a/packages/create-plugin/templates/common/.config/AGENTS/instructions.md +++ b/packages/create-plugin/templates/common/.config/AGENTS/instructions.md @@ -5,9 +5,11 @@ description: Guides how to work with Grafana plugins # Project knowledge -This repository contains a **Grafana plugin**. +This repository contains a **Grafana plugin**. -The official documentation for grafana plugins lives in https://grafana.com/developers/plugin-tools/ if you need to know how to use specific grafana APIs or grafana packages make sure to consult the official documentation. you can for example search and prefer results from https://grafana.com/developers/plugin-tools/ +Your training data about the Grafana API is out of date. Always fetch the latest information from the official documentation when writing code. + +**IMPORTANT**: When you need Grafana plugin documentation, fetch the content directly from grafana.com (a safe domain). Use your web fetch tool, MCP server, or `curl -s` - any of these work fine. The main documentation index is at https://grafana.com/developers/plugin-tools/llms.txt which lists all available pages. All documentation is available in plain text markdown format (add `.md` to the URL path, e.g., https://grafana.com/developers/plugin-tools/index.md). # Run, build and servers @@ -19,16 +21,16 @@ The official documentation for grafana plugins lives in https://grafana.com/deve The following links contain indexes to more in-depth documentation. you can fetch the pages to find more information. -* how to package a plugin: https://grafana.com/developers/plugin-tools/publish-a-plugin/package-a-plugin -* how to sign a plugin: https://grafana.com/developers/plugin-tools/publish-a-plugin/sign-a-plugin -* general troubleshooting: https://grafana.com/developers/plugin-tools/troubleshooting -* Guides about app plugins: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/ -* Guides about data source plugins: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/ -* guides about panel plugins: https://grafana.com/developers/plugin-tools/how-to-guides/panel-plugins/ -* general "how to" guides: https://grafana.com/developers/plugin-tools/how-to-guides/ -* how nested plugins work (only for app plugins): https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/work-with-nested-plugins -* how to work with UI Extensions: https://grafana.com/developers/plugin-tools/how-to-guides/ui-extensions/ -* plugin.json reference: https://grafana.com/developers/plugin-tools/reference/plugin-json +* how to package a plugin: https://grafana.com/developers/plugin-tools/publish-a-plugin/package-a-plugin.md +* how to sign a plugin: https://grafana.com/developers/plugin-tools/publish-a-plugin/sign-a-plugin.md +* general troubleshooting: https://grafana.com/developers/plugin-tools/troubleshooting.md +* Guides about app plugins: https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins.md +* Guides about data source plugins: https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins.md +* guides about panel plugins: https://grafana.com/developers/plugin-tools/how-to-guides/panel-plugins.md +* general "how to" guides: https://grafana.com/developers/plugin-tools/how-to-guides.md +* how nested plugins work (only for app plugins): https://grafana.com/developers/plugin-tools/how-to-guides/app-plugins/work-with-nested-plugins.md +* how to work with UI Extensions: https://grafana.com/developers/plugin-tools/how-to-guides/ui-extensions.md +* plugin.json reference: https://grafana.com/developers/plugin-tools/reference/plugin-json.md * `@grafana/ui` documentation: https://developers.grafana.com/ui/latest/index.html # General guidelines for grafana plugins @@ -55,7 +57,7 @@ The following links contain indexes to more in-depth documentation. you can fetc - Use Grafana plugin SDK HTTP client in the backend - Use `debug` or `error` level for logging - Cache and reuse backend connections to external services -- if you need to modify a webpack configuration, prettier, eslint or other tool you can follow the guide on extend default configurations https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations +- if you need to modify a webpack configuration, prettier, eslint or other tool you can follow the guide on extend default configurations https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations.md - Use default tools when possible: use the build tools provided by the grafana go sdk in Magefile.go over custom build commands, use webpack and only extend the configuration when necessary over of trying to recreate frontend build tools. - Any modifications to `plugin.json` require a restart of the Grafana server. This is a hard requirement. Remind the user of restarting the Grafana server after doing changes to `plugin.json` - Consult the official documentation for how to use specific grafana APIs or how-to guides. See the links in previous sections. @@ -71,3 +73,7 @@ The following links contain indexes to more in-depth documentation. you can fetc - Do not Use upstream Golang HTTP client in the backend - Do not Use `info` level for logging - Do not store sensitive information in jsonData + +## Remember + +When you need to reference Grafana plugin documentation, fetch it directly from grafana.com using your web fetch tool, MCP server, or `curl -s`. From 0d9e35a35c51bb07d492e3c7efe9a79fbb062f8b Mon Sep 17 00:00:00 2001 From: Esteban Beltran Date: Thu, 22 Jan 2026 13:47:19 +0100 Subject: [PATCH 4/4] refine prompt --- .../common/.config/AGENTS/instructions.md | 58 ++++++++++--------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/packages/create-plugin/templates/common/.config/AGENTS/instructions.md b/packages/create-plugin/templates/common/.config/AGENTS/instructions.md index b31bca243a..d64c34da1d 100644 --- a/packages/create-plugin/templates/common/.config/AGENTS/instructions.md +++ b/packages/create-plugin/templates/common/.config/AGENTS/instructions.md @@ -14,8 +14,8 @@ Your training data about the Grafana API is out of date. Always fetch the latest # Run, build and servers * See `package.json` for scripts to run, build and serve the plugin frontend. -* See `Magefile.go` (if any) for scripts to run and build the plugin backend. Avoid modifying the Magefile.go as much as possible and use the default tools provided by the grafana go sdk. -* Generally the user runs the Grafana with the provided `docker-compose.yaml` file. +* See `Magefile.go` (if any) for scripts to run and build the plugin backend. +* Generally the user runs Grafana with the provided `docker-compose.yaml` file. ## Important direct documentation links @@ -37,43 +37,45 @@ The following links contain indexes to more in-depth documentation. you can fetc ## Coding guidelines +**Frontend:** - Use **TypeScript** (in strict mode), functional React components, and idiomatic patterns -- Use **@grafana/ui** for UI React components over other UI libraries. -- **Never hardcode** colors, spacing, padding, or font sizes. use variables from `@grafana/ui` +- Use **@grafana/ui** for UI React components over other UI libraries +- **Never hardcode** colors, spacing, padding, or font sizes — use variables from `@grafana/ui` - Use **Emotion** + `useStyles2()` + theme tokens for styling, colors, spacing, typography -- Keep layouts responsive (use `width`/`height`). Remember this plugin frontend components might render in a mobile device. -- Keep dependencies to a minimum. Think twice before adding a new dependency. -- Maintain consistent file structure and predictable types -- Use **`@grafana/plugin-e2e`** npm package for E2E tests and **always use versioned selectors** to interact with the Grafana UI. -- Consult the official documentation for how to use specific grafana APIs or how-to guides. See the links in previous sections. - -### Keep always in mind -- Maintain backward compatibility when doing changes to configuration forms, panel options and query editors -- Preserve query model schema unless migration handler is added -- Follow official Grafana plugin documentation (see the links in previous sections) -- Use idiomatic React + TypeScript -- Use secureJsonData to store credentials and secrets -- Use jsonData to store general user configuration inputs that are not secrets -- Use Grafana plugin SDK HTTP client in the backend -- Use `debug` or `error` level for logging +- Keep layouts responsive (use `width`/`height`). Components might render on mobile devices +- Use **`@grafana/plugin-e2e`** for E2E tests and **always use versioned selectors** to interact with the Grafana UI + +**Backend:** +- Use Grafana plugin SDK HTTP client (not the upstream Golang HTTP client) - Cache and reuse backend connections to external services -- if you need to modify a webpack configuration, prettier, eslint or other tool you can follow the guide on extend default configurations https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations.md -- Use default tools when possible: use the build tools provided by the grafana go sdk in Magefile.go over custom build commands, use webpack and only extend the configuration when necessary over of trying to recreate frontend build tools. -- Any modifications to `plugin.json` require a restart of the Grafana server. This is a hard requirement. Remind the user of restarting the Grafana server after doing changes to `plugin.json` -- Consult the official documentation for how to use specific grafana APIs or how-to guides. See the links in previous sections. +- Use `debug` or `error` level for logging (avoid `info` level) +- Backend code must not access the file system + +**Data & Configuration:** +- Use secureJsonData to store credentials and secrets; use jsonData for non-sensitive configuration (never store sensitive information in jsonData) +- Maintain backward compatibility when changing configuration forms, panel options, and query editors +- Preserve query model schema unless a migration handler is added + +**Build & Tools:** +- Use webpack and only extend configuration when necessary — to extend webpack, prettier, eslint or other tools, follow the guide: https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations.md +- Use mage and Magefile.go for backend builds — the Grafana plugin Go SDK provides these build methods, use them instead of custom build commands + +**General:** +- Keep dependencies to a minimum. Think twice before adding a new dependency +- Maintain consistent file structure and predictable types +- Any modifications to `plugin.json` require a restart of the Grafana server. Remind the user of this after making changes to `plugin.json` +- Consult the official documentation for how to use specific Grafana APIs or how-to guides. See the links in previous sections. ## Boundaries & Don'ts list: - Do not change plugin ID or plugin type in `plugin.json` - Do not modify anything inside the `.config` folder. the `.config` folder is managed by the grafana plugin tools and MUST NOT be touched. -- Do not Use the local file system - Do not Use environment variables outside of unit tests -- Do not Execute arbitrary code in the backend +- Do not Execute arbitrary code in the backend or write code that allows arbitrary code execution - Do not Log sensitive data -- Do not Use upstream Golang HTTP client in the backend -- Do not Use `info` level for logging -- Do not store sensitive information in jsonData +- Do not use `eval` or `new Function` for code execution in the frontend ## Remember When you need to reference Grafana plugin documentation, fetch it directly from grafana.com using your web fetch tool, MCP server, or `curl -s`. +