Swimlane Agent Skills
Use Swimlane Agent Skills to let an AI coding agent build, validate, back up, and troubleshoot Turbine content in a development tenant.
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ο»Ώ. |
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 | |
Install Swimlane Agent Skills in your agent | |
Point Swimlane Agent Skills at a development tenant | |
Run your first build | |
Back up, validate, and restore content | |
Find the skill for a task | |
Write better prompts and review the result | |
Fix a problem |
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ο»Ώ and 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.
- Create a Turbine user used only for agent work, for example ai-builder.
- Generate a personal access token for that user only.
- Grant that user access only to development or other non-production tenants.
- 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 |
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 | |
Cursor, Codex, Copilot, or Gemini CLI | |
Another agent that supports skills |
Unpack the Zip File
- Download the Swimlane Agent Skills zip file from the support portal.
- Unzip it to a folder you will keep. This topic calls that folder /path/to/swimlane-agent-skills.
- Confirm the hidden .agents and .claude-plugin folders are present.
Important: Keep the hidden folders. The agents need them to find the skills.
Install in Claude Code
- In Claude Code, run /plugin marketplace add /path/to/swimlane-agent-skills.
- Run /plugin install swimlane@swimlane-agent-skills.
- 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.
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
- Open /path/to/swimlane-agent-skills as your project in the agent.
- Start a session. The agent loads skills from .agents/skills/ and the skill index from AGENTS.md.
Install the Skills Only
- Open a terminal in the project folder where you want the skills.
- Run npx skills add /path/to/swimlane-agent-skills.
- 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.
Note: The npx command downloads the skills package from the npm registry the first time you run it.
Update to a New Version
- Download the new zip file.
- Replace the contents of your install folder with the new files.
- 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
- Sign in to the development tenant as your dedicated builder user.
- Create a personal access token. See Customize Your User Profile for the steps.
- Copy the token and store it securely. Turbine does not show it again.
Configure the .env File
- In your install folder, run cp .env.example .env.
- 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.
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
- In Claude Code, run /swimlane:setup. In another agent, ask it to check the Swimlane Agent Skills setup.
- 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.
- 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
- Open a terminal in tools/turbine-archive in your install folder, or ask the agent to do this for you.
- 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ο»Ώ
The target tenant is a development tenant
If something is missing, see 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:
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
- Start a session in your agent and enter your prompt.
- Confirm the tenant name when the agent asks. Tell it whether the tenant is production. It must not be.
- 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.
- Answer the questions the agent asks about triggers, flow splits, vendors, and success criteria.
- Wait for the agent to report the objects it created.
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.
- 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.
- Read the object inventory the agent reported: playbooks, applications, dashboards, and assets.
- In Turbine, open each playbook and confirm it loads.
- 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.
- Check application fields and dashboard widgets.
- 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ο»Ώ before the first write. |
2 | Validate contentο»Ώ before and after every write. |
3 | 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ο»Ώ
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.
- Open a terminal in tools/turbine-archive in your install folder, or ask the agent to do this for you.
- Run python3 -m turbine_archive snapshot.
- Wait for the summary of object counts. A tenant with many objects can take longer and produce tens of megabytes.
- 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.
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.
- 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.
- Read the JSON report. Each finding has a level, a code, a path, and a message.
- 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>.
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.
- In tools/turbine-archive, list what the snapshot holds: python3 -m turbine_archive unpack --from <snapshot folder> --list.
- Unpack the item you want: python3 -m turbine_archive unpack --from <snapshot folder> --key component:<id>. This writes two files under local/repairs/<host>/.
- 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>.
- Read the plan. It shows "applied": false and the change it would make.
- Confirm the tenant name and ID, and that it is not a production tenant.
- Apply the restore: python3 -m turbine_archive restore --from <flow-backup file> --confirm-tenant-id <tenant ID>.
- Check the result. It shows "applied": true and a verify line that says the live playbook matches the backup.
- 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ο»Ώ |
Check content or fix a rejected write | |
Back up, restore, or copy content | |
Diagnose a failed run or look up documentation |
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ο»Ώ. | 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ο»Ώ and Choose a Modelο»Ώ |
Protect credentials | |
Decide when a build is finished | |
Recover from a bad result |
Work with the Agent
- Start narrow. Build and validate the first flow before you add more.
- Answer the clarifying questions. They prevent wrong vendors, triggers, and flow splits.
- Expect a conversation, not a single prompt.
- Read the object inventory the agent reports after each run.
- Verify in Turbine. Open the playbooks, run them where safe, and check fields, widgets, and assets.
- Fix with small corrective prompts or in the UI, then verify again.
- 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ο»Ώ.
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.
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 |
|
After a session |
|
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:
- Open .env and compare SWIMLANE_TENANT_ID and SWIMLANE_ACCOUNT_ID with the tenant address.
- Create a new personal access token if the token has expired or was revoked.
- Confirm the dedicated builder user has access to the tenant.
- 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:
- Show hidden files in your install folder and confirm both folders exist.
- If either is missing, unzip the Swimlane Agent Skills zip file again.
- Reinstall Swimlane Agent Skills. See 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:
- Open the VERSION file and note the Turbine version your Agent Skills version targets.
- Check the support portal for a newer version.
- 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:
- Run /swimlane:validate <file or folder> on the content and fix any blocking finding.
- Give the agent the object name and the error text from the failed run.
- Ask for the smallest fix. Use a strong, high-reasoning model.
- If the agent loops, stop it, fix the smallest broken object in the UI, and give it a precise prompt.
- If the change broke an existing flow, restore it. See Protect and Restore Content with Swimlane Agent Skillsο»Ώ.
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:
- Ask the agent to use fixing-turbine-playbook-validation.
- Read the last line of the error first. The validator lists every branch it tried, and the real cause is usually last.
- 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:
- Choose a new unique name.
- 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:
- Wait a minute and check the run list again.
- Confirm the playbook is enabled.
- 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:
- Open local/repairs/<host>/.
- 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ο»Ώ.
Resolution: Use the manual method the agent offers, or continue with the reduced output it describes.