AgentSkillsCN

poignant-guide

在生成“感人指南”、以 _why the lucky stiff 风格创作充满奇思妙想的插图式 HTML 文档时，或者当用户请求为某个代码库或功能生成一份“感人指南”时，请使用此技能。

SKILL.md
--- frontmatter
name: poignant-guide
description: Use when generating a "poignant guide", creating whimsical illustrated HTML documentation in the style of _why the lucky stiff, or when the user requests a POIGNANT-GUIDE for a codebase or feature

Poignant Guide Generator

Generate standalone HTML documentation in the narrative and visual style of _why the lucky stiff's (Poignant) Guide to Ruby, with inline SVG comic illustrations, for any codebase or feature.

Mandatory Attribution

Every guide MUST include the _why footer attribution. This is pre-populated in references/template.html and must NEVER be removed. The footer contains _why's quote and credit line (1978-?).

Workflow

  1. •

    Analyze the target codebase - Read key files, trace the primary execution flow, identify 4-8 interesting patterns, decisions, or architectural concepts that would make good chapters. The more surprising or counterintuitive a pattern, the better the chapter.

  2. •

    Map patterns to chapters - Each interesting pattern becomes a chapter with a whimsical title and an absurd-but-perfect metaphor. Load references/narrative-voice.md for tone guidance.

  3. •

    Choose a protagonist - Pick a character (fox, snake, blob) that fits the project's personality. The fox is the default. The character appears in SVG panels and is referenced in the narrative.

  4. •

    Generate the HTML - Load references/template.html for the complete CSS and HTML skeleton. Load references/svg-components.md for reusable SVG building blocks. Generate the full guide as a single self-contained HTML file.

Chapter Structure

Each chapter follows this pattern:

  • •chapter-number + whimsical h2 title
  • •2-3 narrative paragraphs mixing story with technical setup
  • •comic-panel with inline SVG illustration (see svg-components.md)
  • •terminal code block with syntax-highlighted real code from the project
  • •aside box with a gotcha, emotional insight, or joke
  • •divider between chapters

Output Constraints

  • •Single self-contained HTML file - all CSS in <style>, all SVGs inline, no external dependencies beyond Google Fonts
  • •File name: poignant-guide-to-{topic}.html (lowercase, hyphenated) in project root or docs/
  • •4-9 chapters + epilogue with stat cards
  • •3-5 SVG comic panels - fewer well-crafted panels beats many rushed ones
  • •800-1500 lines total, scaling with codebase complexity
  • •Responsive - must work at 700px mobile breakpoint
  • •Epilogue ends with protagonist putting down their tool and waiting, plus summary stat cards
  • •Footer with _why attribution (already in template - do not remove)