palkan/action_policy/tutorial-lesson-config

Name: tutorial-lesson-config
Author: palkan

Trust tier 3

community

By palkan
Coding
palkan/action_policy
tutorial/.claude/skills/tutorial-lesson-config/SKILL.md
Updated 24 Sep 2026
Version 1.0.01 version recorded

Source check pending

Checking that the SKILL.md file is still in the repository.

Use this skill whenever configuring lesson frontmatter or checking inheritance rules. Trigger on: 'frontmatter', 'prepareCommands', 'mainCommand', 'editor config', 'terminal config', 'preview config', 'configuration inheritance', 'focus file', 'i18n', 'allowEdits', 'previews', 'autoReload', 'scope', 'defaults', 'what inherits', 'does X inherit', 'invalid combination', 'constraint', or any YAML frontmatter question — even without mentioning configuration. Authoritative reference for all frontmatter options, inheritance rules, defaults, and invalid-combination constraints with Rails-specific patterns. Do NOT guess frontmatter without this skill. Do NOT use for content hierarchy (use tutorial-content-structure) or file organization (use rails-file-management).

Install

npx vskill@latest install palkan/action_policy/tutorial-lesson-config

SKILL.md

Tutorial Lesson Configuration

Complete reference for configuring lessons, with Rails-specific defaults and patterns.

Configuration Cascade

Configuration inherits downward: Tutorial > Part > Chapter > Lesson. Set shared defaults at the tutorial level; override per-lesson as needed.

meta.md (type: tutorial)     ← base defaults for all lessons
  meta.md (type: part)       ← overrides for this part's lessons
    meta.md (type: chapter)  ← overrides for this chapter's lessons
      content.md (type: lesson) ← final per-lesson overrides

Rails convention: Set these once in the tutorial root meta.md:

yaml

prepareCommands:
  - ['npm install', 'Preparing Ruby runtime']
terminalBlockingPrepareCommandsCount: 1
previews: false
filesystem:
  watch: ['/*.json', '/workspace/**/*']
terminal:
  open: true
  panels:
    - type: terminal
      id: 'cmds'
      title: 'Command Line'
      allowRedirects: true
    - ['output', 'Setup Logs']

Then override only what changes per-lesson (e.g., enable previews: [3000] for lessons with a running server).

Inheritance Rules

Properties That Inherit (via cascade)

These properties are resolved through the cascade (Tutorial → Part → Chapter → Lesson). The most specific (lesson-level) value wins. For plain objects, child and parent are deep-merged; for arrays and primitives, the child replaces the parent entirely.

Property	Merge behavior
`mainCommand`	Replace
`prepareCommands`	Replace (not merge — if a lesson sets this, it completely overrides the parent)
`terminalBlockingPrepareCommandsCount`	Replace
`previews`	Replace
`autoReload`	Replace
`template`	Replace
`terminal`	Deep-merge if both are objects; replace if either is a primitive (`true`/`false`)
`editor`	Deep-merge if both are objects; replace if either is a primitive
`focus`	Replace
`i18n`	Deep-merge (lesson keys override parent keys; unset keys fall through)
`meta`	Deep-merge
`editPageLink`	Replace
`openInStackBlitz`	Replace
`downloadAsZip`	Replace
`filesystem`	Deep-merge

Properties That Do NOT Inherit

These are per-lesson only and must be set on each lesson that needs them:

Property	Why no inheritance
`custom` (including `custom.shell.workdir`)	Not in the cascade — set it on every lesson
`scope`	Lesson-specific file tree filter
`hideRoot`	Lesson-specific file tree option

Critical: custom.shell.workdir must be set on every lesson that needs a custom terminal working directory. It will NOT be inherited from a part or tutorial meta.md.

Critical: When a lesson overrides prepareCommands, it replaces the entire array from the parent. If the tutorial root sets prepareCommands: [['npm install', 'Preparing Ruby runtime']] and a lesson needs to add db:prepare, the lesson must include both commands:

yaml

