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 mange your Shaper dashboards and tasks.
4. Before using your agent, run 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. Now setup the shaper skills for your agent of choice. See the skills repo for details. For Claude Code:

   mkdir -p .claude/skills
   git clone git@github.com:taleshape-com/shaper-skills.git /tmp/shaper-skills
   mv /tmp/shaper-skills/* .claude/skills/

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 schema	Shows the database schema
shaper ids	Generate IDs for all dashboards and tasks
shaper validate file.dashboard.sql	Run dashboard and check for errors
shaper preview file.dashboard.sql	Generate a preview link for a dashboard

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.