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:

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

## Summary

Provide a concise summary of what has been achieved in this PR. Focus on the
completed work and the value it delivers.

## Changes

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`

## Testing

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

## Related Issue

Closes #issue-number

(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:

# 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:

Search conversation history for explicit issue references:
- "for issue #42"
- "closes #15"
- "related to #23"
- GitHub issue URLs containing issue numbers
If no issue number is found in conversation:
- Check if there are recent issues that match this work:
```
gh issue list --limit 10
```
- Ask the user: "Which issue does this PR address? (Provide issue number)"

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:

# 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):

Get the current branch name:
```
git branch --show-current
```
Push the branch with tracking:
```
git push -u origin <branch-name>
```
Confirm to user: "Pushed branch to remote: origin/"

If the command succeeds (upstream branch exists):

Check if local is ahead of remote:
```
git status --porcelain --branch
```
If output contains [ahead N], push changes:
```
git push
```
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:

gh pr create --title "TITLE_HERE" --label "agentize:pr" \
--head ${REMOTE}/${CURRENT_BRANCH} \
--body-file - <<'EOF'
BODY_CONTENT_HERE
EOF

Important:

The PR targets --head $REMOTE/$DEFAULT_BRANCH, where upstream/master > upstream/main > origin/master > origin/main.
Use --body-file - with heredoc to preserve markdown formatting and handle special characters safely
The body should include all sections from Summary onwards (not the title)
The PR will be created against the default branch (usually main/master)
Always add the agentize:pr label to enable automatic PR management by the agentize server
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

7.5. Record PR Number in Session State

After successful PR creation, record the PR number in the session state to enable PR link in completion notifications.

Extract PR number from creation output: The gh pr create command outputs the PR URL upon success. Extract the PR number from this URL.

Record in session state:

from agentize.server.session import set_pr_number_for_issue

# Extract issue_no from the PR title (e.g., "[feat][#42] ..." -> 42)
# Extract pr_number from the PR URL (e.g., ".../pull/123" -> 123)
set_pr_number_for_issue(issue_no, pr_number)

Note: This is a best-effort operation. If the session state file is not available (e.g., not running in handsoff mode), the function returns False silently without affecting PR creation success.

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:

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

## Summary

Added support for generating TypeScript SDK templates in the agentize project.
Developers can now bootstrap TypeScript-based agent SDKs alongside existing
Python templates.

## Changes

- 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

## Testing

- 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

## Related Issue

Closes #42

Example 2: Bugfix PR

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

PR:

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

## Summary

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.

## Changes

- 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

## Testing

- 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

## Related Issue

Fixes #15

Example 3: Agent Skill PR

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

PR:

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

## Summary

Added the open-pr skill that guides AI agents through creating well-formatted
GitHub pull requests with proper tag selection and mandatory issue references.

## Changes

- 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

## Testing

- 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

## Related Issue

Closes #67