Building with AI
Use AI tools in your workflow and in the product to create better training content, faster.
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.
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.
Installation and Setup
Required
Claude Code — the plugin runs inside Claude Code.
Linux and macOS work natively.
Windows works through WSL2.
Instruqt CLI — 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 — used to download the plugin during installation. Falls back to
curlorwgetif not installed.shellcheck — improves lifecycle script linting.
Install the plugin
In your terminal start a Claude session
How it works
The plugin uses four stages:
Stage 0: Research — build reusable company and product context.
Stage 1: Plan — define audience, goals, and challenge flow.
Stage 2: Generate — create assignments, scripts, and sandbox config.
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.
This stage can take 10 minutes or more. Large sites take longer.
Research your company
Example:
This produces:
a company profile
a writing style guide
Research a product
Example:
Use product docs, developer portals, or product pages when possible. They produce better results than generic marketing homepages.
Can you skip Stage 0?
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.
Stage 1: Plan
Planning defines your scope before content is generated. A good plan reduces rework later.
Spend more time here than feels necessary. Good planning improves every later stage.
Plan the track
Example:
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
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
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
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:
This keeps the context focused. It also makes testing and debugging easier.
Generating one challenge at a time is slower upfront. It usually saves time overall because issues are easier to isolate.
After each challenge, choose one of these next steps:
Test automatically — runs
instruqt track testTest 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.
Secrets are not generated. If your track needs credentials or tokens, the plugin inserts placeholders. You must add the real values in Secrets before publishing.
To play your track - Push to Instruqt
Push the track from your local files:
If you belong to multiple teams, prefix the slug with the team name.
For track management details, see Create tracks.
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.
Test the full track
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:
For more on testing, see Test tracks.
Debugging
When something fails, start with Track logs.
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:
To find a sandbox ID, run echo $_SANDBOX_ID inside the sandbox. Then use --participant-id to filter logs to that instance.
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.
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:
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:
Use it to document:
sandbox architecture
host and tab layout
challenge map
Tips and best practices
Type /track: in Claude Code to browse all available commands without leaving the chat.
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.
Run /clear before each new stage. This keeps stale context from leaking into the next task.
Treat each stage as a conversation. Ask follow-up questions, request revisions, and challenge weak output.
Upfront research usually lowers total token usage. The plugin spends less time inferring your context later.
If your track needs secrets, add them manually before final testing and publishing.
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.
Command reference
Commands are slash prompts you type directly into Claude Code to trigger the plugin.
/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
Last updated
Was this helpful?