tutorial-checker

name	tutorial-checker
description	Check Ankaios tutorials by executing safe documented shell steps and validating expected outputs. Use this when asked to "check tutorials on main" or to verify local tutorial files. Use when this capability is needed.
metadata	{"author":"eclipse-ankaios"}

Tutorial Checker Skill

Use this skill to validate tutorials by directly following tutorial steps as the agent (not by delegating logic to a large checker script).

Trigger behavior

• If the user asks "check tutorials on main" (or equivalent), use main docs as default without asking for source.
• If the user asks to check local tutorials, ask for the tutorial name (for example events for tutorial-events.md).

Tutorial discovery

• Main tutorials:
  • Load https://eclipse-ankaios.github.io/ankaios/main/usage/installation/.
  • Discover all links containing /usage/tutorial- at runtime.
• Local tutorials:
  • Discover files matching /workspaces/ankaios/doc/docs/usage/tutorial-*.md at runtime.
  • If user requested local mode without a name, ask for the name.

Temporary workspace (required)

• If you need to create tutorial-generated files in the repository workspace, use a dedicated folder under target (for example target/tutorial-check-outputs) and clean it up at the end.
• Create all required files and intermediate files inside the dedicated folder
• Run file-dependent commands from that temp directory (or use absolute temp paths) so no accidental repo files are produced.
• At the end, report the temp directory used and whether cleanup was performed.

Execution process (agent-driven)

For each selected tutorial:

1. Parse markdown and extract shell code blocks.
2. Split multiline shell blocks into executable commands (respect line continuations using \).
3. Run reach step one by one.
4. For each command:
   • Show progress before execution (Tutorial X/Y - Step A/B: <command>).
   • Classify step as execute, transform-and-execute, skip-manual, or skip-unsafe.
   • Systemd is not available inside the devcontainer, however if you use ankaios-start script that does not accept a startup manifest, just use ankaios-start and start on the manifest content dependent Ankaios agents additionally and apply the startup manifest of the tutorial with a simple ank apply instead. Classify the step as transform-and-execute and report the transformation in the final report.
   • Execute safe commands in terminal and capture stdout/stderr + exit code.
   • If a waiting time is required before the next command, don't combine it with the next command as this may affect allowed command detection and execution.
5. Validate expectations:
   • If surrounding text states "should print" and a following text block exists, compare output to expected snippets.
   • Mark step as failed if command fails or expected snippets are missing.
   • Include a warning in the final report as this may indicate a problem with the tutorial or environment.
6. Validate human understandability:
   • Review the tutorial text around each step and mark understandable or unclear.
   • Flag unclear items such as missing prerequisites, unexplained placeholders, ambiguous wording, missing expected result, or required manual context not stated.

Command details

• The following commands are in the PATH:
  • ank, ank-agent, ankaios-start, ankaios-clean, podman, systemctl
• If the checking is running in a container, systemctl commands for starting Ankaios shall be supplemented with ankaios-start and ank-agent. In case systemdctl was not tested, the user must be informed in the final report.
• Disallow chained commands (for example cmd1; cmd2, cmd1 && cmd2, cmd1 || cmd2).
• Transform streaming commands to non-blocking equivalents and execute the transformed command:
  • ank logs -f <workload> or ank logs --follow <workload> -> ank logs --tail 10 <workload>
  • mosquitto_sub ... -> bounded receive mode, e.g. add -C <count> and -W <seconds> so command exits automatically.
  • Report both original and transformed command in step output.
• When server server IP substitution is required (for example containing <SERVER_IP>) use http://localhost:25551 and assume all execution is local.

Web form simulation (curl)

Some tutorials instruct the user to open a browser and interact with a web UI (e.g., enter a speed value). The agent can automate this with curl, but only under strict conditions:

Activation (user confirms via chat UI)

• When the agent encounters a web UI step, it executes the curl command in the terminal like any other command.
• The VS Code chat UI will show the command to the user for approval before execution — the user accepts or rejects it directly in the UI.
• No special flags or keywords are needed.

Scope restrictions (mandatory)

All of the following must be true before the agent issues any curl command:

1. Localhost only — target must be 127.0.0.1 or localhost. Any other host is forbidden.
2. Port from tutorial — the port number must appear in the tutorial text itself (e.g., http://127.0.0.1:5000). Never guess or scan for ports.
3. Workload must be running — the workload serving the web UI must have been started by the agent during this tutorial run and confirmed as Running(Ok).
4. Form discovery — before POSTing, fetch the page with curl -s <url> to extract the HTML form action and field names. Never invent field names.
5. No external requests — curl must never target external URLs, APIs, or services outside the tutorial's locally running workloads.

Execution flow

When a tutorial step says something like "open browser at <url>" or "use the web UI to enter a value":

1. Fetch the page HTML: curl -s <url>
2. Parse the <form> element to determine: method, action path, and input field name attributes.
3. Submit a reasonable test value: curl -s -X POST <url><action> -d "<field>=<value>"
4. Verify the response contains a success indicator (e.g., confirmation text in HTML).
5. If a consumer workload should receive the value, check its logs to confirm end-to-end delivery.
6. Classify the step as transform-and-execute and report both the original instruction and the curl commands used.

Reporting

In the final report, list all curl commands executed under a separate "Web form simulation" subsection, including:

• the original tutorial instruction
• the curl discovery and submission commands
• the response summary
• whether end-to-end verification passed

Live run feedback

• While running, continuously provide concise status updates:
  • current tutorial
  • current step
  • pass/fail/skip decision
  • short reason for skips/failures

Final report format

After all selected tutorials:

1. Per tutorial: passed, failed, skipped counts.
2. For each failure include:
   • exact command
   • output (or output tail if long)
   • expected snippets (if any)
   • likely cause / what may have gone wrong
3. Human-understandability summary per tutorial:
   • only list unclear steps with their surrounding text and reason for being unclear
   • give a brief overall assessment of the tutorial's clarity and usability based on the number and severity of unclear steps
4. End with: ask whether to try fixing detected problems.

---

Source: eclipse-ankaios/ankaios — distributed by TomeVault.