gpsaggese/helpers / .claude/skills/blog.write_tutorial_readme
blog.write_tutorial_readme
FlaggedWrite a practical tutorial for engineers covering one tool or concept
Goal
- Write clear, hands-on tutorials that help engineers quickly learn a new tool, technique, or concept
- Tutorials should be practical and immediately applicable, not theoretical surveys
Audience
- Target: Software engineers and technical practitioners
- Skill level: General to intermediate (some programming knowledge assumed)
- Goal: Readers can use the tool or technique effectively after reading
Tutorial Structure
-
Follow this outline:
-
Introduction (1-2 paragraphs)
- What is this tool or concept? Why should engineers care?
- When to use it (not just "always") and which tools solve similar problems
- Links to official docs: installation, documentation, tutorial
-
Prerequisites (if any)
- Required knowledge or tools
-
Installation/Setup (if applicable)
- Clear, copy-paste ready commands
- Verify the installation with a simple test
-
Core Concepts (1-2 paragraphs)
- Explain 2-3 key ideas
-
Guidelines
Length
- Target 10-15 minutes of reading time (roughly 1500-2500 words)
- Focus on the 80% use case. Avoid covering everything
Template
- Use
website/docs/blog/posts/draft.blog_template.mdas template
Code Examples
- Use copy-paste ready code blocks, with
bashor language-specific highlighting - Include expected output, so readers know it worked
- For shell commands, show the prompt style, e.g.,
- On macOS and Linux using the official installer:
> curl -LsSf https://astral.sh/uv/install.sh | sh
- On macOS and Linux using the official installer:
Platform Coverage
- Focus on macOS and Linux
Tone & Voice
- Direct and practical ("use this when..." not "one might consider...")
- Active voice, short sentences
- Assume busy engineers. Do not be overly casual
Visuals
- Include diagrams only if they clarify workflow or architecture
- Use simple mermaid or graphviz diagrams, or external images, if needed
- Do not over-decorate
Formatting
- Follow
.claude/skills/markdown.rules.mdand.claude/skills/text.rules.md
Examples to Reference
- Located in
website/docs/blog/posts/. Study them for structure, tone, depth, and lengthwebsite/docs/blog/posts/in_30_mins.uv.md: tool intro, install, core conceptswebsite/docs/blog/posts/in_30_mins.ripgrep.md: search tool, use caseswebsite/docs/blog/posts/in_30_mins.Python_Packaging.md: concept, with workflowwebsite/docs/blog/posts/in_30_mins.mdm_unified_markdown_manager.md: multi-tool tutorial
Verification
- Confirm the tutorial reads in 10-15 minutes (see
## Length) - Confirm every code block has a language tag and shows expected output
- Confirm the tutorial follows
.claude/skills/markdown.rules.mdand.claude/skills/text.rules.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |