Open PR

This skill instructs AI agents on how to create GitHub pull requests from conversation context with meaningful titles, proper formatting, and appropriate tag selection. The AI agent should analyze the conversation, extract PR details, and confirm with the user before creating the pull request.

PR Format

GitHub pull requests created by this skill must follow this exact structure:

markdown
1# [tag][#issue-number] Brief description of what was achieved
2
3## Summary
4
5Provide a concise summary of what has been achieved in this PR. Focus on the
6completed work and the value it delivers.
7
8## Changes
9
10Provide a detailed list of changes made in this PR:
11- Modified `file_path:line_range` to implement X
12- Added `new_file.py` for Y functionality
13- Updated `config.json` to support Z
14- Removed deprecated code from `old_file.py:line_range`
15
16## Testing
17
18Describe what was tested and how:
19- Added `tests/test_feature.py` to verify behavior A
20- Modified `tests/test_existing.py:line_range` to cover edge case B
21- Manually tested scenario C with the following steps:
22  1. Step 1
23  2. Step 2
24  3. Expected result
25
26## Related Issue
27
28Closes #issue-number
29
30(Or "Part of #issue-number" if this PR partially addresses the issue)

Tag Selection

A git-msg-tags.md file should appear in {ROOT_PROJ}/docs/git-msg-tags.md which defines the tags related to the corresponding modules or modifications. The AI agent MUST refer to this file to select the appropriate tag for the PR title.

If the file does not exist, reject the PR creation and ask the user to provide a list of tags in docs/git-msg-tags.md.

Tag Logic

The AI agent must determine which tag to use based on the PR type by reading docs/git-msg-tags.md which contains the project's tag definitions.

Selection guidelines:

• Read docs/git-msg-tags.md to understand available tags and their meanings
• Choose the most specific tag that describes the primary change
• If multiple tags could apply, choose the one that best represents the core purpose
• If the tag is ambiguous, ask the user to select from 2-3 most relevant options

Workflow for AI Agents

When this skill is invoked, the AI agent MUST follow these steps:

1. Context Analysis Phase

Review the entire conversation history and git changes to extract PR details:

• Identify what work was completed during the conversation
• Review git diff and git status to see actual changes made
• Extract key details: what was changed, why, which files were affected
• Determine the type of changes (feature, bugfix, refactor, etc.)
• Check if there's a related issue number mentioned in the conversation

Context signals for PR type:

• Feature signals: new functionality added, new files created, capabilities extended
• Bugfix signals: fixed error, resolved issue, corrected behavior
• Refactor signals: improved code structure, reorganized code, better patterns
• Documentation signals: updated README, added comments, wrote guides
• Test signals: added test coverage, modified test cases

2. Git Changes Review

CRITICAL: Before drafting the PR, the AI agent MUST review actual git changes:

bash
1# Check what files have changed
2git status
3
4# Review the actual changes
5git diff
6
7# Check commit history on current branch
8git log origin/main..HEAD --oneline

This ensures the PR description accurately reflects the actual code changes.

3. Tag Selection Phase

• Read docs/git-msg-tags.md to understand available tags
• Analyze the changes and determine the primary purpose
• Apply the tag logic described above
• If multiple tags could apply, choose the most specific one
• If the tag is ambiguous, ask the user to choose from 2-3 most relevant options

4. Issue Number Extraction

CRITICAL: The PR title MUST include an issue number in the format [tag][#N].

How to find the issue number:

1. Search conversation history for explicit issue references:

   • "for issue #42"
   • "closes #15"
   • "related to #23"
   • GitHub issue URLs containing issue numbers

2. If no issue number is found in conversation:

   • Check if there are recent issues that match this work:

     bash
     1gh issue list --limit 10

   • Ask the user: "Which issue does this PR address? (Provide issue number)"

3. If user says there's no related issue:

   • STOP and inform the user:

     Cannot create PR without a related issue.
     Please create an issue first using the open-issue skill, or provide an existing issue number.
     

Never create a PR without an issue number.

5. PR Draft Construction

Build the PR following the format specification:

Title:

• Format: [tag][#issue-number] Brief description
• The description should be in past tense (what was achieved)
• Keep description concise (max 80 characters for the description portion)
• Example: [feat][#42] Add TypeScript SDK template support
• Example: [bugfix][#15] Fix pre-commit hook test execution

Summary section:

• Describe what has been achieved (past tense)
• Focus on the value and purpose of the changes
• Keep it concise but meaningful

Changes section:

• List specific files modified, added, or deleted
• Include line ranges when relevant (e.g., file.py:12-34)
• Describe what each change does
• Order changes logically (not just alphabetically)
• DO NOT include actual code snippets to save context length

Testing section:

• Describe what was tested
• List new test files added with what they test
• List modified test files with what new coverage was added
• Include manual testing steps if applicable
• Be specific about test scenarios and expected outcomes

Related Issue section:

• Use Closes #N if this PR fully resolves the issue
• Use Part of #N if this PR partially addresses the issue
• Use Fixes #N for bugfix PRs
• GitHub will automatically link and close the issue when PR is merged

6. User Confirmation Phase

CRITICAL: The AI agent MUST display the complete PR draft to the user and wait for explicit confirmation before creating the PR.

Present the draft in a clear format:

I've prepared this pull request:

---
[Full PR content here]
---

Should I create this PR?

• Wait for explicit "yes", "confirm", "create it", or similar affirmative response
• If the user requests modifications, update the draft and present again
• If the user declines, abort PR creation gracefully

6.5. Remote Branch Verification

CRITICAL: Before creating the PR, verify the current branch exists on the remote repository.

Check if the current branch is tracking a remote branch:

bash
1# Check if current branch has an upstream branch
2git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null

If the command fails (no upstream branch):

1. Get the current branch name:

   bash
   1git branch --show-current

2. Push the branch with tracking:

   bash
   1git push -u origin <branch-name>

3. Confirm to user: "Pushed branch to remote: origin/<branch-name>"

If the command succeeds (upstream branch exists):

1. Check if local is ahead of remote:

   bash
   1git status --porcelain --branch

2. If output contains [ahead N], push changes:

   bash
   1git push

3. If up-to-date, continue to PR creation

Error handling:

• If push fails due to authentication:

  Git push failed. Please check your Git credentials.
  

• If push fails due to conflicts:

  Cannot push: your branch has diverged from remote.
  Please resolve conflicts manually with:
    git pull --rebase origin <branch-name>
  

• For other push failures: Display the error and abort PR creation

7. GitHub PR Creation

Once confirmed and the branch is on remote, create the PR using the GitHub CLI:

bash
1gh pr create --title "TITLE_HERE" --body "$(cat <<'EOF'
2BODY_CONTENT_HERE
3EOF
4)"

Important:

• Use heredoc (<<'EOF' ... EOF) to preserve markdown formatting
• The body should include all sections from Summary onwards (not the title)
• The PR will be created against the default branch (usually main/master)
• After successful creation, display the PR URL to the user
• Confirm: "Pull request created successfully: [URL]"

Optional flags:

• Add --draft if the user wants to create a draft PR
• Add --base BRANCH if targeting a different base branch

8. Error Handling

Handle common error scenarios gracefully:

Missing git-msg-tags.md:

Cannot create PR: docs/git-msg-tags.md not found.
Please create this file with your project's tag definitions.

No issue number found:

Cannot create PR: No related issue number found.

Please either:
1. Provide the issue number this PR addresses
2. Create an issue first using the open-issue skill

No git changes:

Cannot create PR: No changes detected in the working directory.
Please make and commit your changes first.

GitHub CLI not authenticated:

GitHub CLI is not authenticated. Please run:
  gh auth login

Not on a feature branch:

Warning: You're on the main/master branch.
PRs should typically be created from feature branches.

Create a new branch with:
  git checkout -b feature/your-feature-name

Or confirm you want to create a PR from the current branch.

No conversation context:

I don't have enough context to create a PR. Could you please provide:
- What changes were made?
- What issue does this PR address?
- What was tested?

PR creation failed:

Failed to create pull request: [error message]
Please check your GitHub CLI configuration and try again.

Ownership

The AI agent SHALL NOT claim authorship or co-authorship of the pull request. The PR is created on behalf of the user, who is FULLY responsible for its content.

Do not add any "Created by AI" or similar attributions to the PR body unless explicitly requested by the user.

Examples

Note: The following examples use tags like [feat], [bugfix], [agent.skill] etc. These are illustrative only - actual tags must come from your project's docs/git-msg-tags.md.

Example 1: Feature PR

Context: User implemented TypeScript SDK template support to close issue #42.

PR:

markdown
1# [feat][#42] Add TypeScript SDK template support
2
3## Summary
4
5Added support for generating TypeScript SDK templates in the agentize project.
6Developers can now bootstrap TypeScript-based agent SDKs alongside existing
7Python templates.
8
9## Changes
10
11- Created `templates/typescript/` directory structure with standard layout
12- Added `templates/typescript/package.json` with default dependencies (typescript, @types/node)
13- Created `templates/typescript/tsconfig.json` with recommended compiler settings
14- Added `templates/typescript/src/index.ts` as the SDK entry point
15- Updated `claude/skills/sdk-init/SKILL.md` to include TypeScript as a language option
16- Modified `sdk-init` skill logic to handle TypeScript template generation
17
18## Testing
19
20- Added `tests/test_typescript_template.py` to verify:
21  - Template directory creation
22  - All required files are generated correctly
23  - package.json has correct dependencies
24  - tsconfig.json has proper compiler options
25- Manually tested TypeScript template generation:
26  1. Ran sdk-init skill and selected TypeScript
27  2. Verified generated files compile without errors
28  3. Confirmed npm install works correctly
29  4. Built sample TypeScript SDK successfully
30
31## Related Issue
32
33Closes #42

Example 2: Bugfix PR

Context: User fixed pre-commit hook not running tests (issue #15).

PR:

markdown
1# [bugfix][#15] Fix pre-commit hook test execution
2
3## Summary
4
5Fixed the pre-commit hook to properly execute the test suite before allowing commits.
6The hook was not running tests due to incorrect path resolution.
7
8## Changes
9
10- Modified `.git/hooks/pre-commit:8-12` to use absolute path for test script
11- Updated hook to check exit code and block commit on test failure
12- Added error message output when tests fail
13
14## Testing
15
16- Modified `tests/test_hooks.py:23-45` to verify pre-commit hook behavior
17- Manually tested the fix:
18  1. Made changes to a Python file in `claude/skills/`
19  2. Ran `git add .` and `git commit -m "test"`
20  3. Confirmed tests executed and commit was blocked when tests failed
21  4. Fixed the test failure
22  5. Confirmed commit succeeded after tests passed
23
24## Related Issue
25
26Fixes #15

Example 3: Agent Skill PR

Context: User created the open-pr skill (issue #67).

PR:

markdown
1# [agent.skill][#67] Add open-pr skill for creating pull requests
2
3## Summary
4
5Added the open-pr skill that guides AI agents through creating well-formatted
6GitHub pull requests with proper tag selection and mandatory issue references.
7
8## Changes
9
10- Created `claude/skills/open-pr/` directory
11- Added `claude/skills/open-pr/SKILL.md` with complete PR creation workflow
12- Skill enforces issue number requirement in PR titles
13- Includes comprehensive examples and error handling guidelines
14
15## Testing
16
17- Added `tests/test_open_pr_skill.py` to verify:
18  - Skill file structure and format
19  - Tag selection logic correctness
20  - Issue number extraction from various formats
21- Manually tested skill workflow:
22  1. Invoked open-pr skill in conversation
23  2. Verified it correctly extracted issue number from context
24  3. Confirmed it generated proper PR format
25  4. Tested error handling for missing issue numbers
26
27## Related Issue
28
29Closes #67