# 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](https://github.com/taleshape-com/shaper-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](https://taleshape.com/shaper/docs/installing-shaper) since the skills use CLI commands.
2. You need a [Taleshape Cloud](https://taleshape.com/signup) 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](https://github.com/taleshape-com/shaper-skills/#install) for details.
   For Claude Code:
   ```sh
   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](https://taleshape.com/shaper/docs/git-workflow/#deploying-dashboards) section in the Git Workflow docs.

_If you are familiar with the [Git Workflow](https://taleshape.com/shaper/docs/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](https://taleshape.com/shaper/docs/connecting-to-data-sources/#connecting-to-databases) the necessary databases and consider [creating views](https://taleshape.com/shaper/docs/tasks-and-scheduling/#startup-tasks) 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.