---
title: Swimlane Agent Skills
slug: turbine-user-guide/swimlane-agent-skills
createdAt: 2026-11-19T15:10:55.631Z
---

Use Swimlane Agent Skills to let an AI coding agent build, validate, back up, and troubleshoot Turbine content in a development tenant.

:::hint{type="warning"}
**Warning:** Swimlane Agent Skills is an early release. It calls Turbine private, unversioned APIs that can change between Turbine releases without notice. Use it only in development or other non-production tenants. You are responsible for reviewing, testing, and approving everything the agent creates or changes.
:::

## What Swimlane Agent Skills Does

Swimlane Agent Skills is a set of skills, tools, and commands for AI coding agents. The agent reads the skills and then works against your tenant through the Turbine API.

| **Item**             | **Description**                                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Skills**           | Skills that cover playbooks, components, connectors, JSONata, schema mapping, dashboards, validation, snapshots, and run troubleshooting. |
| **Tools**            | A tenant snapshot and restore tool, and a local widget preview tool.                                                                      |
| **Commands**         | `/swimlane:setup` checks your setup. `/swimlane:validate` checks content offline. Both are for Claude Code.                               |
| **Supported agents** | Claude Code, Cursor, Codex, Copilot, and Gemini CLI.                                                                                      |

Swimlane Agent Skills helps you build faster. It does not replace knowing Turbine, reviewing what the agent created, or testing in the Turbine UI. Experienced builders can expect it to complete most of a new build, with a person owning the final review and the decision to promote.

## How a Build Works

Each skill that writes to a tenant asks you to confirm the tenant, and whether it is a production tenant, before it writes. The skills tell the agent to run snapshots and restores. You can also ask for them at any time.

