AI Agent Workflow

With Shaper, data visualization, dashboards and reports are just standard SQL, and LLMs are great at generating SQL.

Install the Shaper Agent Skills so Claude Code, Codex, Gemini CLI, Cursor or your agent of choice knows everything it needs to create Shaper dashboards.

Setup

1. Make sure you have Shaper installed since the skills use CLI commands.

2. You need a Taleshape Cloud account or have Shaper running locally.

3. Create a new folder where you like to manage your Shaper dashboards and tasks.

4. Before using your agent, run shaper login and shaper pull manually in the terminal once. This will initialize a new shaper.json file for you and pull any existing dashboards you might already have. Follow the instructions, enter your Shaper URL and confirm the authentication in your browser when prompted.

   Note

   The CLI only allows the agent to create dashboards and validate them. The agent cannot query any data. The LLM never sees your actual data.

5. Install the Shaper skills for your agent of choice. You can install them automatically using the Claude Code Plugin, the npx skills CLI, or manually. See the skills repo for details.

   Claude Code Plugin

   Inside a Claude Code session:

   # 1. Register the marketplace (run once)
   /plugin marketplace add taleshape-com/shaper-skills
   
   # 2. Install all skills:
   /plugin install shaper@shaper-skills
   
   # Or install only a single skill:
   /plugin install shaper-dashboard-development@shaper-skills

   Or from your terminal:

   claude plugin marketplace add taleshape-com/shaper-skills
   claude plugin install shaper@shaper-skills

   To automatically enable skills for everyone working in a repository, configure .claude/settings.json:

   {
     "extraKnownMarketplaces": {
       "shaper-skills": {
         "source": {
           "source": "github",
           "repo": "taleshape-com/shaper-skills"
         }
       }
     },
     "enabledPlugins": {
       "shaper@shaper-skills": true
     }
   }

   npx skills

   Use the open agent skills CLI (skills.sh) to automatically discover and install Shaper skills into your project:

   # Install all skills into your project (auto-detects installed agents)
   npx skills add taleshape-com/shaper-skills
   
   # Or install only a single skill (e.g. dashboard development)
   npx skills add taleshape-com/shaper-skills --skill shaper-dashboard-development
   
   # Or install globally across all projects
   npx skills add taleshape-com/shaper-skills -g
   
   # Or target specific agents (e.g. Cursor, Codex)
   npx skills add taleshape-com/shaper-skills -a cursor -a codex

   Supported agents include Cursor, Codex CLI, Gemini CLI, Antigravity, OpenCode, Claude Code, Windsurf, GitHub Copilot, and Qwen Code.

   Manual

   If you prefer to install without package managers, copy the skills directly into your repository:

   mkdir -p .agents/skills
   git clone git@github.com:taleshape-com/shaper-skills.git /tmp/shaper-skills
   cp -r /tmp/shaper-skills/shaper-* .agents/skills/
   rm -rf /tmp/shaper-skills

   Agent	Target Location
   Claude Code	.claude/skills/
   Cursor, Codex CLI, Gemini CLI, Antigravity, OpenCode	.agents/skills/
   Qwen Code	.qwen/skills/

Available Skills

The repository organizes the development workflow into three skills:

• shaper-dashboard-development (Main skill): Guides the agent through exploring schemas and existing dashboards, authoring files named <Dashboard Name>.dashboard.sql organized by folders, automatically generating IDs via the CLI, validating SQL queries, previewing dashboards in the browser, and following Git-based CI/CD deployment rules.
• shaper-setup (Sub-skill): Ensures the environment is compatible, verifies the Shaper CLI is installed, configures shaper.json with instance URL and local directory settings, authenticates via shaper login, safely pulls dashboards, and configures .gitignore to prevent authentication tokens from being committed.
• shaper-task-development (Sub-skill): Guides the agent through creating and managing startup (init) and scheduled tasks (*.task.sql), installing community extensions (e.g. http_client), attaching to external databases (Postgres and DuckLake) via persistent secrets, creating commented views, and validating tasks manually via the Shaper UI.

Usage

The AI agent uses skills automatically when appropriate so you can simply prompt it something like:

Create a new dashboard that gives an overview over all data in the system

The skills explain how to write Shaper-specific SQL and how to use the shaper CLI.

CLI commands the agent uses:

Command	Description
shaper --version	Checks if the Shaper CLI is installed and gets its version
shaper login	Prompts the user to open a URL and confirm authentication in the browser
shaper pull --yes	Pulls existing dashboards and tasks from the production system
shaper schema	Prints the current database schema to explore available tables and columns
shaper ids	Scans all dashboard and task SQL files and injects unique -- shaperid:<UUID> header comments
shaper validate file.dashboard.sql	Executes the dashboard SQL locally to check for errors
shaper preview file.dashboard.sql	Compiles the dashboard and opens a live preview in the browser

To deploy dashboards to production, see the Deploy section in the Git Workflow docs.

If you are familiar with the Git Workflow, when using an agent you do not need to keep shaper dev running in the background. The agent already manages ids and previews for you.

Configuring the Database Schema

The agent can generate better dashboards if it knows more about the system and the data it is working with.

You can manually run shaper schema to see the database schema the agent is working with.

Make sure you attach the necessary databases and consider creating views to simplify the queries the agent has to write.

Comments on tables, views and columns are a great tool to include more information about the system.

If there are databases/schemas/tables/views the agent should not know about, you can exclude them from the schema by adding a "schemaIgnore": ["mydb", "otherdb.myschema", "db3.schema2.mytable"] field to your shaper.json config file.

The agent also reads your existing dashboards and tasks to learn about common patterns you are already using.