custom-gh-pr-reading-guide

Adds a mermaid mental-model diagram and ordered reading table to GitHub PR descriptions.

1|Updated Apr 3, 2021
One-click install
npx skills add https://github.com/NaoyaMiyagawa/dotfiles --skill custom-gh-pr-reading-guide-naoyamiyagawa
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: custom-gh-pr-reading-guide
Source: https://github.com/NaoyaMiyagawa/dotfiles/tree/main/.ai/skills/custom-gh-pr-reading-guide
Command: npx skills add https://github.com/NaoyaMiyagawa/dotfiles --skill custom-gh-pr-reading-guide-naoyamiyagawa

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Reviewers facing a PR that introduces an unfamiliar subsystem, protocol, or vocabulary of types have no route into the code; the diff shows what changed but not how to understand it. This Skill writes a reading guide into the PR description so reviewers know where to start and in what order to read. ## Core Features & Use Cases - Mental-Model Diagram: Generates a mermaid flowchart where every node label carries its job or invariant, capped at seven nodes, with dotted edges showing round-trips or idempotency. - Ordered Reading Table: Builds a four-to-seven-row table linking exact symbols to the pinned commit SHA, ordered by what must be understood first and ending on the proving test. - Safe Description Splicing: Wraps the guide in HTML comment markers and uses gh pr edit --body-file so re-runs replace the block instead of duplicating it. - Use Case: A PR introduces a new binary encoder; the Skill adds a diagram of the encode/decode round-trip plus a table routing the reviewer from the type definitions through the encoder to the byte-for-byte round-trip test. ## Quick Start Ask the AI to add a reading guide with a mental-model diagram and reading-order table to the current GitHub PR description.

Frequently Asked Questions about custom-gh-pr-reading-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a reading guide to a GitHub PR description?

Fetch the PR body with gh pr view, build a mermaid mental-model diagram plus an ordered reading table, splice the block between HTML comment markers into the existing body, and update it with gh pr edit --body-file.

When should a pull request include a reading guide?

Add one when the PR introduces something reviewers hold no prior model of, such as a wire format, encoder, protocol, state machine, or new vocabulary of types. A CRUD endpoint or refactor does not need one.

Does GitHub render mermaid diagrams in PR descriptions?

Yes, GitHub renders mermaid code blocks natively in PR descriptions. The guide uses a flowchart LR diagram with node labels that state each component's job or invariant rather than just its name.

Why does gh pr edit overwrite my entire PR description?

gh pr edit replaces the entire body, so never pass it the guide alone. Read the current body first, splice the guide between the marker comments, write the full result to a file, then run gh pr edit with --body-file.

How many rows should a PR reading-order table have?

Four to seven rows. Each row links one exact symbol or directory at the pinned commit SHA and states the payoff of reading it, ending on the test that proves the change end-to-end.