# WRONG — npm install is lost
prepareCommands:
  - ['node scripts/rails.js db:prepare', 'Prepare database']
 
# CORRECT — include all commands
prepareCommands:
  - ['npm install', 'Preparing Ruby runtime']
  - ['node scripts/rails.js db:prepare', 'Prepare database']

Editor Configuration

Show/Hide Editor

yaml

editor: false           # Hide editor entirely (terminal-only lessons)
editor: true            # Show editor (default)

File Tree Options

yaml

editor:
  fileTree: false                      # Hide file tree, show only editor tabs
  fileTree:
    allowEdits: true                   # Allow creating files/folders anywhere
    allowEdits: "/workspace/**"        # Allow edits matching glob
    allowEdits:                        # Multiple glob patterns
      - "/workspace/app/**"
      - "/workspace/config/**"

Focus File

Auto-open a specific file in the editor when the lesson loads:

yaml

focus: /workspace/app/controllers/products_controller.rb

Path must be absolute from the WebContainer root. For Rails apps, this is typically /workspace/<app-name>/....

File Tree Scope and Root

yaml

scope: /workspace/store        # Only show files under this path in the tree
hideRoot: true                 # Hide the "/" root node (default: true)

scope is useful to avoid exposing infrastructure files (bin/, lib/, scripts/) to tutorial users.

Terminal Configuration

Basic

yaml

terminal: false     # Hide terminal entirely
terminal: true      # Show with defaults

Panel Configuration

yaml

terminal:
  open: true              # Open terminal panel by default
  activePanel: 0          # Which tab is active (0-indexed)
  panels:
    - type: terminal      # Interactive terminal
      id: 'cmds'          # Persistent session ID (survives lesson navigation)
      title: 'Command Line'
      allowRedirects: true
      allowCommands:       # Restrict allowed commands (optional)
        - rails
        - ruby
        - node
    - type: output         # Read-only output panel (max 1 per lesson)
      title: 'Setup Logs'

Shorthand panel syntax:

yaml

panels:
  - terminal                    # Interactive terminal, default title
  - output                     # Read-only output, default title
  - [terminal, "Rails Console"] # Interactive with custom title
  - ['output', 'Setup Logs']   # Read-only with custom title

Persistent sessions: Use id to keep terminal state across lesson navigation. The user's terminal history and running processes persist when they switch between lessons that share the same id.

Output Panel

Only one output panel is allowed per lesson. It captures output from prepareCommands and mainCommand.

Preview Configuration

Basic

yaml

previews: false          # No preview panel
previews: true           # Auto-detect preview
previews: [3000]         # Show preview for port 3000

Advanced

yaml

previews:
  - 3000                                          # Port only
  - "3000/products"                               # Port with pathname
  - [3000, "Rails App"]                           # Port with title
  - [3000, "Rails App", "/products"]              # Port, title, pathname
  - { port: 3000, title: "App", pathname: "/products" }  # Object form

Auto-Reload

yaml

autoReload: true    # Force preview reload when navigating to this lesson

Useful for lessons where the preview state may be stale from a previous lesson.

Commands

prepareCommands

Commands that run before the lesson is interactive. Shown as progress steps to the user:

yaml

prepareCommands:
  - 'npm install'                                              # String form
  - ['npm install', 'Preparing Ruby runtime']                  # [command, label]
  - { command: 'node scripts/rails.js db:prepare', title: 'Preparing database' }  # Object form

Rails patterns:

yaml

# Basic — just install WASM runtime (set at tutorial level)
prepareCommands:
  - ['npm install', 'Preparing Ruby runtime']
 
# With database — for lessons that need migrations/seeds
prepareCommands:
  - ['npm install', 'Preparing Ruby runtime']
  - ['node scripts/rails.js db:prepare', 'Prepare development database']

terminalBlockingPrepareCommandsCount

How many prepareCommands must finish before the terminal becomes interactive:

yaml

terminalBlockingPrepareCommandsCount: 1   # Block until npm install finishes

mainCommand

