Skip to content

gpsaggese/helpers / .claude/skills/blog.write_tutorial_readme

blog.write_tutorial_readme

Flagged

Write a practical tutorial for engineers covering one tool or concept

FileKindSize
SKILL.mdskill md2.8 KB
---
description: Write a practical tutorial for engineers covering one tool or concept
model: opus
---

# 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:

  1. **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

  2. **Prerequisites** (if any)
     - Required knowledge or tools

  3. **Installation/Setup** (if applicable)
     - Clear, copy-paste ready commands
     - Verify the installation with a simple test

  4. **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.md` as template

## Code Examples
- Use copy-paste ready code blocks, with `bash` or 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:
    ```bash
    > curl -LsSf https://astral.sh/uv/install.sh | sh
    ```

## 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.md` and `.claude/skills/text.rules.md`

# Examples to Reference
- Located in `website/docs/blog/posts/`. Study them for structure, tone, depth, and
  length
  - `website/docs/blog/posts/in_30_mins.uv.md`: tool intro, install, core concepts
  - `website/docs/blog/posts/in_30_mins.ripgrep.md`: search tool, use cases
  - `website/docs/blog/posts/in_30_mins.Python_Packaging.md`: concept, with workflow
  - `website/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.md` and
      `.claude/skills/text.rules.md`
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall