create-pr - SKILL.md Agent Skill

name: create-pr description: Validate tests and docs, then create a GitHub PR with conventional commit formatting disable-model-invocation: true argument-hint: [base branch]

Create Pull Request

Validate that all tests and documentation pass, then create a well-formatted GitHub PR for the current branch.

Context

Current branch:

!git branch --show-current

Repository:

!git remote get-url origin 2>&1

Commits on this branch (vs main):

!git log --oneline main..HEAD 2>&1 || git log --oneline origin/main..HEAD 2>&1 || echo "Could not determine commits"

Changed files (vs main):

!git diff --stat main..HEAD 2>&1 || git diff --stat origin/main..HEAD 2>&1 || echo "Could not determine changes"

Existing open PR for this branch:

!gh pr view --json number,title,url,state 2>&1 || echo "NO_EXISTING_PR"

Arguments

$ARGUMENTS

If $ARGUMENTS specifies a base branch, use that instead of the default branch.

Workflow

Follow these steps in strict order. Do NOT skip ahead.

Step 0: Pre-flight checks

Verify the current branch is NOT main. If it is, stop and tell the user to create a feature branch first.
If a PR already exists for this branch, inform the user and ask whether to update the existing PR description or stop.
Ensure all changes are committed. If there are uncommitted changes, inform the user and stop.
DCO sign-off check: Verify that every commit on this branch has a Signed-off-by: line:

git log main..HEAD --format="%h %s" --no-merges | while read hash rest; do
  if ! git log -1 --format="%b" "$hash" | grep -q "^Signed-off-by:"; then
    echo "MISSING DCO: $hash $rest"
  fi
done

If any commits are missing DCO sign-off, report them and stop. Instruct the user to fix with:

git rebase main --exec "git commit --amend --signoff --no-edit"

Do NOT create the PR until all commits have DCO sign-off.

Step 1: Identify affected packages

Examine the commit history and changed files to determine which libs/* packages were modified. This determines which workspaces need building, testing, and which scopes to use in the PR title.

Step 2: Build affected packages

Build each affected package:

npm run build -w libs/<package>

If a build fails, report the error and stop. Do NOT create the PR.

Step 3: Run tests

Run tests for each affected package:

npm test -w libs/<package>

If any test fails, report the error and stop. Do NOT create the PR.

Step 4: Run typecheck

npm run typecheck

If the typecheck fails on files within libs/ (ignore pre-existing errors in node_modules), report the error and stop. Do NOT create the PR.

Step 5: Build and validate documentation

Build the documentation to catch TSDoc errors, broken {@includeCode} references, and missing documentation:

npm run build -w docs

Review the output for warnings and errors. If there are documentation errors related to the changed packages, report them and stop. Do NOT create the PR.

Step 6: Find related GitHub issues

Search for related open issues in the repository:

gh issue list --state open --json number,title --limit 50

Also check the commit messages and branch name for issue references (e.g., #123, issue-123, fixes-123).

Present any potentially related issues to the user and ask which (if any) should be referenced in the PR.

Step 7: Draft the PR title and description

Title Format

Follow conventional commit format. The title must be under 70 characters.

Pattern: <type>(<scope>): <short description>

Types:

feat - New feature or public API addition
fix - Bug fix
refactor - Code change that neither fixes a bug nor adds a feature
docs - Documentation only changes
test - Adding or correcting tests
chore - Maintenance, tooling, or dependency updates
build - Changes that affect the build system
perf - Performance improvement

Scope: The package name without the libs/ prefix (e.g., cmcd, iso-bmff, utils). If multiple packages are affected, use the primary package or omit the scope.

Examples:

feat(cmcd): add CmcdReporter class
fix(iso-bmff): handle non-zero byteOffset in parsePsshList
refactor(utils): rename RequestType to ResponseType
feat: add throughput measurement library

Description Format

Use this template:

## Summary

<1-4 bullet points describing what changed and why>

## Packages Changed

| Package | Version | Change Type |
|---------|---------|-------------|
| @svta/cml-<name> | x.x.x | feat/fix/etc |

## Test Plan

- [ ] <specific test scenarios that validate the changes>

Refs: <issue references>

Refs footer rules:

Use Fixes #N if the PR fully resolves an issue (this auto-closes the issue on merge)
Use Refs #N if the PR is related but does not fully resolve the issue
Multiple references are comma-separated: Refs: #12, #34, Fixes #56
Only include issue references confirmed by the user in Step 6
Omit the Refs: line entirely if there are no related issues

Step 8: Present for approval

Show the user the complete PR title and description. Ask for approval or revisions. The user may:

Approve as-is
Modify the title, description, or issue references
Request changes to the scope or type

Do NOT create the PR until the user explicitly approves.

Step 9: Push and create the PR

Ensure the branch is pushed to the remote:

git push -u origin <branch-name>

Create the PR:

gh pr create --base <base-branch> --title "<title>" --body "$(cat <<'EOF'
<description>
EOF
)"

Display the PR URL to the user.

Important Notes

Never create a PR with failing tests or documentation errors.
The conventional commit type in the PR title should reflect the primary change, not every change.
Keep the title under 70 characters. Use the description for details.
The summary bullets should explain why the changes were made, not just what files changed.
If builds are slow, only build packages that are directly affected by the changes and their dependents.
Always push with -u to set up tracking if not already configured.
Every commit must have DCO sign-off. Always use git commit -s and include Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> in the message body. If you need to fix issues discovered during validation (Steps 2-5), commit the fixes with these requirements before proceeding.