agentleFS
WikiEducationFoundationWikiEducationFoundation/WikiEduDashboard/.claude/skills/prepare-pr/SKILL.md

prepare-pr

Skill431 starsChanged 8 months agoMITView on GitHub

Prepare a pull request description for the current branch following the WikiEduDashboard PR template. Use this skill when asked to prepare a PR, draft a PR description, or get a branch ready to open as a pull request.

  • Reads credentials
  • Commits and pushes

12 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. 0 are common, 6 are distinctive, and 13 are very specific to this project.

  • 0

    Common

    Most of the 11 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use the current coding agent's actual product name in attribution text (for example, Claude Code or Codex).

    line 11
  2. Very specific:

    Run bin/pr-screenshots --clean to remove any leftover screenshots and draft from a prior run before starting fresh.

    line 16
  3. Very specific:

    Read PULL_REQUEST_TEMPLATE.md — know the exact sections required

    line 27
  4. Very specific:

    Put it next to the regular specs: spec/features/<feature>_screenshots_spec.rb

    line 46
  5. Distinctive:

    No global RSpec config change needed.

    line 90
  6. Very specific:

    If you're making a small tweak and an existing feature spec already ends up in a good-looking state at one of its assertion points, you can …

    line 109
  7. Distinctive:

    If there are no UI changes at all (pure backend or config PR), skip this phase and put "No UI changes" in the Screenshots section of the …

    line 136
  8. Very specific:

    Write the full PR description to tmp/pr_description.md (create or overwrite).

    line 142
  9. Very specific:

    If commits reference GitHub issues (e.g.

    line 148
  10. Distinctive:

    If there are relevant external docs (API docs, gem docs, Wikipedia policies), link them

    line 149
  11. Distinctive:

    Write an honest, specific statement.

    line 158
  12. Very specific:

    Always end the AI usage section with a sentence noting that this PR description was drafted using the current coding agent and the …

    line 171
  13. Distinctive:

    If screenshots could not be captured (e.g.

    line 179
  14. Distinctive:

    If there's nothing notable, write "None." — don't invent concerns

    line 186
  15. Very specific:

    Run code tmp/pr_description.md to open the file in VS Code and tell the user to press Ctrl+Shift+V to preview it with screenshots rendered …

    line 197
  16. Very specific:

    Make sure the feature branch is on origin first, with a plain push (git push -u origin <branch>).

    line 200
  17. Very specific:

    When ready to publish, run bin/open-pr "<PR title>" once, passing the title explicitly: the commit subject for a single-commit branch, …

    line 205
  18. Very specific:

    Create (or update, if the branch already has an open PR) a draft PR with the full rewritten description.

    line 216
  19. Very specific:

    If neither is available, the script prints instructions for generating a classic PAT with repo scope.

    line 231

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PR Description Preparer

Draft a complete pull request description for the current branch, following the project's PULL_REQUEST_TEMPLATE.md and docs/ai_guidelines.md.

Use the current coding agent's actual product name in attribution text (for example, Claude Code or Codex). Never attribute one agent's work to another.

Phase 0: Clean up previous iteration

Run bin/pr-screenshots --clean to remove any leftover screenshots and draft from a prior run before starting fresh.

Phase 1: Understand the branch

Gather the raw material:

  1. git log master..HEAD --oneline — list all commits
  2. git log master..HEAD --format="%H %ai %s" — commits with timestamps (for estimating elapsed time and effort)
  3. git log master..HEAD — full commit messages (for design decisions and process notes)
  4. git diff master...HEAD --stat — which files changed and how much
  5. Read PULL_REQUEST_TEMPLATE.md — know the exact sections required

From the timestamps, estimate:

  • Elapsed calendar time: from the first commit's date to the last
  • Human effort level: was this done in one sitting (< 1 hour), a few sessions (a day or two), or spread over many days? A large number of commits across many days suggests sustained iteration; a handful of commits within minutes suggests a single focused AI-assisted session.

Phase 2: Capture screenshots

There are two strategies, and picking the right one for the PR matters a lot more than picking the right script invocation.

Strategy A — Disposable screenshot spec (preferred for new features)

For any PR that introduces substantial new UI, write a dedicated feature spec whose only job is to drive the feature through its interesting states and save named PNGs. This gives you complete control over what's shown, lets you seed realistic-looking fixture data, and produces screenshots with stable, descriptive filenames.

Put it next to the regular specs: spec/features/<feature>_screenshots_spec.rb

A minimal template:

require 'rails_helper'

# `if: ENV['SCREENSHOT']` keeps this spec out of the default suite — it
# only defines itself when bin/pr-screenshots sets the env var.
describe '<Feature> screenshots', type: :feature, js: true,
         if: ENV['SCREENSHOT'] do
  let(:admin) { create(:admin) }
  let(:screenshot_dir) { Rails.root.join('tmp', 'screenshots', ENV['SCREENSHOT']) }

  before do
    FileUtils.mkdir_p(screenshot_dir)
    page.current_window.resize_to(1440, 1000)
    login_as(admin)
  end

  def shoot(name)
    sleep 0.2 # let transitions settle
    page.save_screenshot(screenshot_dir.join("#{name}.png"))
  end

  it 'captures the full UI' do
    # seed whatever looks realistic
    visit '/the/feature'
    shoot('01_landing')

    click_button 'Open editor'
    shoot('02_editor_default')

    # keep going through every state worth showing
  end
end

Key conventions:

  • Gate with if: ENV['SCREENSHOT'] so the describe block only exists when bin/pr-screenshots invokes rspec (it sets SCREENSHOT=before or SCREENSHOT=after). The main suite runs zero examples from the file. No global RSpec config change needed.
  • Write to tmp/screenshots/$SCREENSHOT/ so bin/pr-screenshots can pair up before/after PNGs by filename on a later run.
  • Name files by stable sort order (01_, 02_, …) so they appear in the intended order in the PR description.
  • Seed fixture data that looks real, not foo/bar. Reviewers read screenshots.

Then run: bin/pr-screenshots spec/features/<feature>_screenshots_spec.rb

For a brand-new feature, the spec doesn't exist on master so the before column will render as _(did not exist on master)_ automatically. That's the right outcome — there is no "before" state for something that didn't exist. For iterations on an existing UI, commit the spec on master first (or a preceding PR) so the before pass has something to run.

Strategy B — Auto-detected feature specs

If you're making a small tweak and an existing feature spec already ends up in a good-looking state at one of its assertion points, you can skip writing a dedicated spec and let bin/pr-screenshots auto-detect:

bin/pr-screenshots # no arguments

It picks feature specs from files changed in git diff master...HEAD, captures their terminal UI state on both branches, and prints a before/after markdown snippet.

This works best when:

  • The feature spec's final assertion lands on a useful UI state
  • You just want a quick confirmation of a visual change, not a walkthrough

It works poorly when:

  • The spec ends on something generic like "navigate to X and assert Y has content" — the screenshot is whatever happened to be on screen after the last expect, which is often a narrow slice of the feature
  • The spec covers multiple states you'd want to show separately

Notes for either strategy

  • Screenshot files get sanitized by bin/pr-screenshots (strips (, ), →, and collapses -- sequences) so they survive as markdown alt text.
  • The markdown snippet printed by the script uses paths relative to tmp/ (e.g. screenshots/after/01_landing.png) to match where tmp/pr_description.md lives.
  • If there are no UI changes at all (pure backend or config PR), skip this phase and put "No UI changes" in the Screenshots section of the description.

Phase 3: Draft the description

Write the full PR description to tmp/pr_description.md (create or overwrite). Fill in every section of the template:

What this PR does

  • Summarize the purpose in 2–4 sentences — what problem it solves and how
  • If commits reference GitHub issues (e.g. #1234), link them: Addresses #1234
  • If there are relevant external docs (API docs, gem docs, Wikipedia policies), link them

AI usage

Inspect the commit messages for signs of AI involvement:

  • An AI agent in a Co-Authored-By: trailer — AI wrote or substantially drafted the code
  • A (Commit message written by <agent name>.) marker — AI wrote the commit message
  • "## Process" sections in commit bodies — read these for how AI was used

Write an honest, specific statement. This project requires transparency. If an AI coding agent wrote most of the code under human direction, say so clearly. Name the actual tool, describe what it did (drafted code, wrote commit messages, iterated on design), and note what the human contributed (direction, review, decisions about what to build).

Note that the "What this PR does" summary and other analysis in the description were also drafted by the named coding agent and may contain errors.

Include a brief note on the scale of effort: how many commits, over what time span, and roughly what that implies about how much human time was involved. For example: "This was developed across 8 commits over 3 days" or "All commits were made within a single 20-minute session." This helps reviewers calibrate how much iteration and review went into the work.

Always end the AI usage section with a sentence noting that this PR description was drafted using the current coding agent and the prepare-pr skill.

Screenshots

Paste the markdown snippet from bin/pr-screenshots output directly into this section. The script outputs before/after tables; use that output as-is.

If screenshots could not be captured (e.g. spec infrastructure issue), describe what the user should capture manually and which URLs to visit.

Open questions and concerns

  • Surface any tradeoffs or rough edges mentioned in commit messages
  • Note anything left out of scope, or follow-up work that might be needed
  • If there's nothing notable, write "None." — don't invent concerns

AI attribution trailer (required)

End the entire description with this exact line as its final line, after the "Open questions and concerns" section, separated by a blank line:

(PR description written by <agent name>.)

Phase 4: Preview locally and open the PR

Run code tmp/pr_description.md to open the file in VS Code and tell the user to press Ctrl+Shift+V to preview it with screenshots rendered locally.

Make sure the feature branch is on origin first, with a plain push (git push -u origin <branch>); that push and the screenshot-branch push below are the ones the "Git pushes" section of .claude/CLAUDE.md allows without asking, so do them and report them.

When ready to publish, run bin/open-pr "<PR title>" once, passing the title explicitly: the commit subject for a single-commit branch, otherwise a title you draft from the "What this PR does" section. (Without an argument the script prompts on a terminal, and falls back to the last commit subject when there is no terminal to prompt — agents never have one.) It will:

  1. Find each screenshots/… reference in tmp/pr_description.md.
  2. Build an orphan commit containing those files and force-push it to refs/heads/pr-screenshots/<current-branch> on origin.
  3. Rewrite the description to reference each screenshot by its raw.githubusercontent.com URL on that orphan branch.
  4. Create (or update, if the branch already has an open PR) a draft PR with the full rewritten description. An update leaves the title as it was; to change it, run gh pr edit --title "<PR title>".

The result: a draft PR with screenshots rendered inline, in a single pass, with no manual drag-and-drop.

The force-push in step 2 goes only to the pr-screenshots/<branch> orphan branch, never to the feature branch or a permanent branch; it is the one force-push agents may perform unprompted.

Authentication is tried in this order:

  1. GITHUB_TOKEN env var
  2. gh auth token output, if the GitHub CLI is installed and logged in

If neither is available, the script prints instructions for generating a classic PAT with repo scope.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.