Technical Book Lab Design
Core Lens
A technical book lab is not a pile of commands. It is a guided reader transformation with a clear starting state, safe path, visible progress, expected output, and exit criteria. The reader should know what they built, why it works, how to verify it, and what to do when it fails.
Use this skill to design or improve:
- Self-hosting chapters.
- DevOps, infrastructure, programming, data, or security tutorials.
- Worked examples and exercises.
- Lab prerequisites and environment assumptions.
- Checkpoints, expected outputs, and troubleshooting branches.
Reference Routing
| Need |
Read |
| Core lab concepts and terminology |
references/core/knowledge.md |
| Lab design rules |
references/core/rules.md |
| Before/after examples |
references/core/examples.md |
| Lab review checklist |
references/core/checklist.md |
| Step-by-step lab design |
workflows/design-runnable-lab.md |
Workflow
1. Name The Reader Outcome
State what the reader will be able to do, decide, deploy, debug, or explain after the lab.
If the outcome is only "learn about X," sharpen it until there is visible proof of progress.
2. Define The Starting State
List what the reader already has and knows:
- Required concepts.
- Accounts, hardware, software, versions, and operating system.
- Network, domain, DNS, permissions, credentials, or safety constraints.
- Files or repo state.
Move missing prerequisites earlier, compress them, or link them to companion material.
3. Design The Path
Structure the lab as small checkpoints:
- Explain the purpose before each action.
- Give the smallest safe command or change.
- Show expected output or state.
- Add a quick verification.
- Explain the next decision.
4. Add Failure Handling
Technical readers do not only need the happy path.
- List likely errors and what they mean.
- Add rollback or cleanup steps where changes are risky.
- Mark steps that expose services, change permissions, spend money, or affect data.
- Tell readers when to stop and ask for help.
5. Close The Loop
End every lab with:
- Final verification.
- What the reader should understand now.
- What they can safely change next.
- Cleanup, maintenance, or security follow-up.
Output Format
When designing or reviewing a lab, return:
- Reader outcome and starting-state assumptions.
- Lab sequence with checkpoints.
- Expected outputs and verification steps.
- Troubleshooting table.
- Safety notes and cleanup.
- Suggested companion resources or prerequisites.
Quality Bar
Make the lab useful to a real reader in a real environment. Prefer concrete outputs, checkpoints, and failure handling over abstract explanation or untested command sequences.
1---2name: technical-book-lab-design3description: Design hands-on technical nonfiction chapters as runnable labs, worked examples, exercises, checkpoints, troubleshooting paths, and reader outcomes. Use when turning technical book sections, tutorials, self-hosting chapters, DevOps guides, programming lessons, or infrastructure explanations into practical labs that readers can complete and verify.4license: MIT5---67# Technical Book Lab Design89## Core Lens1011A technical book lab is not a pile of commands. It is a guided reader transformation with a clear starting state, safe path, visible progress, expected output, and exit criteria. The reader should know what they built, why it works, how to verify it, and what to do when it fails.1213Use this skill to design or improve:1415- Self-hosting chapters.16- DevOps, infrastructure, programming, data, or security tutorials.17- Worked examples and exercises.18- Lab prerequisites and environment assumptions.19- Checkpoints, expected outputs, and troubleshooting branches.2021## Reference Routing2223| Need | Read |24|------|------|25| Core lab concepts and terminology | `references/core/knowledge.md` |26| Lab design rules | `references/core/rules.md` |27| Before/after examples | `references/core/examples.md` |28| Lab review checklist | `references/core/checklist.md` |29| Step-by-step lab design | `workflows/design-runnable-lab.md` |3031## Workflow3233### 1. Name The Reader Outcome3435State what the reader will be able to do, decide, deploy, debug, or explain after the lab.3637If the outcome is only "learn about X," sharpen it until there is visible proof of progress.3839### 2. Define The Starting State4041List what the reader already has and knows:4243- Required concepts.44- Accounts, hardware, software, versions, and operating system.45- Network, domain, DNS, permissions, credentials, or safety constraints.46- Files or repo state.4748Move missing prerequisites earlier, compress them, or link them to companion material.4950### 3. Design The Path5152Structure the lab as small checkpoints:5354- Explain the purpose before each action.55- Give the smallest safe command or change.56- Show expected output or state.57- Add a quick verification.58- Explain the next decision.5960### 4. Add Failure Handling6162Technical readers do not only need the happy path.6364- List likely errors and what they mean.65- Add rollback or cleanup steps where changes are risky.66- Mark steps that expose services, change permissions, spend money, or affect data.67- Tell readers when to stop and ask for help.6869### 5. Close The Loop7071End every lab with:7273- Final verification.74- What the reader should understand now.75- What they can safely change next.76- Cleanup, maintenance, or security follow-up.7778## Output Format7980When designing or reviewing a lab, return:81821. Reader outcome and starting-state assumptions.832. Lab sequence with checkpoints.843. Expected outputs and verification steps.854. Troubleshooting table.865. Safety notes and cleanup.876. Suggested companion resources or prerequisites.8889## Quality Bar9091Make the lab useful to a real reader in a real environment. Prefer concrete outputs, checkpoints, and failure handling over abstract explanation or untested command sequences.
ConcertoNotes