create-pr

Overview of create-pr skill

What create-pr does

The create-pr skill helps an agent turn finished branch work into a review-ready pull request, with one important specialization: it checks whether repository documentation also needs updating and, in this repo’s intended workflow, keeps both English and Chinese README content aligned. If you want more than “write me a PR title,” create-pr is designed for the full handoff step: inspect changes, decide doc impact, prepare updates, verify branch state, and draft the PR.

Who the create-pr skill is best for

This create-pr skill is best for users who already have changes on a Git branch and want a repeatable PR workflow instead of ad hoc prompting. It is especially relevant if your repository treats docs as part of the definition of done, or if you maintain bilingual project pages and do not want PRs merged with stale README content.

The real job-to-be-done

Most users do not just need “a pull request.” They need an agent to:

1. understand what changed,
2. identify whether user-facing docs must change,
3. summarize the work clearly for reviewers, and
4. avoid the common failure of shipping code while forgetting README updates.

That is where create-pr for Git Workflows is more useful than a generic “draft a PR description” prompt.

What makes create-pr different from a generic prompt

The main differentiator is workflow structure. The skill does not start from prose; it starts from git evidence such as git status, git diff, and branch history relative to main. It also includes a decision step for docs updates, including changes under skills/, which is much more actionable than asking a model to “look around and make a PR.”

What matters before you install

The key adoption question is fit. create-pr is a strong fit if:

• you work in Git branches,
• you want a checklist-like PR process,
• you want docs impact considered automatically,
• you are comfortable letting the agent inspect repo state.

It is a weaker fit if you only want a one-line PR summary or if your environment blocks git inspection and file edits.

How to Use create-pr skill

Install context and repository path

The upstream repository shows create-pr as a skill inside zhaono1/agent-playbook at skills/create-pr. The repo README demonstrates a Claude-style symlink install pattern:

ln -s ~/Documents/code/GitHub/agent-playbook/skills/create-pr/SKILL.md ~/.claude/skills/create-pr.md

If you use a different skill loader, adapt the pathing, but the important source file is still skills/create-pr/SKILL.md.

Read these files first

Before relying on the skill, read:

• skills/create-pr/SKILL.md
• skills/create-pr/README.md

SKILL.md is the operational source: activation triggers, workflow steps, and allowed tools. README.md is useful for install intent and the high-level flow.

How create-pr is triggered in practice

The skill is meant to activate from requests such as:

• “create a PR”
• “make a pull request”
• “submit my changes”
• “push and create PR”

That means create-pr usage is conversational, but the quality depends on the branch already containing coherent work. The skill is not a substitute for finishing implementation first.

What inputs the skill needs

The strongest create-pr usage starts with concrete repository state:

• a clean understanding of the target base branch, usually main
• committed or at least inspectable local changes
• the intended scope of the PR
• any reviewer-relevant context, such as breaking changes or follow-up work
• confirmation of whether bilingual docs are expected in your repo

Without that, the agent can still inspect diffs, but it may produce a generic PR draft or miss organizational expectations.

Core workflow the skill follows

From the repository evidence, the create-pr skill follows a practical sequence:

1. inspect branch state with git,
2. analyze changed files and impact area,
3. determine whether docs must be updated,
4. update English and Chinese README content when required,
5. verify completeness,
6. prepare the PR content.

This is the main reason to use the skill instead of a free-form prompt: the process is anchored in repository evidence.

The git checks that drive quality

The skill explicitly relies on commands like:

git status
git diff
git log --oneline main..HEAD
git diff --name-only main..HEAD | grep "^skills/"

These checks matter because they tell the agent:

• whether the branch is actually ready,
• what changed since main,
• whether skill documentation may need index-level updates.

If your branch compares against a different base branch, say so up front. Otherwise the default main..HEAD assumption can skew the summary.

Turn a rough request into a strong prompt

A weak prompt:

• “Create a PR for this.”

A stronger prompt:

• “Use create-pr to prepare a PR against main. Review the branch diff, identify whether any README or skills index updates are required, and draft a concise PR title and body. This branch adds a new skill and updates existing usage docs, so please check both English and Chinese README parity.”

Why this works:

• it names the base branch,
• it tells the agent to inspect before writing,
• it signals likely doc impact,
• it clarifies the expected output.

Example prompt for documentation-sensitive repos

Use something like:

Use the create-pr skill for the current branch. Compare against main, summarize the code and doc changes, verify whether README.md and README.zh-CN.md need updates, and draft a reviewer-friendly PR with scope, testing notes, and any follow-up items.

This prompt is better than “open a PR” because it encodes the repository behaviors the skill is built around.

Practical workflow advice before running create-pr

For better results:

