How to use the create-pr agent skill for GitHub PRs

What the create-pr skill makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions the agent reads when a request matches the skill's description. The create-pr skill's description says it creates a GitHub PR with a Linear-ticket-prefixed title and a decision-led, narrative description.

Following its instructions, the agent detects the base branch instead of assuming main, reads the commits and diff between that base and your branch, and checks for uncommitted changes. It then identifies the related Linear ticket and writes the PR.

• Title format: TML-NNNN: followed by a concise sentence in sentence case, with no period at the end.
• Ticket lookup: the agent finds the ticket from the branch name, the conversation, or commit messages, and only asks you if all three fail.
• Description: a structure that starts with a Linked issue section and a Skill update section, then covers the decision, how the pieces fit together, and behavior changes with evidence.
• PR creation: the skill uses the GitHub CLI (gh) to run gh pr create.

Install the create-pr skill

Download the ZIP for the skill from this page. Then choose one of two installation routes depending on how you use Claude.

For Claude Code, unzip the archive into ~/.claude/skills/ to make the skill available to you everywhere, or into a project's .claude/skills/ folder to limit it to that project. Make sure the unzipped folder contains SKILL.md.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the repository
• Claude apps: Settings → Capabilities → Skills

Check the requirements before you run it

The skill depends on tools and files that must already exist. If any are missing, the PR step will fail or produce the wrong result.

The skill expects a .github/PULL_REQUEST_TEMPLATE.md file in the repository, and it reads that template before drafting the body. Your branch also needs a Linear ticket identifier in its name or commit messages, or in the conversation. The file does not reference a Linear API key.

• git, with the repository checked out on your feature branch
• GitHub CLI (gh), used to run gh pr create
• A Linear ticket identifier in the branch name (for example tml-1859-...) or in commit messages
• A .github/PULL_REQUEST_TEMPLATE.md file in the repository

Trigger the skill with a natural request

You do not need a special command. The skill's description tells the agent to use it when you ask to create a pull request, open a PR, or submit changes for review. Ask in plain language from inside your repository.

Before the agent opens anything, review the title, base branch and description it proposes. The skill itself notes that uncommitted changes will not be part of the PR, so commit anything you want included first.

• Create a PR for this branch.
• Open a pull request and submit my changes for review.
• Submit this work for review with a PR title and description.

What the agent runs under the hood

The skill's instructions show the git commands the agent uses to gather context. These are read-only comparisons against the base branch. The base branch comes from origin/HEAD, falling back to main if that is not set. You can override it if your PR branches from a non-default branch.

Running these yourself can help you check the agent's work.

• git rev-parse --abbrev-ref origin/HEAD to detect the base branch
• git log "$BASE_BRANCH..HEAD" --oneline to list commits on the branch
• git diff "$BASE_BRANCH...HEAD" --stat to list changed files
• git diff "$BASE_BRANCH...HEAD" to read the full diff
• git status -sb to find uncommitted local changes

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its job ends with gh pr create, which publishes a pull request to GitHub under your account, so treat the step as a real action. Review the proposed title, base branch and body before confirming.

The skill does not reference a Linear API key. The Linear link in the description is built from the ticket identifier, so check that the ticket is the correct one, since the agent can infer the wrong ticket.

• Read the proposed base branch. The agent may infer the wrong one.
• Commit all changes you want in the PR, because uncommitted work is left out.
• Confirm the ticket ID, since the agent might pick up the wrong one from the branch or commits.
• Check the body against your .github/PULL_REQUEST_TEMPLATE.md before submitting.

Tips for better PR titles and descriptions

Clear branch names and commit messages make the ticket lookup more reliable. The skill's rules favour titles that name the concrete deliverable so a teammate can understand the PR from the title alone.

If a change spans several packages, the title should name the headline package or capability, and secondary scopes belong in the body.

• Name branches with the ticket identifier, such as tml-NNNN-short-slug.
• Put the ticket in commit messages with a Refs: TML-NNNN trailer.
• Aim for under 70 characters in the title and keep it specific.
• Use the Linked issue and Skill update sections as the skill expects, even for small changes.