The primary long-running process (usually the dev server). Runs after all prepareCommands complete:

yaml

mainCommand: ['node scripts/rails.js server', 'Starting Rails server']

Important: Use node scripts/rails.js server — not rails server — because the Rails CLI dispatches through Node.js wrapper scripts in this WASM environment.

Filesystem Watching

yaml

filesystem:
  watch: true                            # Watch all files
  watch: ['/*.json', '/workspace/**/*']  # Watch specific patterns

For Rails tutorials, watch /workspace/**/* so the preview reflects file changes in the Rails app.

Defaults

When a property is not set at any level in the cascade, these defaults apply:

Property	Default	Effect
`template`	`'default'`	Uses the base Rails WASM runtime template
`editor`	(unset)	Editor is shown with default file tree
`terminal`	(unset)	One read-only "Output" panel, initially closed
`previews`	`true`	Auto-detect: shows preview for the first port that opens
`autoReload`	(unset)	Preview is not force-reloaded on navigation
`focus`	(unset)	No file auto-opened in editor
`openInStackBlitz`	`true`	"Open in StackBlitz" button shown
`downloadAsZip`	`false`	Download button hidden
`mainCommand`	(unset)	No long-running process started
`prepareCommands`	(unset)	No preparation steps
`filesystem.watch`	(unset)	No file watching
`scope`	(unset)	All files visible in tree
`hideRoot`	`true`	Root "/" node hidden in file tree
`custom`	(unset)	No custom fields

Constraints

Invalid or problematic frontmatter combinations that cause silent failures:

Combination	Problem	Fix
`focus: /path/...` with `editor: false`	Focus is silently ignored — no editor to open the file in	Remove `focus` or set `editor: true`
`previews: [3000]` without `mainCommand`	Nothing starts a server on port 3000 — preview stays blank	Add `mainCommand: ['node scripts/rails.js server', 'Starting Rails server']`
`mainCommand: 'rails server'`	Bare `rails` won't work — commands must go through the Node.js wrapper	Use `mainCommand: ['node scripts/rails.js server', 'Starting Rails server']`
Lesson `prepareCommands` without `npm install`	WASM runtime never loads — everything else fails	Always include `['npm install', 'Preparing Ruby runtime']` as the first prepare command
`previews` without `prepareCommands` including `npm install`	Runtime not loaded, server can't start	Add `prepareCommands` with `npm install` (or inherit from tutorial root)
`terminal: false` with `mainCommand` set	Terminal hidden but `mainCommand` still runs — output is invisible	Either show terminal or remove `mainCommand`
`custom.shell.workdir` set only in `meta.md`	`custom` doesn't inherit — terminal won't cd in lessons	Set `custom.shell.workdir` on each lesson's `content.md`

Other Options

Custom Shell Working Directory

yaml

custom:
  shell:
    workdir: "/workspace/store"

Sets the terminal's working directory by sending cd /home/tutorial<workdir> && clear to the first terminal panel on lesson load. The path is constructed by prepending /home/tutorial to the workdir value, so workdir: "/workspace/store" sends cd /home/tutorial/workspace/store && clear. This is a Rails-tutorial-specific feature (implemented via ShellConfigurator in this template, not upstream TutorialKit). Essential for Rails tutorials where the app lives at /workspace/<app-name>.

Does not inherit. Must be set on every lesson that needs it (see Inheritance Rules above).

Template Selection

yaml

template: default          # Use the default (base Rails) template
template: rails-app        # Use a template with pre-generated Rails app

Templates live in src/templates/. Each lesson can also override via _files/.tk-config.json.

Download and StackBlitz

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 95 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingtutorial/.claude/skills/tutorial-lesson-config/SKILL.md

Popularity

Repository stars: 1,562
Repository forks: 89
7-day trend score: 37

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/palkan/action_policy/tutorial-lesson-config/badge)](https://verified-skill.com/skills/palkan/action_policy/tutorial-lesson-config)

Something wrong with this skill or its page? Tell us.