• finish the branch scope first,
• squash obvious noise commits if your team prefers clean history,
• make sure generated files are intentional,
• note any files that should be excluded from PR emphasis,
• decide whether bilingual docs are mandatory or optional.

This saves the skill from over-describing churn or under-reporting user-facing changes.

How to handle bilingual documentation updates

A central feature of create-pr for Git Workflows in this repo is bilingual README synchronization. If your branch adds, removes, or changes a skill, do not just ask for a PR draft. Ask the agent to explicitly check whether README.md and README.zh-CN.md need matching updates. That is where the skill adds real value versus ordinary PR-copy generation.

When the skill may need clarification

You should give extra guidance if:

• your default branch is not main,
• your repo does not use bilingual docs,
• the branch includes unrelated changes,
• you want the PR split into smaller units,
• you need the agent to stop before pushing or opening anything.

The skill’s workflow is useful, but these repo-specific constraints are not safely inferable.

create-pr skill FAQ

Is create-pr only for this repository?

No, but it is clearly shaped by the agent-playbook repository’s expectations, especially bilingual README maintenance and skill-directory changes. You can adapt the workflow elsewhere, but the closer your process is to “analyze diff, update docs, draft PR,” the better the fit.

Is create-pr good for beginners?

Yes, if the beginner already understands basic Git branch concepts. The create-pr guide value is that it makes the pull request step less easy to forget. It is not a substitute for learning what a base branch, diff, or review summary is.

When should I not use create-pr?

Skip create-pr if you only need a quick PR title, if your repo has no doc-sync expectations, or if the branch is messy and not yet reviewable. In those cases, a normal prompt may be faster or you may need to clean the branch first.

How is create-pr better than asking for a PR description directly?

A plain prompt usually starts from whatever text you give it. create-pr starts from repository evidence and includes a doc-update decision step. That reduces the chance of a polished but incomplete PR, especially in repos where docs and code must ship together.

Does create-pr actually open the PR on GitHub?

Based on the provided evidence, the skill is primarily about preparing and verifying the PR workflow, not guaranteed end-to-end GitHub API automation. Treat it as a structured PR creation assistant unless your environment adds the final open/push steps.

Does create-pr require bilingual documentation?

No. That is a specialization of this implementation, not a universal requirement for the concept. But if your repo does maintain English and Chinese docs, the create-pr skill is more compelling because it explicitly accounts for that burden.

How to Improve create-pr skill

Give create-pr better repository context

The fastest way to improve create-pr output is to provide:

• target base branch,
• intended PR scope,
• whether docs should be updated,
• whether the final output should include title, summary, test notes, and checklist,
• any branch-specific caveats.

This reduces guesswork and keeps the PR aligned with team norms.

Improve the input quality, not just the prompt wording

The skill performs best when the branch itself is coherent. If the diff mixes refactors, fixes, and doc edits with no clear story, the PR will also be harder to frame. Clean commits and clear scope improve create-pr usage more than clever wording does.

Tell the skill what counts as user-facing change

A common failure mode is under-updating docs because the code change feels “small.” If a new skill, command, workflow, or file path becomes visible to users, say so explicitly. That nudges create-pr to check README-level documentation instead of stopping at code summary.

Prevent the wrong base-branch comparison

One easy miss is comparing against main when the true target is another branch. If your workflow uses develop, release branches, or stacked PRs, say that up front. Otherwise the skill may summarize the wrong change set or suggest unnecessary updates.

Ask for a verification pass before finalizing

A strong iteration prompt is:

Run create-pr, then do a final verification pass: confirm changed files are reflected in the PR summary, confirm whether README.md and README.zh-CN.md are consistent, and call out anything that still needs manual review.

This catches the most important failure mode: a PR that sounds complete but does not match the actual diff.

Use iteration after the first draft

After the first create-pr output, improve it by asking:

• “Shorten the PR title for reviewer scanning.”
• “Call out breaking changes separately.”
• “Make the testing notes more explicit.”
• “List documentation updates in a dedicated section.”
• “Explain why this belongs in one PR rather than two.”

These are high-value refinements because they improve review quality, not just phrasing.

Adapt create-pr if your repo is not bilingual

If you reuse this create-pr guide outside the original repo, replace the bilingual README rule with your own documentation system:

• docs site pages,
• changelog entries,
• package release notes,
• internal runbooks.

The skill’s real strength is the decision logic between code changes and documentation obligations. Preserve that, even if the target files differ.

Watch for scope creep in create-pr output

Another common issue is the agent over-explaining incidental changes. To improve results, tell it which files are central and which are mechanical. That keeps the PR body reviewer-friendly and avoids making the branch seem larger or riskier than it is.