open-pr

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

```markdown

# [tag][#issue-number] Brief description of what was achieved

Provide a concise summary of what has been achieved in this PR. Focus on the

completed work and the value it delivers.

Provide a detailed list of changes made in this PR:

• Modified file_path:line_range to implement X
• Added new_file.py for Y functionality
• Updated config.json to support Z
• Removed deprecated code from old_file.py:line_range

Describe what was tested and how:

• Added tests/test_feature.py to verify behavior A
• Modified tests/test_existing.py:line_range to cover edge case B
• Manually tested scenario C with the following steps:

1. Step 1

2. Step 2

3. Expected result

Closes #issue-number

(Or "Part of #issue-number" if this PR partially addresses the issue)

```

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

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

# Check what files have changed

git status

# Review the actual changes

git diff

# Check commit history on current branch

git 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

1. If no issue number is found in conversation:

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

```bash

gh issue list --limit 10

```

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

1. 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

# Check if current branch has an upstream branch

git 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

git branch --show-current

```

1. Push the branch with tracking:

```bash

git push -u origin

```

1. Confirm to user: "Pushed branch to remote: origin/"

If the command succeeds (upstream branch exists):

1. Check if local is ahead of remote:

```bash

git status --porcelain --branch

```

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

```bash

git push

```

1. 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

```

• 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

gh pr create --title "TITLE_HERE" --body "$(cat <<'EOF'

BODY_CONTENT_HERE

EOF

)"

```

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.

```

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.

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

# [feat][#42] Add TypeScript SDK template support

Added support for generating TypeScript SDK templates in the agentize project.

Developers can now bootstrap TypeScript-based agent SDKs alongside existing

Python templates.

• Created templates/typescript/ directory structure with standard layout
• Added templates/typescript/package.json with default dependencies (typescript, @types/node)
• Created templates/typescript/tsconfig.json with recommended compiler settings
• Added templates/typescript/src/index.ts as the SDK entry point
• Updated claude/skills/sdk-init/SKILL.md to include TypeScript as a language option
• Modified sdk-init skill logic to handle TypeScript template generation

• Added tests/test_typescript_template.py to verify:

- Template directory creation

- All required files are generated correctly

- package.json has correct dependencies

- tsconfig.json has proper compiler options

• Manually tested TypeScript template generation:

1. Ran sdk-init skill and selected TypeScript

2. Verified generated files compile without errors

3. Confirmed npm install works correctly

4. Built sample TypeScript SDK successfully

Closes #42

```

Example 2: Bugfix PR

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

PR:

```markdown

# [bugfix][#15] Fix pre-commit hook test execution

Fixed the pre-commit hook to properly execute the test suite before allowing commits.

The hook was not running tests due to incorrect path resolution.

• Modified .git/hooks/pre-commit:8-12 to use absolute path for test script
• Updated hook to check exit code and block commit on test failure
• Added error message output when tests fail

• Modified tests/test_hooks.py:23-45 to verify pre-commit hook behavior
• Manually tested the fix:

1. Made changes to a Python file in claude/skills/

2. Ran git add . and git commit -m "test"

3. Confirmed tests executed and commit was blocked when tests failed

4. Fixed the test failure

5. Confirmed commit succeeded after tests passed

Fixes #15

```

Example 3: Agent Skill PR

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

PR:

```markdown

# [agent.skill][#67] Add open-pr skill for creating pull requests

Added the open-pr skill that guides AI agents through creating well-formatted

GitHub pull requests with proper tag selection and mandatory issue references.

• Created claude/skills/open-pr/ directory
• Added claude/skills/open-pr/SKILL.md with complete PR creation workflow
• Skill enforces issue number requirement in PR titles
• Includes comprehensive examples and error handling guidelines

• Added tests/test_open_pr_skill.py to verify:

- Skill file structure and format

- Tag selection logic correctness

- Issue number extraction from various formats

• Manually tested skill workflow:

1. Invoked open-pr skill in conversation

2. Verified it correctly extracted issue number from context

3. Confirmed it generated proper PR format

4. Tested error handling for missing issue numbers

Closes #67

```