> For the complete documentation index, see [llms.txt](https://docs.instruqt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.instruqt.com/ai-capabilities/building-with-ai.md).

# Building with AI

## Instruqt Track Builder

Instruqt Track Builder is a plugin for Claude Code that takes you from idea to fully generated Instruqt track. Company research, product research, planning, and challenge content included. Rather than starting from a blank page, you work through a set of purpose-built commands that guide you through the entire process, one stage at a time.

{% hint style="warning" %}
AI-generated content should always be reviewed before publishing. The plugin produces a strong starting point but scripts, assignments, and infrastructure config may need manual corrections. Always test your track end to end before sharing it with learners.
{% endhint %}

***

### Installation and Setup

#### Required

* [**Claude Code**](https://claude.ai/code) — the plugin runs inside Claude Code.
  * Linux and macOS work natively.
  * Windows works through [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).
* [**Instruqt CLI**](/reference/cli.md) — required to validate, test, and push tracks.

Without the Instruqt CLI, the plugin still runs structural checks. You cannot run end-to-end platform validation or publish from your machine.

#### Recommended

* [**GitHub CLI**](https://cli.github.com/) — used to download the plugin during installation. Falls back to `curl` or `wget` if not installed.
* [**shellcheck**](https://github.com/koalaman/shellcheck) — improves lifecycle script linting.

### Install the plugin

{% stepper %}
{% step %}

### Add the marketplace

```bash
/plugin marketplace add instruqt/ai-plugins
```

{% endstep %}

{% step %}

### Install the plugin

```bash
/plugin install track@ai-plugin
```

{% endstep %}

{% step %}

### Reload plugins

```bash
/reload-plugins
```

{% endstep %}
{% endstepper %}

***

## How it works

The plugin uses four stages:

1. [**Stage 0: Research**](#stage-0-research-your-company-and-product) — build reusable company and product context.
2. [**Stage 1: Plan**](#stage-1-plan) — define audience, goals, and challenge flow.
3. [**Stage 2: Generate**](#stage-2-generate) — create assignments, scripts, and sandbox config.
4. [**Testing and review**](#testing-and-review) — validate, test, debug, and publish.

You can rerun any stage later. This helps when a product changes or a single challenge needs work.

***

### Stage 0: Research your company and product

Do this once and it pays dividends across every track you build. Run this once per company or product set. It improves terminology, tone, and technical accuracy.

The better the context your tracks build from, the fewer hallucinated features and workflows you get later.

{% hint style="warning" %}
This stage can take 10 minutes or more. Large sites take longer.
{% endhint %}

#### Research your company

```bash
/track:research-company <url>
```

Example:

```bash
/track:research-company https://norncorp.com
```

This produces:

* a company profile
* a writing style guide

#### Research a product

```bash
/track:research-product <product-name>
```

Example:

```bash
/track:research-product Mimir
```

{% hint style="success" %}
Use product docs, developer portals, or product pages when possible. They produce better results than generic marketing homepages.
{% endhint %}

<details>

<summary>Can you skip Stage 0?</summary>

You can skip this stage and move straight to planning. Without upfront research, the plugin fills in gaps as it goes. Results tend to be less consistent and you may find yourself doing more back-and-forth to get tone and terminology right. If you're building more than one track, doing this once upfront saves time and tokens overall.

</details>

## Stage 1: Plan

Planning defines your scope before content is generated. A good plan reduces rework later.

{% hint style="success" %}
Spend more time here than feels necessary. Good planning improves every later stage.
{% endhint %}

#### Plan the track

```bash
/track:plan-track <description>
```

Example:

```bash
/track:plan-track A hands-on intro to Mimir secrets management for platform engineers
```

Describe the track in plain language. Claude asks follow-up questions and drafts a plan.

Review the output carefully. Fix audience level, learning goals, and challenge structure before moving on.

#### Review the track plan

```bash
/track:review-track-plan
```

Use this to catch issues like:

* vague audience definition
* objectives that do not map to challenges
* challenge flow that feels too broad or too narrow

#### Plan each challenge

```bash
/track:plan-challenge <challenge-slug>
```

Run this for each challenge in order. Each challenge builds on the previous one.

This stage defines:

* assignment outline
* tab layout
* infrastructure changes
* lifecycle scripts

You can also ask Claude to plan all challenges in sequence, or manually prompt the planning of each challenge.

#### Review a challenge plan

```bash
/track:review-challenge-plan <challenge-slug>
```

Use this to catch:

* unrealistic time estimates
* missing check logic
* incomplete environment setup

## Stage 2: Generate

Generation turns plans into working content. That includes assignments, tab config, sandbox resources, and lifecycle scripts.

#### Generate challenges

Generate one challenge at a time:

```bash
/track:generate-challenge <challenge-slug>
```

This keeps the context focused. It also makes testing and debugging easier.

{% hint style="info" %}
Generating one challenge at a time is slower upfront. It usually saves time overall because issues are easier to isolate.
{% endhint %}

After each challenge, choose one of these next steps:

* **Test automatically** — runs `instruqt track test`
* **Test manually** — you play through it yourself
* **Skip testing** — continue to the next challenge
* **AI review** — runs `/track:review-challenge`

#### Generate all remaining challenges

You can also ask Claude to generate all challenges. This is faster. It also makes it easier to miss early issues.

```bash
/track:generate-all-challenges
```

{% hint style="danger" %}
Secrets are not generated. If your track needs credentials or tokens, the plugin inserts placeholders. You must add the real values in [Secrets](/sandboxes/runtime/secrets.md) before publishing.
{% endhint %}

#### To play your track - Push to Instruqt

Push the track from your local files:

```bash
instruqt track push <team>/<track-slug>
```

If you belong to multiple teams, prefix the slug with the team name.

For track management details, see [Create tracks](/tracks/manage/create-tracks.md).

## Testing and review

By the time generation finishes, most structural issues should already be caught. Use the steps below to confirm the full track works end to end.

{% stepper %}
{% step %}

### Validate

```bash
instruqt track validate
```

Run this as a final whole-track check.

The plugin also runs this during generation when the CLI is available.
{% endstep %}

{% step %}

### Test the full track

```bash
instruqt track test
```

This simulates a learner from start to finish. For each challenge it runs the setup script, checks that the check script fails before the learner has done anything, runs the solve script to complete the task, then checks again expecting success.

To keep the sandbox running after the test:

```bash
instruqt track test --keep-running
```

For more on testing, see [Test tracks](/tracks/manage/test-a-track.md).
{% endstep %}

{% step %}

### Run an AI review

```bash
/track:review-track
```

This checks challenge flow, script quality, and brand consistency.
{% endstep %}

{% step %}

### Play through it manually

Test the track like a learner would.

Read each assignment. Follow the written steps. Avoid shortcuts or prior knowledge.

If a step feels unclear to you, it will feel unclear to learners too.
{% endstep %}
{% endstepper %}

#### Debugging

When something fails, start with [Track logs](/tracks/manage/viewing-logs.md).

You can access logs in two ways:

* **Web UI** — open the track, go to **Statistics**, then select **Logs**
* **CLI** — run `instruqt track logs <track-slug>`

Filter by time with:

```bash
instruqt track logs <track-slug> --since 6h
```

{% hint style="info" %}
To find a sandbox ID, run `echo $_SANDBOX_ID` inside the sandbox. Then use `--participant-id` to filter logs to that instance.
{% endhint %}

Paste failing log output into Claude when you need help debugging. Logs give the model enough context to explain what failed and suggest a fix.

For more detail, see [Track logs](/tracks/manage/viewing-logs.md).

## Collaborate with your team

Keep shared context and handoff docs in one place. This makes outputs more consistent across authors.

#### Share research across your team

Research files are plain files. Store them in a shared repository so everyone builds from the same company and product context.

Agree on a few basics early:

* where the repository lives
* who owns profile updates
* how product changes are reviewed

Research files are saved to `~/.instruqt/` by default. To store them elsewhere, set `INSTRUQT_DATA_DIR` in your shell config:

```bash
export INSTRUQT_DATA_DIR=/path/to/your/shared/folder
```

Add this to `~/.zshrc` or `~/.bashrc` on Mac or Linux, or your WSL2 shell config on Windows. Then reload your shell or open a new terminal window.

The folder structure is:

* Company profiles: `~/.instruqt/companies/<slug>/`
* Product profiles: `~/.instruqt/products/<company-slug>/<product-slug>/`

#### Generate a maintainer README

A maintainer README makes the track easier to review, update, and hand off.

Once your track is built, generate a README:

```bash
/track:generate-readme
```

Use it to document:

* sandbox architecture
* host and tab layout
* challenge map

## Tips and best practices

{% hint style="info" %}
Type `/track:` in Claude Code to browse all available commands without leaving the chat.
{% endhint %}

{% hint style="info" %}
**Choose your model based on quality and budget.** Sonnet works well for research and planning. For generation, Opus produces the best results but costs more. Model selection is up to you and your Claude account limits.
{% endhint %}

{% hint style="info" %}
Run `/clear` before each new stage. This keeps stale context from leaking into the next task.
{% endhint %}

{% hint style="info" %}
Treat each stage as a conversation. Ask follow-up questions, request revisions, and challenge weak output.
{% endhint %}

{% hint style="success" %}
Upfront research usually lowers total token usage. The plugin spends less time inferring your context later.
{% endhint %}

{% hint style="warning" %}
If your track needs secrets, add them manually before final testing and publishing.
{% endhint %}

{% hint style="warning" %}
You can skip Company and Product research and start planning straight away. The plugin will do its best without company or product context, but output quality and consistency can be lower.
{% endhint %}

## Command reference

Commands are slash prompts you type directly into Claude Code to trigger the plugin.

| Command                                  | Description                                                     | Prerequisites                    |
| ---------------------------------------- | --------------------------------------------------------------- | -------------------------------- |
| `/track:research-company <url>`          | Build a company profile and style guide from a website          | None                             |
| `/track:research-product <product-name>` | Research a product in depth                                     | None                             |
| `/track:plan-track <description>`        | Define track scope, audience, objectives, and challenge outline | None                             |
| `/track:review-track-plan`               | Score the track plan against quality rubrics                    | Track plan                       |
| `/track:plan-challenge <slug>`           | Create a detailed plan for one challenge                        | Track plan                       |
| `/track:review-challenge-plan <slug>`    | Score a challenge plan against quality rubrics                  | Challenge plan                   |
| `/track:generate-challenge <slug>`       | Generate one challenge with content and scripts                 | Challenge plan                   |
| `/track:review-challenge <slug>`         | Score one generated challenge                                   | Generated challenge              |
| `/track:generate-all-challenges`         | Generate all remaining challenges in sequence                   | Track plan and challenge plans   |
| `/track:generate-readme`                 | Produce a maintainer-facing README                              | At least one generated challenge |
| `/track:review-track`                    | Score the full generated track                                  | Generated track                  |

### Related pages

<table data-view="cards"><thead><tr><th>Title</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td>Instruqt CLI</td><td><a href="/spaces/-MGJDYBXyftBAZb1Wq0e/pages/-MGJP-eP_wb6i-7wOrtk">/spaces/-MGJDYBXyftBAZb1Wq0e/pages/-MGJP-eP_wb6i-7wOrtk</a></td></tr><tr><td>Test tracks</td><td><a href="/spaces/-MGJDYBXyftBAZb1Wq0e/pages/SBqBB0OZDlFwkgbZPBwP">/spaces/-MGJDYBXyftBAZb1Wq0e/pages/SBqBB0OZDlFwkgbZPBwP</a></td></tr><tr><td>Track logs</td><td><a href="/spaces/-MGJDYBXyftBAZb1Wq0e/pages/-MXhmdD2NFK8jINrqeHi">/spaces/-MGJDYBXyftBAZb1Wq0e/pages/-MXhmdD2NFK8jINrqeHi</a></td></tr><tr><td>Secrets</td><td><a href="/spaces/-MGJDYBXyftBAZb1Wq0e/pages/rQBZTpLJ5KZgDl2HhL7Z">/spaces/-MGJDYBXyftBAZb1Wq0e/pages/rQBZTpLJ5KZgDl2HhL7Z</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/ai-capabilities/building-with-ai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.