Fu-Jie_openwebui-extensions/.agent/skills/pr-submitter/SKILL.md

name, description

name	description
pr-submitter	Submits a feature branch as a Pull Request with a validated, properly formatted bilingual PR body. Handles shell-escape-safe body writing via temp files. Use after release-prep has committed all changes.

PR Submitter

Overview

This skill handles the final step of pushing a feature branch and creating a validated Pull Request on GitHub. Its primary purpose is to avoid the shell-escaping pitfalls (backticks, special characters in gh pr create --body) by always writing the PR body to a temp file first.

Prerequisites

• All changes are committed (use release-prep skill first)
• The gh CLI is authenticated (gh auth status)
• Current branch is NOT main or master

---

Workflow

Step 0 — Initialize Temp Directory (Project-Based)

For all temporary files, use the project's .temp/ directory instead of system /tmp:

# Create temp directory if it doesn't exist
mkdir -p .temp

Why: All temporary files stay within the project workspace, avoiding system /tmp pollution and better aligning with OpenWebUI workspace isolation principles.

Step 1 — Pre-Flight Checks

Run these checks before any push:

# 1. Confirm not on protected branch
git branch --show-current

# 2. Verify there are commits to push
git log origin/$(git branch --show-current)..HEAD --oneline 2>/dev/null || echo "No remote tracking branch yet"

# 3. Check gh CLI auth
gh auth status

If any check fails, stop and report clearly.

Step 2 — Collect PR Metadata

Gather:

• PR Title: Must follow Conventional Commits format, English only (e.g., feat(github-copilot-sdk): release v0.8.0 with conditional tool filtering)
• Target base branch: Default is main
• Plugin name + version (to build body sections)
• Key changes (reuse from release-prep or the latest What's New section)

Step 3 — Build PR Body File (Shell-Escape-Safe)

Always write the body to a temp file in .temp/ directory. Never embed multi-line markdown with special characters directly in a shell command.

cat > .temp/pr_body.md << 'HEREDOC'
## Summary

Brief one-sentence description of what this PR accomplishes.

## Changes

### New Features
- Feature 1 description
- Feature 2 description

### Bug Fixes
- Fix 1 description

## Plugin Version
- `PluginName` bumped to `vX.X.X`

## Documentation
- README.md / README_CN.md updated
- docs/ mirrors synced

## Testing
- [ ] Tested locally in OpenWebUI
- [ ] i18n validated (all language keys present)
- [ ] Version consistency check passed (`python3 scripts/check_version_consistency.py`)

---

## 变更摘要（中文）

简要描述本次 PR 的改动内容。

### 新功能
- 功能1描述
- 功能2描述

### 问题修复
- 修复1描述
HEREDOC

Critical rules for the body file:

• Use << 'HEREDOC' (quoted heredoc) to prevent variable expansion
• Keep all backticks literal — they are safe inside a heredoc
• Paths like /api/v1/files/ are safe too since heredoc doesn't interpret them as commands

Step 4 — Validate PR Body

Before submitting, verify the body file contains expected sections:

# Check key sections exist
grep -q "## Summary" .temp/pr_body.md && echo "✅ Summary" || echo "❌ Summary missing"
grep -q "## Changes" .temp/pr_body.md && echo "✅ Changes" || echo "❌ Changes missing"
grep -q "## 变更摘要" .temp/pr_body.md && echo "✅ CN Section" || echo "❌ CN Section missing"

# Preview the body
cat .temp/pr_body.md

Ask the user to confirm the body content before proceeding.

Step 5 — Push Branch

git push -u origin $(git branch --show-current)

If push is rejected (non-fast-forward), report to user and ask whether to force-push. Do NOT force-push without explicit confirmation.

Step 6 — Create Pull Request

gh pr create \
  --base main \
  --head $(git branch --show-current) \
  --title "<PR title from Step 2>" \
  --body-file .temp/pr_body.md

Always use --body-file, never --body with inline markdown.

Step 7 — Verify PR Creation

PAGER=cat GH_PAGER=cat gh pr view --json number,url,title,body --jq '{number: .number, url: .url, title: .title, body_preview: .body[:200]}'

Confirm:

• PR number and URL
• Title matches intended Conventional Commits format
• Body preview includes key sections (not truncated/corrupted)

If the body appears corrupted (empty sections, missing backtick content), use edit:

gh pr edit <PR-NUMBER> --body-file /tmp/pr_body.md

Step 8 — Cleanup

rm -f .temp/pr_body.md

Note: The .temp/ directory itself is preserved for reuse; only the individual PR body file is deleted. To fully clean up: rm -rf .temp/

Report final PR URL to the user.

---

Shell-Escape Safety Rules

Risk	Safe Approach
Backticks in --body	Write to file, use --body-file
Paths like /api/...	Safe in heredoc; risky in inline --body
Newlines in --body	File-based only
$variable expansion	Use << 'HEREDOC' (quoted)
Double quotes in body	Safe in heredoc file
Temp file storage	Use .temp/ dir, not /tmp
Cleanup after use	Always delete temp file (keep dir)

---

Anti-Patterns to Avoid

• ❌ Never use --body "..." with multi-line content directly in shell command
• ❌ Never interpolate variables directly into heredoc without quoting the delimiter
• ❌ Never force-push (--force) without explicit user confirmation
• ❌ Never target main as the source branch (only as base)
• ❌ Never skip the body validation step — a PR with empty body is worse than a delayed PR