Lab Instructions guide learners through hands-on activities inside their lab environment.
The Instructions Editor allows you to create, edit, and manage those instructions using either:
Code (Markdown) mode
Visual mode
You can switch between modes at any time.
Key Features
The Instructions Editor combines flexibility, speed, and control—allowing lab authors to build rich, interactive lab instructions without sacrificing precision. Whether you prefer Markdown or a visual interface, the editor provides the tools you need to create scalable, dynamic learning experiences:
Syntax highlighting for code
Scroll sync between editor and preview
Spellcheck (for visual mode)
Drag-and-drop tokens and activities
Double-click editing for supported structured objects
Embedded Skillable AI tools (if enabled)
Skillable AI
Skillable AI features are optional. If your organization has opted out of Skillable AI, AI capabilities will not appear in the Instructions Editor, including:
The AI option in the ribbon bar
AI Content Assistant in the left action panel
Contact your organization administrator if you have questions about AI availability.
Code Mode vs. Visual Mode
You can build labs using either Markdown (code mode) or a visual editing interface (visual mode). Both modes support the same core functionality, allowing you to choose the workflow that best fits your needs:
Code Mode | Visual Mode |
|---|---|
Code mode is ideal for authors who prefer precise control over structured syntax:
| Visual mode is ideal for authors who prefer a WYSIWYG experience:
|
To switch from code mode (default) to visual mode, select the Visual toggle in the editor’s bottom-left corner.
To make visual mode the default for your editor, open the Settings menu and select Set Visual Editor as Default.
Switching to Visual Mode for the First Time
When you first switch to Visual mode, you’re asked to confirm the change. You’ll see two confirmations:
A dialog asking if you want to proceed.
A review prompt with Approve (to stay in visual mode) or Revert (to return to code mode).
You’ll only need to approve these changes once for each instruction set.
Double-Click Editing
Within the Instructions Editor, you can double-click certain structured objects to open their edit dialog instead of manually editing. This helps to minimize errors and improve editing speed and workflow efficiency for lab authors.
|
|
Note
Unsupported items must be edited manually.
Navigate the Instructions Editor
The Instructions Editor is organized into distinct interface areas that provide access to formatting tools, lab components, and preview controls. These functional sections are designed to support specific parts of the authoring workflow:
Ribbon Bar: Apply general formatting, layout options, paragraph styles, and insert tools (including content elements and AI features, if enabled).
Left Action Panel: Access lab components like AI Content Assistant (if enabled), tokens, activities, variables, and Text Swap. Drag supported components directly into the Visual editor.
Top Menu Bar: Navigate between Editor, Activities, Help, and Settings, and switch or manage Instruction Sets.
Bottom Bar: Toggle between code and visual mode and control Autosave (or manually save changes).
Learner Preview: View a live preview of how instructions appear to learners and update the lab theme as needed.
Use the Ribbon Bar
The ribbon bar along the top of the editor contains general formatting, layout and paragraph, and insertion tools.
Use the general formatting options to format text:
UI Element | Formatting Option | Description |
|---|---|---|
| Standard styles | Apply bold, italic, or |
| Heading | Apply a heading or paragraph style to your text. |
| Blocks | Add pre-formatted quotes, alerts, notes, help, hint, or knowledge text to your instructions. |
| Link | Add a text hyperlink to your instructions. The link dialog supports selecting an icon to display alongside the text and choosing the open method (new window, dialog, or portal. window) |
| Code | Add a code block or inline code to your instructions. |
Use the layout and paragraph options for more formatting flexibility:
UI Element | Formatting Option | Description |
|---|---|---|
| Lists | Apply bulleted, numbered, or task (check) lists to your text. |
| Indents | Increase or decrease the indent in your text. |
| Insert | Insert a page break, section, or horizontal rule. Sections allow you to group a block of content and optionally set conditional visibility based on an associated variable. |
| Table | Insert a table into your instructions. |
Use the insert tools to add resources to your instructions:
UI Element | Formatting Option | Description |
|---|---|---|
| AI | Embed Skillable AI features directly into your lab instructions. From this menu, you can insert:
|
| Type Text | Insert text into a learner’s active lab environment automatically. Three variations of type text are supported:
|
| Input Field | Insert an interactive response area directly into the lab instructions. An input field allows learners to enter responses within the lab instruction panel. Available input types include:
|
| Author Comment | Insert an internal comment within the instructions that isn’t visible to learners. Use author comments to leave editing notes for yourself, provide guidance to co-authors, flag sections for review, or document implementation details. |
| Include Instructions | Insert content from another instruction set into the current lab. Use this option to reuse standardized content across multiple labs, reference shared setup or policy instructions, and maintain consistency without duplicating content. |
| Import from File(s) | Imports content from a file to your current instruction set. Supported file types include: Microsoft Word (.doc or .docx), Markdown (.md), and RTF (.rtf). |
| Upload Media | Insert images, video, and audio files directly into the lab instructions. The dialog supports drag-and-drop file upload, multiple file selection, display options (inline or as a link), and overwriting existing files. |
Skillable AI
For more details on how you can leverage the full Skillable AI suite of tools, check out these articles:
Use the Left Action Panel
The left action panel provides quick access to interactive lab components and AI authoring tools. Select an icon to view and insert the corresponding elements into your instructions.
AI Content Assistant
The Content Assistant helps generate or improve instructional content using prompt-based content generation within the editor. Use it to draft new instructions, refine existing content, reduce manual formatting effort, and maintain consistency across labs.
Specify a topic, select an AI model, choose the response depth (beginner → expert) and format your AI content, all from within the Content Assistant panel.
For more details on how to use this feature, check out our AI Content Assistant documentation.
Menu Options
The wand icon now opens the AI Content Assistant. Tokens are available under the @ icon.
Tokens
Tokens insert dynamic placeholders into your instructions. They automatically resolve at lab launch with environment-specific or personalized values like user-specific information, resource identifiers, and dynamic configuration values.
Drag tokens into the editor or insert them using structured syntax (e.g., @lab.TokenName). Use the search and filter fields to find existing tokens.
Activities
Activities insert interactive or scored elements into lab instructions. Activities may include knowledge checks, scripted validations, automated scoring, or grouped activity sets.
Reference activities using their assigned alias (e.g., @lab.Activity(q1)). Use the search and filter fields to find existing activities, or add new activities as needed.
Variables
Variables define configurable values within a lab. They allow dynamic behavior across lab launches, such as personalization flags, unique identifiers, and SSH keys or credentials.
Use the Variables panel to see existing variables or add new variables.
Text Swap
Text Swap dynamically replaces visible text without modifying the underlying content. Use Text Swap to standardize terminology, adjust learner-facing language, and apply case-sensitive or pattern-based text replacement.
For example, if your base instructions reference Azure Portal, you can use Text Swap to display AWS Management Console for a different audience.
Use the Top Menu Bar
The top menu bar provides access to navigation, configuration, and instruction set management within the Instructions Editor.
Editor
The Editor tab displays the Instructions Editor workspace. Use this tab to return to editing instructions.
Activities
The Activities tab opens the activity manager, where you can create, edit, and manage lab activities. Activities can then be referenced within the instructions using their assigned alias.
Help
The Help tab provides access to Skillable documentation and support resources.
Settings
The Settings (
) tab opens the Editor Settings menu. Available options depend on whether you’re in code mode or visual mode:
Setting | Description | Visual Mode | Code Mode |
|---|---|---|---|
Learner Preview | Displays a preview of the lab instructions next to the code view, which updates in real time as changes are made to the lab instructions. | ✅ | ✅ |
Sync Learner Preview Location | Syncs the position of the code view and position of the lab instructions preview while scrolling in the lab instructions editor. | ✅ | ✅ |
Set Visual Editor as Default | Sets the Visual Editor as the default editor. | ✅ | ✅ |
Spellcheck | Checks spelling as you write instructions, highlighting potential errors and suggesting corrections. | ✅ | |
Code Editor Word Wrap | Allows text to wrap to the next line when it reaches the end of line in the editor pane. | ✅ | |
Code Editor Zoom | Adjusts the zoom level while viewing the editor. | ✅ | |
Track Task Progress | Displays a progress bar at the bottom of the lab instruction window with the total number of tasks the lab user has to complete. When they check a task, the progress bar reflects their progress. | ✅ | ✅ |
Require tasks to be completed in order | Requires lab users to complete tasks in the order they appear in the lab instructions. | ✅ | ✅ |
Auto-Check Previous Tasks | Allows a lab user to select a task in the lab instructions to automatically mark all previous tasks as complete. | ✅ | ✅ |
Instruction Sets
The Instruction Set dropdown allows you to switch between multiple Instruction Sets for the same lab.
Click Manage Instruction Sets to create, edit, or organize additional sets.
Close
Click Close (
) to close out of the Instructions Editor.
Use the Bottom Bar
The bottom bar provides quick access to editor mode controls and save options:
Mode toggle: Switch between visual mode and code mode at any time without losing content.
Autosave: Enabled by default, Autosave saves changes automatically to your current instruction set as you edit. When disabled, you must manually select Save Changes to apply updates.
Save Changes: Disabled by default, use Save Changes to manually save changes when Autosave is turned off.
View Learner Preview
The Learner Preview pane shows how instructions appear to learners. Preview updates in real time as you edit.
To enable or disable learner preview:
Along the top of the editor, select the gear icon to open the Settings menu (
).Toggle Learner Preview on or off and then click anywhere on the screen to close out of the Settings menu.
Summary
The Instructions Editor provides a flexible authoring environment for building hands-on lab instructions. Authors can switch between code mode and visual mode, preview content in real time, and insert interactive elements such as tokens, activities, and AI-powered tools.
By combining structured formatting, reusable instruction sets, and dynamic components, the editor supports both rapid content creation and advanced customization.
Frequently Asked Questions
What happens when I add in Markdown in the visual editor can’t render?
Sometimes there are certain Markdown patterns that users can add to Code mode that Visual mode cannot display properly. In this case, a popup displays indicating that the Visual Editor is currently disabled. No worries, you’re automatically redirected back to Code mode, and Visual mode is disabled to prevent any issues with editing. You will always have an editor that allows you to work effectively.
Can I change my default editor?
If your lab has some advanced or unique patterns that Visual mode can’t render properly, you can change the default editor mode.
You may also prefer to write your lab instructions in Markdown, using Code mode as the default option. To enable Code mode as the default, use the Settings menu to toggle Set Visual Editor as Default off.
To reset to Visual mode, toggle Set Visual Editor as Default on.
What are tokens?
Tokens, also known as Replacement Tokens, are dynamic text placeholders that enhance your lab's interactivity and personalization. By inserting structured text (of the format @lab.TokenName) into instructions or scripts, it will dynamically be replaced in each lab launch with personalized text or interactive components like user-specific names, unique identifiers, questions, or dropdown menus. Tokens empower you to create engaging, personalized, and ever-changing lab experiences, fostering interaction and customization for a more immersive skills journey. For more information about Replacement Tokens, read our Replacement Tokens documentation.
What are activities?
Activities provide ways for users to interact with lab content. Activities also allow authors to assess how well a user is doing in their lab. Activities can consist of interactive questions, automated scripts, or even groups of multiple activities.
You can reference activities in your instructions by using the activity's Alias. For example, if you have a question with the alias "q1", you can reference it in your instructions like this: @lab.Activity(q1). When a learner reaches this point in the instructions, they will see the question you created. For more information about Activities, read our Activities documentation.
What are variables?
Variables empower you to personalize and fine-tune your lab like never before. Think of them as dynamic settings that you control, allowing you to tailor each launch to your exact needs. While some variables could be as simple as 'Personalized: Yes/No,' others might be complex like SSH keys or completely unique identifiers. This customization injects dynamism into your lab, making every instance distinctive and precisely suited to your requirements. For more information about Variables, read our Variables documentation.
What is Text Swap?
Text Swap empowers you to seamlessly change what users see in your lab without altering the actual content. Just like using find/replace in documents, Text Swap allows you to transform visible text elements while keeping the original text unchanged. For instance, you can transform 'Sign in to the environment' to 'Login' for users, while preserving the original wording for backend operations. Whether you need case-sensitive changes, case-insensitive adjustments, or even more intricate transformations using regular expressions (Regex), Text Swap provides a user-friendly solution to enhance the user experience.
Can I double-click any object in the Instructions Editor to edit it?
No. Double-click editing is supported only for specific structured objects. Tokens, variables. author comments, and code blocks must still be edited manually.
If you’re experiencing an issue with a lab, platform feature, or your account, please submit a ticket to Skillable Support. Our Support team can help you troubleshoot errors, resolve access issues, and answer questions specific to your environment.
If you noticed an error or have suggestions for improving this documentation, use the Was this article helpful? section below. Your input helps us keep our documentation accurate and up to date.
Was this article helpful?
Please note that this feedback is for documentation only. Be sure to log in to your Skillable account when leaving feedback so we can respond directly.