| **Step**         | **What happens**                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Protect**   | The build skills tell the agent to save a snapshot of existing playbooks, components, and AI agents before its first write. Ask for a snapshot at the start of a session to be sure. See [Protect and Restore Content with Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#protect-and-restore-content-with-swimlane-agent-sk). |
| **2. Build**     | The agent creates playbooks, components, connectors, JSONata, and schema mappings.                                                                                                                                                                                                                                                                                        |
| **3. Validate**  | The agent checks content before and after every write.                                                                                                                                                                                                                                                                                                                    |
| **4. Roll Back** | If a change goes wrong, ask the agent to restore a playbook, component, or AI agent from the snapshot. A restore covers playbook source only.                                                                                                                                                                                                                             |
| **5. Operate**   | The agent diagnoses failed or stalled runs and finds root causes.                                                                                                                                                                                                                                                                                                         |

## Choose Your Path

| **Goal**                                            | **Where to go**                                                                                                                                                                 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Decide whether Swimlane Agent Skills fits your team | [Before You Begin with Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#before-you-begin-with-swimlane-agent-skills)                   |
| Install Swimlane Agent Skills in your agent         | [Install Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#install-swimlane-agent-skills)                                               |
| Point Swimlane Agent Skills at a development tenant | [Connect Swimlane Agent Skills to a Tenant](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#connect-swimlane-agent-skills-to-a-tenant)                       |
| Run your first build                                | [Build Your First Solution with Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#build-your-first-solution-with-swimlane-agent-skil)   |
| Back up, validate, and restore content              | [Protect and Restore Content with Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#protect-and-restore-content-with-swimlane-agent-sk) |
| Find the skill for a task                           | [Swimlane Agent Skills Reference](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#swimlane-agent-skills-reference)                                           |
| Write better prompts and review the result          | [Swimlane Agent Skills Best Practices](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#swimlane-agent-skills-best-practices)                                 |
| Fix a problem                                       | [Troubleshoot Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#troubleshoot-swimlane-agent-skills)                                     |

## Before You Begin with Swimlane Agent Skills

Check that Swimlane Agent Skills fits your team and that your environment is ready before you install it.

### Who Should Use Swimlane Agent Skills

| **Good fit**                                                                                  | **Not a good fit**                                                                    |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| You already build playbooks, applications, assets, and dashboards in Turbine with confidence. | You are new to Turbine and still learning its object model.                           |
| You can tell when a playbook, schema, or widget is wrong and how to fix it.                   | You cannot yet review the content an agent creates.                                   |
| You already use a supported AI coding agent as part of your normal work.                      | You want to change a prebuilt solution such as AI SOC without deep Turbine expertise. |

### Prerequisites

- [ ] A supported AI coding agent: Claude Code, Cursor, Codex, Copilot, or Gemini CLI
- [ ] Python 3.9 or later, for tenant snapshots and restores
- [ ] Node.js, for offline validation and widget preview. Check that it is installed by running `node --version` in a terminal
- [ ] A development or other non-production Turbine tenant
- [ ] A dedicated Turbine user for the agent, and a personal access token for that user
- [ ] The Swimlane Agent Skills zip file from the support portal

If something is missing, see [Install Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#install-swimlane-agent-skills) and [Connect Swimlane Agent Skills to a Tenant](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#connect-swimlane-agent-skills-to-a-tenant).

### Set Up a Dedicated Builder Identity

Do not point the agent at your daily-use account. Permissions are the real control, because prompt instructions alone cannot stop an agent that holds production credentials.

1. Create a Turbine user used only for agent work, for example `ai-builder`.
2. Generate a personal access token for that user only.
3. Grant that user access only to development or other non-production tenants.
4. Assign the minimum role needed to create and update the objects you build. Do not grant broad administrator rights for convenience.

Using a dedicated user makes the audit history show agent changes separately from changes made in the UI.

### Use Development Tenants Only

- Build and iterate only in a development or other non-production tenant.
- Promote to higher environments through your normal change process after a person reviews the content.
- Never place a production token in the agent environment, even for read-only checks.
- If your `.env` file holds more than one tenant, give each a clear name and confirm which tenant the session targets before a large build.

### Choose What to Build

| **Supported**                                                                                            | **Use with caution**                                                           |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| New use cases: playbooks, applications, assets, connectors and HTTP actions, dashboards, and sample data | Large changes to prebuilt solutions such as AI SOC, VRM, CAR, and SOC Solution |
| Changes to content Swimlane Agent Skills created for you in the same project                             | Wide refactors of mature content you did not author                            |

:::hint{type="info"}
**Tip:** When in doubt, recreate the content in a sandbox tenant instead of editing a live solution package.
:::

## Install Swimlane Agent Skills

Install Swimlane Agent Skills so your AI coding agent can load the Swimlane skills.

### Choose Your Install Path

| **Your agent**                        | **Where to go**                                                                                                                                                      |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code                           | [Install in Claude Code](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#install-in-claude-code)                                                  |
| Cursor, Codex, Copilot, or Gemini CLI | [Install in Cursor, Codex, Copilot, or Gemini CLI](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#install-in-cursor-codex-copilot-or-gemini-cli) |
| Another agent that supports skills    | [Install the Skills Only](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#install-the-skills-only)                                                |

### Unpack the Zip File

1. Download the Swimlane Agent Skills zip file from the support portal.
2. Unzip it to a folder you will keep. This topic calls that folder `/path/to/swimlane-agent-skills`.
3. Confirm the hidden `.agents` and `.claude-plugin` folders are present.

:::hint{type="warning"}
**Important:** Keep the hidden folders. The agents need them to find the skills.
:::

### Install in Claude Code

1. In Claude Code, run `/plugin marketplace add /path/to/swimlane-agent-skills`.
2. Run `/plugin install swimlane@swimlane-agent-skills`.
3. Start a new session. The plugin loads the skill index at the start of each session. It makes no network calls and reads no secrets.

The plugin adds the `/swimlane:setup` and `/swimlane:validate` commands.

:::hint{type="warning"}
**Important:** Claude Code reads the plugin from your install folder. Do not move or delete the folder after you install.
:::

### Install in Cursor, Codex, Copilot, or Gemini CLI

1. Open `/path/to/swimlane-agent-skills` as your project in the agent.
2. Start a session. The agent loads skills from `.agents/skills/` and the skill index from `AGENTS.md`.

### Install the Skills Only

1. Open a terminal in the project folder where you want the skills.
2. Run `npx skills add /path/to/swimlane-agent-skills`.
3. Start a session and ask the agent to use the `turbine` skill. This router skill picks the right skill for each request.

The command copies the skills into the `.agents/skills` folder of your current folder. It does not copy the snapshot tool, the Claude Code commands, or `.env.example`. To take snapshots, copy `tools/turbine-archive` and `.env.example` from the unzipped folder into your project, or use the project install above.

:::hint{type="note"}
**Note:** The `npx` command downloads the `skills` package from the npm registry the first time you run it.
:::

### Update to a New Version

1. Download the new zip file.
2. Replace the contents of your install folder with the new files.
3. In Claude Code, run `/plugin marketplace update swimlane-agent-skills`.

The `VERSION` file in the folder shows the Agent Skills version and the Turbine version it targets. Skills can stop working after a Turbine upgrade because Swimlane Agent Skills uses private APIs, so check that file against your tenant version.

## Connect Swimlane Agent Skills to a Tenant

Give Swimlane Agent Skills the details it needs to reach your development tenant, then run the setup check.

### Quick Path to Connect a Tenant

| **Step** | **Action**                                                        |
| -------- | ----------------------------------------------------------------- |
| 1        | Create the personal access token for your dedicated builder user. |
| 2        | Copy `.env.example` to `.env`.                                    |
| 3        | Enter the four tenant values in `.env`.                           |
| 4        | Run the setup check.                                              |
| 5        | Install the snapshot tool requirements.                           |

### Create the Personal Access Token

1. Sign in to the development tenant as your dedicated builder user.
2. Create a personal access token. See [Customize Your User Profile](/customize-your-user-profile) for the steps.
3. Copy the token and store it securely. Turbine does not show it again.

### Configure the .env File

1. In your install folder, run `cp .env.example .env`.
2. Open `.env` and set these values:

| **Setting**             | **Value**                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `BASE_URL`              | The address of your development tenant, for example `https://YOUR-REGION.swimlane.app` |
| `SWIMLANE_ACCESS_TOKEN` | The personal access token you created                                                  |
| `SWIMLANE_ACCOUNT_ID`   | The account ID of your tenant                                                          |
| `SWIMLANE_TENANT_ID`    | The tenant ID of your development tenant                                               |

Find the account ID and tenant ID in the address bar when you are signed in to the tenant. The address has the form `https://YOUR-REGION.swimlane.app/account/<account ID>/tenant/<tenant ID>/home`.

:::hint{type="warning"}
**Warning:** Never commit `.env` or share it. If a token appears in a chat log, transcript, or agent history, rotate it.
:::

The `.env.example` file also holds an optional setting for the local widget preview (`VITE_SWIMLANE_LIT_PROXY_TARGET`). Set it to your tenant address if you preview widgets.

### Run the Setup Check

1. In Claude Code, run `/swimlane:setup`. In another agent, ask it to check the Swimlane Agent Skills setup.
2. Review the checklist the agent returns. It confirms that `.env` exists, that Python and Node.js are installed, that one read-only call to the tenant succeeds, and that the snapshot tool runs.
3. If a step fails, fix it and run the check again.

| **Result**                  | **Meaning**                          |
| --------------------------- | ------------------------------------ |
| HTTP 401 or 403             | The token or the tenant ID is wrong. |
| Python or Node.js not found | Install the missing runtime.         |

### Install the Snapshot Tool Requirements

1. Open a terminal in `tools/turbine-archive` in your install folder, or ask the agent to do this for you.
2. Run `pip install -r requirements.txt`.

The snapshot tool needs this before the first write to your tenant.

## Build Your First Solution with Swimlane Agent Skills

Run a small, scoped build in a development tenant and verify the result in Turbine.

### Quick Path to Your First Build

| **Step** | **Action**                                   |
| -------- | -------------------------------------------- |
| 1        | Choose a small, well-defined use case.       |
| 2        | Write a scoped prompt that names the tenant. |
| 3        | Confirm the tenant and take a snapshot.      |
| 4        | Answer the agent questions while it builds.  |
| 5        | Validate, then verify in the Turbine UI.     |

### Prerequisites for Your First Build

- [ ] Swimlane Agent Skills is installed and the setup check passes
- [ ] You are using a strong, high-reasoning model. See [Swimlane Agent Skills Best Practices](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#swimlane-agent-skills-best-practices)
- [ ] The target tenant is a development tenant

If something is missing, see [Connect Swimlane Agent Skills to a Tenant](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#connect-swimlane-agent-skills-to-a-tenant).

### Write a Scoped Prompt

Start narrow. If you have a list of use cases, build and validate the first one before you add the rest.

A good prompt names the tenant, lists the objects you want, and invites questions. For example:

:::BlockQuote
Read the attached controls spreadsheet. Focus only on the first row. Build end-to-end automation in my **dev** tenant `DEV-ACME` using the token in `.env`. Create the playbooks, required assets, an application to store results, and a dashboard with pass and fail metrics. Ask clarifying questions before making irreversible choices. When finished, list every object you created by name and ID.
:::

| **Weaker prompt**                                    | **Problem**                                                     |
| ---------------------------------------------------- | --------------------------------------------------------------- |
| "Automate all our security controls in Turbine."     | No tenant, no scope, and no success criteria                    |
| "Update AI SOC so it also does phishing validation." | Edits a prebuilt solution, which has a high risk of breaking it |
| "Build this and push it to production."              | Breaks the development-only rule                                |
| "Make it work." after a failure                      | Gives the agent no object names or error text, so it guesses    |

### Run the Build

1. Start a session in your agent and enter your prompt.
2. Confirm the tenant name when the agent asks. Tell it whether the tenant is production. It must not be.
3. Let the agent take a snapshot before its first write. Check that it reports the snapshot folder path. Snapshots are saved under `local/snapshots` in your install folder, and they can be large for a tenant with many objects.
4. Answer the questions the agent asks about triggers, flow splits, vendors, and success criteria.
5. Wait for the agent to report the objects it created.

:::hint{type="note"}
**Note:** Expect a conversation. A full build can take a long time and several decisions from you.
:::

### Verify the Result

The Turbine API can accept content that the Turbine UI cannot open or run. Check the build yourself.

1. In Claude Code, run `/swimlane:validate <file or folder>` with the path to the content, or ask the agent to validate it. Fix any blocking finding.
2. Read the object inventory the agent reported: playbooks, applications, dashboards, and assets.
3. In Turbine, open each playbook and confirm it loads.
4. Run or test each playbook where it is safe to do so, and check the job result. A new run can take up to a minute to appear in the run list.
5. Check application fields and dashboard widgets.
6. Confirm that assets and credentials are wired, or list the steps that remain.

A clean validation does not prove the playbook works. Always check a real run.

### Fix Problems

- Ask the agent to diagnose from run results, and to propose the smallest fix.
- Use small corrective prompts, for example "add vertical scrolling to the controls table in the dashboard widget you created." Do not ask for a full rebuild.
- If the agent loops, stop it, fix the smallest broken object in the UI, then give the agent a precise prompt.
- To undo a bad change to a playbook or component, ask the agent to restore it from the snapshot.

## Protect and Restore Content with Swimlane Agent Skills

Take a snapshot before the agent writes to your tenant, check content with the offline validator, and restore a playbook, component, or AI agent if a change goes wrong.

### Quick Path to Protect Content

| **Step** | **Action**                                                                                                                                    |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 1        | [Take a snapshot](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#take-a-snapshot) before the first write.                 |
| 2        | [Validate content](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#validate-content) before and after every write.         |
| 3        | [Restore a flow](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#restore-a-flow) from the snapshot if a change goes wrong. |

You can ask the agent to do each of these, and it runs the commands below. You can also run them yourself.

### Prerequisites for Snapshots and Restores

- [ ] The setup check passes. See [Connect Swimlane Agent Skills to a Tenant](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#connect-swimlane-agent-skills-to-a-tenant)
- [ ] Python requirements are installed in `tools/turbine-archive`
- [ ] Node.js is installed, for validation

### Take a Snapshot

A snapshot is a copy of your tenant content saved on your computer. It is read-only: it does not change the tenant.

1. Open a terminal in `tools/turbine-archive` in your install folder, or ask the agent to do this for you.
2. Run `python3 -m turbine_archive snapshot`.
3. Wait for the summary of object counts. A tenant with many objects can take longer and produce tens of megabytes.
4. Open `local/snapshots/<host>/snap-<timestamp>/` in your install folder. Confirm that `dump.json` and `manifest.json` exist.

The snapshot folder also holds the flow definitions as YAML files and the JSONata and Python code from your flows. Secret values are redacted.

:::hint{type="warning"}
**Warning:** A snapshot holds your tenant content. Keep it on your computer. Do not commit it or share it.
:::

To snapshot a single item, run `python3 -m turbine_archive backup --key component:<id>`. This creates a redacted backup for reading. It cannot be restored directly.

### How the Agent Uses Snapshots

The build skills tell the agent to run a snapshot before its first write. The agent runs the command, reports the snapshot folder path, and waits for you to confirm the tenant before it writes. A snapshot is not guaranteed, so check these limits.

| **Limit**                          | **What it means**                                                                                                                        |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **The agent can skip it**          | If the agent skips the step, ignores the skill, or you use a skill that does not mention snapshots, a write can happen with no snapshot. |
| **One snapshot per build**         | The agent snapshots before the first write, not before every write. A long session with many edits has one snapshot from the start.      |
| **Snapshots go stale**             | A snapshot from last week does not cover changes made since.                                                                             |
| **Snapshots stay on one computer** | Snapshots are saved under `local/snapshots/` on the computer that ran the tool. Nothing syncs or cleans them up.                         |

To make this stricter:

- Ask the agent for a snapshot at the start of every session, for example "snapshot the development tenant first and show me manifest.json."
- Schedule snapshots outside the agent, with cron or a CI job. The tool does not need an agent session. It needs only the credentials in your `.env` file.

### Validate Content

The validator checks content on your computer. It does not contact the tenant. In Claude Code, you can run `/swimlane:validate <file or folder>` with the path to the content instead of the steps below. In another agent, ask it to validate the content.

1. In your install folder, run `node .agents/skills/validating-turbine-content/validate.mjs --kind playbook --file <document.json>`. Use `--kind schema`, `asset`, or `sensor` for other content.
2. Read the JSON report. Each finding has a level, a code, a path, and a message.
3. Check the exit code.

| **Exit code** | **Meaning**                                                           |
| ------------- | --------------------------------------------------------------------- |
| `0`           | No blocking findings.                                                 |
| `2`           | Blocking findings. Fix them before you write.                         |
| `1`           | The command could not run, or no check applies to that document type. |

To check an `.ssp` bundle, run `node .agents/skills/validating-turbine-content/validate.mjs --ssp <bundle.ssp>`.

:::hint{type="note"}
**Note:** A clean result does not prove the content works. The validator does not check document structure, because the tenant does that when you write. Always check a real run.
:::

### Restore a Flow

A restore puts a flow's earlier definition back on the tenant. Try it on a development tenant first.

1. In `tools/turbine-archive`, list what the snapshot holds: `python3 -m turbine_archive unpack --from <snapshot folder> --list`.
2. Unpack the item you want: `python3 -m turbine_archive unpack --from <snapshot folder> --key component:<id>`. This writes two files under `local/repairs/<host>/`.
3. Run a dry run on the file that starts with `flow-backup__` and does not end in `.put.json`: `python3 -m turbine_archive restore --from <flow-backup file>`.
4. Read the plan. It shows `"applied": false` and the change it would make.
5. Confirm the tenant name and ID, and that it is not a production tenant.
6. Apply the restore: `python3 -m turbine_archive restore --from <flow-backup file> --confirm-tenant-id <tenant ID>`.
7. Check the result. It shows `"applied": true` and a `verify` line that says the live playbook matches the backup.
8. Open the flow in Turbine, or run it, and confirm it is back to its earlier state.

If the tenant ID you type does not match the connected tenant, the restore stops without writing. Before it writes, the restore saves a copy of the current flow under `local/repairs/<host>/` in a file that starts with `pre-restore-`. It keeps the flow's current enabled or disabled state.

### What a Restore Covers

| **Restored**                                                        | **Not restored**                                                                                 |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Playbook source for components, AI agents, playbooks, and workflows | Applications, schemas, connectors, assets, secrets, records, widgets, audit history, and sensors |

The snapshot also holds applications, widget code, and canvas notes. You can read these, but a restore does not write them back. Rebuild them by hand, or ask the agent to use the `cloning-turbine-tenants` skill. The agent does not restore on its own. Ask for a restore when you need one.

## Swimlane Agent Skills Reference

Find the skill that fits your task. Each skill is a set of instructions your AI coding agent loads when your request matches.

### Choose Your Skill Path

| **Goal**                                               | **Where to go**                                                                                                             |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Build playbooks, components, connectors, or dashboards | [Build Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#build-skills)                             |
| Check content or fix a rejected write                  | [Validate and Fix Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#validate-and-fix-skills)       |
| Back up, restore, or copy content                      | [Protect and Move Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#protect-and-move-skills)       |
| Diagnose a failed run or look up documentation         | [Operate and Look Up Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#operate-and-look-up-skills) |

### Pick a Skill

You do not need to name a skill. Describe the task and the agent picks one. If you are unsure, ask for the `turbine` skill. This router skill matches your request to the right skill and hands off to it.

| **Prompt**                           | **Skill the agent uses**    |
| ------------------------------------ | --------------------------- |
| "Which Turbine skill should I use?"  | `turbine`                   |
| "Why did this playbook fail?"        | `triaging-turbine-runs`     |
| "Snapshot the tenant before I edit." | `archiving-turbine-tenants` |

### Build Skills

| **Skill**                       | **Use it to**                                                                                                                                                        | **Not for**                                                         |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `building-turbine-playbooks`    | Build, deploy, and debug playbooks, components, and assets through the API. Includes a worked example that brings Microsoft Graph Security alerts into AI SOC cases. | AI agents. Use `building-turbine-ai-agents`.                        |
| `creating-turbine-components`   | Create a Solution Builder component in three writes, run it, and check its output.                                                                                   | AI agents.                                                          |
| `building-turbine-ai-agents`    | Build and debug Turbine AI Agent components, for example an agent that makes no tool calls.                                                                          | Plain components.                                                   |
| `building-turbine-connectors`   | Write connector YAML by hand: the manifest, assets, and actions.                                                                                                     | Building, signing, or pushing. Use `publishing-turbine-connectors`. |
| `publishing-turbine-connectors` | Validate, build, sign, and push a connector with `tsdk`.                                                                                                             | Writing connector YAML.                                             |
| `mapping-turbine-schema`        | Map and validate data against the Turbine schema.                                                                                                                    | JSONata syntax.                                                     |
| `writing-turbine-jsonata`       | Write and review Turbine and portable JSONata, including `$arrayPluckBy` and `$inputs`.                                                                              | Extracting JSONata from YAML.                                       |
| `annotating-turbine-canvases`   | Write canvas notes in HTML that survives editing, for example when formatting vanishes after an edit.                                                                | Backups.                                                            |
| `designing-turbine-dashboards`  | Turn a dashboard request into Turbine dashboard, report, and chart objects.                                                                                          | Widget code preview.                                                |
| `previewing-turbine-widgets`    | Preview and check Lit widgets offline on your machine.                                                                                                               | Dashboard design.                                                   |
| `integrating-turbine-with-jsm`  | Connect Turbine to Jira Service Management, for example when a transition returns an error 400.                                                                      | General playbook work.                                              |

### Validate and Fix Skills

| **Skill**                             | **Use it to**                                                                                    | **Not for**            |
| ------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------- |
| `validating-turbine-content`          | Check schemas, playbooks, assets, sensors, and `.ssp` bundles offline, before and after a write. | Decoding write errors. |
| `fixing-turbine-playbook-validation`  | Turn a `PlaybookValidationException` into the exact fix.                                         | New playbook source.   |
| `extracting-turbine-playbook-jsonata` | Pull JSONata out of a playbook YAML export into a digest. This skill is experimental.            | Writing JSONata.       |

### Protect and Move Skills

| **Skill**                   | **Use it to**                                                                                                                                                                                                                                  | **Not for**               |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `archiving-turbine-tenants` | Take a snapshot of a tenant and restore one flow from it. See [Protect and Restore Content with Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#protect-and-restore-content-with-swimlane-agent-sk). | Copies to another tenant. |
| `cloning-turbine-tenants`   | Copy content and records between tenants when an `.ssp` import is blocked.                                                                                                                                                                     | Rollback.                 |

### Operate and Look Up Skills

| **Skill**                       | **Use it to**                                                                         | **Not for**                                  |
| ------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------- |
| `triaging-turbine-runs`         | Diagnose failed or stalled runs and report cause and fix. This skill is experimental. | Deeper root cause.                           |
| `analyzing-turbine-root-causes` | Find the root cause of a failure that keeps coming back. This skill is experimental.  | Single-run triage.                           |
| `searching-turbine-docs`        | Look up and cite official Turbine documentation.                                      | Calling the tenant API.                      |
| `setting-turbine-user-agent`    | Tag requests the agent sends to the tenant API so audit logs show agent activity.     | Other hosts, or content built into a tenant. |

### Experimental Skills

Three skills are marked experimental because part of what they rely on is not included in this release. They still load and run, with the reduced results described below.

| **Skill**                             | **What is missing**                                                                                                                                             |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `triaging-turbine-runs`               | A severity rubric, platform limits, and an outdated-connector report. The agent marks severity as unrated and tells you to confirm limits in the documentation. |
| `analyzing-turbine-root-causes`       | The full workflows for each analysis method. The agent uses the method picker and core rules in the skill and says so in its write-up.                          |
| `extracting-turbine-playbook-jsonata` | The extraction script. The agent stops and offers a manual method.                                                                                              |

## Swimlane Agent Skills Best Practices

Follow these practices to reduce risk and get reliable results. They lower the risk but do not remove it, because AI agents do not always follow instructions.

### Choose Your Practice

| **Goal**                         | **Where to go**                                                                                                                                                                                                       |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get better output from the agent | [Work with the Agent](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#work-with-the-agent) and [Choose a Model](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#choose-a-model) |
| Protect credentials              | [Protect Credentials](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#protect-credentials)                                                                                                         |
| Decide when a build is finished  | [Know When a Build Is Done](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#know-when-a-build-is-done)                                                                                             |
| Recover from a bad result        | [Recover When Things Go Wrong](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#recover-when-things-go-wrong)                                                                                       |

### Work with the Agent

1. Start narrow. Build and validate the first flow before you add more.
2. Answer the clarifying questions. They prevent wrong vendors, triggers, and flow splits.
3. Expect a conversation, not a single prompt.
4. Read the object inventory the agent reports after each run.
5. Verify in Turbine. Open the playbooks, run them where safe, and check fields, widgets, and assets.
6. Fix with small corrective prompts or in the UI, then verify again.
7. Do not skip testing. Run real integrations in the tenant when the use case depends on them.

For prompt examples, see [Build Your First Solution with Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#build-your-first-solution-with-swimlane-agent-skil).

### Choose a Model

| **Task**                                              | **Model guidance**                                                                                                                                                              |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| First-pass builds with many objects and long sessions | Use the strongest generally available, high-reasoning model in your agent, such as the current top-tier Anthropic Opus-class model. Do not use a mid-tier or automatic default. |
| Small, bounded follow-up changes                      | A mid-tier model is acceptable once the structure exists.                                                                                                                       |

Weaker models tend to invent invalid constructs, bloat large graphs, or fail silently. The Turbine APIs can still accept that content until you open or run it in the UI.

:::hint{type="note"}
**Note:** Model names change often, so treat any named model as accurate for a point in time.
:::

If an agent creates content that will not open or run, do not keep iterating with a weak model. Use a strong model with a small corrective prompt, or repair the content in the UI.

### Protect Credentials

- Never hard-code tokens, API keys, or passwords into playbooks, skills, or committed files.
- Store runtime secrets in Turbine assets and sensitive schema fields.
- Do not connect the agent to a password manager or broad secret store unless your security team has approved it.
- Rotate any credential that may appear in chat logs, transcripts, or local agent history.
- Leave the `Swimlane Agent Skills` User-Agent header in place. It lets you tell agent activity apart from UI activity in audit logs.

### Know When a Build Is Done

A build is done when all of these are true, not when the agent says it finished:

- The objects exist in the intended development tenant, with clear names and canvas notes where expected.
- You inspected the critical paths in the Turbine UI.
- Test or sample results show the behavior you asked for, or you deliberately deferred the gaps.
- Assets and authentication are configured, or the remaining steps are listed.
- You are comfortable promoting the content through your normal release process.

### Recover When Things Go Wrong

- Watch for partial builds: an application without a working playbook, orphaned sensors, or missing assets. Clean these up before you add more automation.
- If a tenant is in a bad state, pause agent writes, export or snapshot if you can, recover by hand, and resume only when it is stable.
- To undo a playbook or component change, restore it from the snapshot. A restore covers playbook source only. It does not restore applications, connectors, assets, records, or widgets.

### Quick Checklist

| **When**         | **Check**                                                                                                                                                                                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Before a session | - A dedicated builder user and token are configured.<br />- The target tenant is a development tenant.<br />- The scope is a new build or a tightly bounded change.<br />- A strong model is selected for multi-object builds.<br />- Secrets are stored only in the local `.env` file or in tenant assets. |
| After a session  | - You reviewed the created and changed objects in Turbine.<br />- You ran appropriate tests.<br />- You noted the remaining manual steps, such as authentication, vendor setup, and promotion.<br />- No production credentials are in the agent environment or in commits.                                 |

## Troubleshoot Swimlane Agent Skills

Find the symptom, then follow the fix.

### Quick Reference

| **Issue**                                              | **Category**  | **Quick fix**                                                             |
| ------------------------------------------------------ | ------------- | ------------------------------------------------------------------------- |
| Setup check returns HTTP 401 or 403                    | Setup         | Check the token and the tenant ID in `.env`.                              |
| Agent does not find the skills                         | Install       | Confirm the hidden `.agents` and `.claude-plugin` folders are present.    |
| Skills stop working after a Turbine upgrade            | Compatibility | Compare the `VERSION` file with your tenant version.                      |
| Content saved but will not open or run                 | Build         | Fix with a strong model and a small prompt, or repair in the UI.          |
| A write is rejected with `PlaybookValidationException` | Build         | Ask the agent to use `fixing-turbine-playbook-validation`.                |
| Component name already exists                          | Build         | Choose a new unique name.                                                 |
| New run does not appear in the run list                | Run           | Wait, then check that the playbook is enabled.                            |
| Restore dry run says the backup has no playbook source | Restore       | Use the `flow-backup__` file, not the `.put.json` file.                   |
| Restore refuses a file that contains `<redacted>`      | Restore       | Restore from a snapshot taken before the change.                          |
| A skill says a tool or script is not shipped           | Skills        | Expected for experimental skills. Use the manual method the skill offers. |

### Setup Check Returns 401 or 403

**Symptoms:** `/swimlane:setup` stops at the tenant call and reports HTTP 401 or 403.

**Cause:** The personal access token or the tenant ID is wrong.

**Resolution:**

1. Open `.env` and compare `SWIMLANE_TENANT_ID` and `SWIMLANE_ACCOUNT_ID` with the tenant address.
2. Create a new personal access token if the token has expired or was revoked.
3. Confirm the dedicated builder user has access to the tenant.
4. Run the setup check again.

If you call the API yourself, send the token in the `Private-Token` header. An `Authorization: Bearer` header returns 401.

**Prevention:** Use a dedicated builder user and keep its token in `.env`.

### Agent Does Not Find the Skills

**Symptoms:** The agent does not use the Swimlane skills, or the commands are missing.

**Cause:** The `.agents` or `.claude-plugin` folder is missing. These folders are hidden, and some copy tools skip them.

**Resolution:**

1. Show hidden files in your install folder and confirm both folders exist.
2. If either is missing, unzip the Swimlane Agent Skills zip file again.
3. Reinstall Swimlane Agent Skills. See [Install Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#install-swimlane-agent-skills).

### Skills Stop Working After a Turbine Upgrade

**Symptoms:** Calls that worked before now fail after your tenant is upgraded.

**Cause:** Swimlane Agent Skills uses Turbine private, unversioned APIs. They can change between Turbine releases.

**Resolution:**

1. Open the `VERSION` file and note the Turbine version your Agent Skills version targets.
2. Check the support portal for a newer version.
3. Update Swimlane Agent Skills if a newer version exists.

### Content Saved but Will Not Open or Run

**Symptoms:** The agent reports success, but a playbook will not open in Turbine, or a run fails.

**Cause:** The API can accept content that the Turbine UI cannot render or run.

**Resolution:**

1. Run `/swimlane:validate <file or folder>` on the content and fix any blocking finding.
2. Give the agent the object name and the error text from the failed run.
3. Ask for the smallest fix. Use a strong, high-reasoning model.
4. If the agent loops, stop it, fix the smallest broken object in the UI, and give it a precise prompt.
5. If the change broke an existing flow, restore it. See [Protect and Restore Content with Swimlane Agent Skills](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#protect-and-restore-content-with-swimlane-agent-sk).

**Prevention:** Check every build in the UI and with a real run.

### A Write Is Rejected with PlaybookValidationException

**Symptoms:** A save or validate call fails with `PlaybookValidationException`.

**Resolution:**

1. Ask the agent to use `fixing-turbine-playbook-validation`.
2. Read the last line of the error first. The validator lists every branch it tried, and the real cause is usually last.
3. If the error only says `Error validating` with a name, ask the agent to bisect: remove half of the content, save, and narrow down. The message carries no other detail.

### Component Name Already Exists

**Symptoms:** Naming a component fails with HTTP 400 and error code 25007.

**Cause:** Another component in the tenant already has that name.

**Resolution:**

1. Choose a new unique name.
2. Do not delete the existing component and create it again. A new component gets a new ID and breaks anything that referenced the old one.

### New Run Does Not Appear in the Run List

**Symptoms:** You started a run, but the run list shows nothing.

**Cause:** The run list can lag behind the start of a run, sometimes by a minute or more. A disabled playbook accepts a run request but creates no run.

**Resolution:**

1. Wait a minute and check the run list again.
2. Confirm the playbook is enabled.
3. If you changed the enabled state for a test, set it back afterward.

### Restore Dry Run Says the Backup Has No Playbook Source

**Symptoms:** `restore` reports "Backup has no playbookSrc."

**Cause:** You pointed the command at the `.put.json` file. Unpacking writes two files, and only the one that starts with `flow-backup__` and does not end in `.put.json` can be restored.

**Resolution:**

1. Open `local/repairs/<host>/`.
2. Run `restore --from` with the `flow-backup__` file that does not end in `.put.json`.

### Restore Refuses a File That Contains Redacted Values

**Symptoms:** The restore stops and mentions `<redacted>`.

**Cause:** Secret values were masked when the file was written. The restore will not write masked values to a tenant.

**Resolution:** Unpack from a snapshot that was taken before the change, and restore from that file.

### A Skill Says a Tool or Script Is Not Shipped

**Symptoms:** The agent stops and says part of a skill is not included in this release.

**Cause:** Three skills are experimental. See [Swimlane Agent Skills Reference](https://docs.swimlane.com/turbine-user-guide/swimlane-agent-skills#swimlane-agent-skills-reference).

**Resolution:** Use the manual method the agent offers, or continue with the reduced output it describes.
