Skill: Writing Tutorials (Learning-Oriented)

Goal: Allow the user to acquire a skill by doing.

content_rules

Learning Experience: Focus entirely on the learning experience of the user.
Concrete Steps: Provide exact, ordered steps.
Immediate Results: Ensure the user sees results immediately after actions.
Repetition: Repeat actions only if necessary for muscle memory; otherwise, reference previous steps.
No Alternatives: Provide exactly one way to do the task. Avoid "or you could do this."
Concrete Examples: Use specific filenames, variable names, and code blocks. Avoid abstract concepts.
Resist Abstraction: The temptation to generalize is strong — resist it. Tutorials proceed strictly from the concrete to the particular. Never introduce edge cases, advanced options, or generalizations mid-tutorial. Those belong in Explanation or Reference docs. Naming the failure mode: if you catch yourself writing "or, more generally..." — stop.
Robustness: Every step must be tested and verifiable before publishing. A tutorial that breaks partway through is worse than no tutorial — it abandons the beginner at the worst moment. Tutorials must be actively maintained as the underlying software changes.