OSS Contribution Workflows

Overview

Facilitate GitHub-based open source contribution workflows including pull requests, issues, and discussions. This skill provides structured automation for common OSS contribution tasks, ensuring consistent formatting, proper metadata application, and adherence to repository conventions. Use this skill when contributing to open source projects or managing GitHub repositories through the command line.

The skill emphasizes semantic analysis over mechanical operations—understand the intent and context of changes before generating titles, descriptions, or selecting templates. All generated content should be conversational and informal rather than robotic or overly formal.

Prerequisites

Before using any OSS contribution workflow, verify GitHub CLI authentication status:

gh auth status

Ensure the output shows you are logged in to github.com with appropriate scopes (repo, read:org, etc.). If not authenticated, run:

gh auth login

For pull request workflows, also verify:

• Working tree is clean or changes are committed
• Current branch has commits ahead of the base branch
• Remote tracking is configured for the current branch

Related Skills

For detailed GitHub CLI command syntax, flags, and patterns, activate the gh-cli skill. That skill covers the full gh command surface including issue management, PR operations, repository queries, workflow triggers, and API interactions.

Pull Requests

Create GitHub pull requests with semantic change analysis and structured formatting. The workflow generates meaningful titles and descriptions by reading actual code changes rather than relying solely on commit messages or filenames.

Workflow Steps

Validate Prerequisites

Confirm git state before proceeding:

• Check git status for uncommitted changes
• Verify branch has commits ahead of base branch via git log
• Confirm remote tracking is configured
• Ensure gh CLI is authenticated

Parse Arguments

Support the following arguments:

• base-branch: Target branch for the PR (default: main/master)
• reviewers: Comma-separated list of GitHub usernames
• --draft: Create as draft PR
• --test-plan: Include test plan section in body

Semantic Change Analysis

Read the actual diff to understand what changed:

git diff base-branch...HEAD

Analyze:

• Nature of changes (feature, fix, refactor, docs, test, chore)
• Scope of impact (which components/modules affected)
• Intent and purpose (why the change was made)
• Dependencies or related changes

Generate Title and Body

Craft a concise title summarizing the change. Generate a body with:

• Summary section (1-3 bullet points explaining what and why)
• Test Plan section if --test-plan flag provided (bulleted checklist)
• GitHub admonitions (NOTE, TIP, IMPORTANT, WARNING, CAUTION) where appropriate

Pass the body using HEREDOC syntax:

gh pr create --title "the pr title" --body "$(cat <<'EOF'
## Summary
- First bullet point
- Second bullet point

## Test Plan
- [ ] Test item one
- [ ] Test item two
EOF
)"

Create Pull Request

Execute the gh command with all parsed flags and generated content. Include:

• --base for target branch
• --reviewer for each reviewer
• --draft if draft mode requested
• Return the PR URL to the user

For the complete pull request workflow with detailed steps, examples, and edge cases, refer to references/pull-requests.md.

Issues

Create GitHub issues with automatic template selection and label application. The workflow intelligently chooses the appropriate issue template based on the description content and applies relevant labels for repositories where you have write access.

Workflow Steps

Check for Issue Templates

Search the repository for issue templates:

ls -la .github/ISSUE_TEMPLATE/

Templates may be in YAML or Markdown format. Parse YAML frontmatter to extract:

• Template name
• Description
• Labels to auto-apply

Auto-Select Template

Analyze the issue description to determine the most appropriate template:

• Bug reports: errors, crashes, unexpected behavior
• Feature requests: enhancements, new functionality
• Documentation: docs improvements, clarifications
• Questions: how-to, usage inquiries

If no template matches or templates don't exist, proceed without one.

Apply Labels

For repositories where you have write access, apply labels using the --label flag:

gh issue create --label "bug" --label "needs-triage"

Extract labels from:

• Selected template metadata
• Issue description content (infer appropriate labels)

Support Similar Issue Search

When --check flag is provided, search for similar existing issues before creating:

gh issue list --search "search terms" --state all

Display results and ask user if they want to proceed with creation.

Create Issue

Execute the gh command with generated title, body, and metadata. Pass multi-line bodies using HEREDOC syntax. Return the issue URL to the user.

For the complete issue creation workflow with template examples, label strategies, and search patterns, refer to references/issues.md.

Claude Code Issues

Create issues specifically in the anthropics/claude-code repository with environment information gathering and specialized templates. This workflow is optimized for reporting bugs, requesting features, or improving documentation for Claude Code itself.

Workflow Steps

Identify Issue Type

Determine which template to use based on user intent:

• bug_report: Errors, crashes, unexpected behavior
• feature_request: New functionality or enhancements
• documentation: Docs improvements or clarifications
• model_behavior: Issues related to Claude's responses or reasoning

Gather Environment Information

Collect relevant environment details:

# Claude Code version
claude --version

# Operating system
uname -a

# Terminal emulator (macOS)
echo $TERM_PROGRAM

# Shell
echo $SHELL

Generate Issue Body

Create structured content following the selected template format:

• Clear description of the issue or request
• Steps to reproduce (for bugs)
• Expected vs actual behavior (for bugs)
• Environment information section
• Additional context or screenshots

Use GitHub admonitions for important callouts:

> [!IMPORTANT]
> This issue affects all macOS users on Apple Silicon

Create in anthropics/claude-code

Execute the gh command targeting the correct repository:

gh issue create \
  --repo anthropics/claude-code \
  --title "Issue title" \
  --body "$(cat <<'EOF'
Issue content here
EOF
)"

Return the issue URL to the user.

For the complete Claude Code issue workflow with template examples and environment gathering scripts, refer to references/issues-claude-code.md.

Codex CLI Issues

Create issues specifically in the openai/codex repository with environment information gathering and specialized templates. This workflow is optimized for reporting bugs, requesting features, improving documentation, or reporting VS Code extension issues for Codex CLI.

Workflow Steps

Identify Issue Type

Determine which template to use based on user intent:

• 2-bug-report: Errors, crashes, unexpected behavior in CLI
• 4-feature-request: New functionality or enhancements
• 3-docs-issue: Docs improvements or clarifications
• 5-vs-code-extension: Issues with the VS Code/Cursor/Windsurf extension

Gather Environment Information

Collect relevant environment details:

# Codex CLI version
codex --version

# Platform (macOS/Linux)
uname -mprs

# For VS Code extension issues
code --version

Generate Issue Body

Create structured content following the selected template format:

• Clear description of the issue or request
• Steps to reproduce (for bugs)
• Expected vs actual behavior (for bugs)
• Environment information section (version, platform, model, subscription)
• Additional context

Create in openai/codex

Execute the gh command targeting the correct repository:

gh issue create \
  --repo openai/codex \
  --title "Issue title" \
  --body "$(cat <<'EOF'
Issue content here
EOF
)"

Return the issue URL to the user.

For the complete Codex CLI issue workflow with template examples and environment gathering scripts, refer to references/issues-codex-cli.md.

Discussions

Create GitHub discussions using the GraphQL API with automatic category selection. Discussions are ideal for Q&A, ideas, announcements, and general community conversations that don't fit the issue format.

Workflow Steps

Fetch Repository Information

Query the repository to get its node ID:

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      id
    }
  }
' -f owner="OWNER" -f repo="REPO"

Fetch Discussion Categories

Query available categories for the repository:

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 10) {
        nodes {
          id
          name
          description
        }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO"

Auto-Select Category

Analyze the discussion title and body to choose the most appropriate category:

• Ideas: Feature suggestions, proposals, brainstorming
• Q&A: Questions seeking answers, how-to inquiries
• General: Broad discussions, community topics
• Announcements: Important updates (if you have permissions)
• Show and Tell: Demos, showcases, sharing work

If uncertain, default to "General" or ask the user to select.

Support Similar Discussion Search

When --check flag is provided, search for similar existing discussions:

gh api graphql -f query='
  query($owner: String!, $repo: String!, $search: String!) {
    repository(owner: $owner, name: $repo) {
      discussions(first: 5, orderBy: {field: CREATED_AT, direction: DESC}, filterBy: {query: $search}) {
        nodes {
          title
          url
        }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" -f search="search terms"

Display results and confirm before proceeding.

Create Discussion

Execute the GraphQL mutation to create the discussion:

gh api graphql -f query='
  mutation($repositoryId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {
      repositoryId: $repositoryId
      categoryId: $categoryId
      title: $title
      body: $body
    }) {
      discussion {
        url
      }
    }
  }
' -f repositoryId="REPO_ID" -f categoryId="CATEGORY_ID" -f title="Title" -f body="Body"

Return the discussion URL to the user.

For the complete discussion workflow with GraphQL examples, category selection logic, and search patterns, refer to references/discussions.md.

Common Patterns

Shared conventions and patterns used across all OSS contribution workflows.

HEREDOC for Multi-line Content

Always use HEREDOC syntax when passing multi-line bodies to gh commands:

gh pr create --title "Title" --body "$(cat <<'EOF'
First paragraph

Second paragraph
EOF
)"

The single quotes around 'EOF' prevent variable expansion, ensuring literal content is passed.

GitHub Admonitions

Use GitHub-flavored markdown admonitions to highlight important information:

> [!NOTE]
> Useful information that users should know

> [!TIP]
> Helpful advice for doing things better

> [!IMPORTANT]
> Key information users need to know

> [!WARNING]
> Urgent info that needs immediate attention

> [!CAUTION]
> Advises about risks or negative outcomes

Apply these judiciously—overuse reduces their impact.

Semantic Analysis Over Mechanical Operations

Never generate content based solely on filenames or commit messages. Always read the actual changes:

# Read the diff
git diff base-branch...HEAD

# Or for specific files
git diff base-branch...HEAD -- path/to/file

Understand:

• What changed (the mechanics)
• Why it changed (the intent)
• How it fits into the broader system (the context)

Use this understanding to craft meaningful titles and descriptions that communicate value, not just mechanics.

Informal Tone

Generated content should be conversational and approachable:

Good:

This PR adds support for parsing YAML frontmatter in issue templates. Previously, we only supported markdown format, which meant users couldn't take advantage of GitHub's newer template features.

Bad:

This pull request implements functionality for YAML frontmatter parsing in the issue template processing subsystem. The implementation enhances the system's capabilities regarding template format support.

Write like a human talking to another human, not like a technical specification.

Error Handling

When operations fail, provide clear context:

• What was being attempted
• What went wrong
• What the user should do to fix it

Example:

Failed to create PR: current branch has no commits ahead of main.

Make sure you've committed your changes and that your branch differs from the base branch.

Confirmation and Feedback

For destructive or significant operations:

• Show what will happen before executing
• Ask for confirmation when appropriate
• Provide clear feedback after completion

For search operations with --check:

• Display found items clearly
• Let the user decide whether to proceed
• Don't automatically skip creation if duplicates exist

Additional Resources

For detailed workflows, examples, and edge case handling, refer to these reference documents:

• references/pull-requests.md - Complete pull request workflow including git state validation, semantic analysis strategies, template examples, and reviewer management
• references/issues.md - Complete issue creation workflow including template parsing, label application strategies, and duplicate detection
• references/issues-claude-code.md - Claude Code-specific issue creation including all template formats, environment gathering scripts, and submission guidelines
• references/issues-codex-cli.md - Codex CLI-specific issue creation including bug reports, feature requests, docs issues, and VS Code extension templates
• references/issues-biome.md - Biome-specific issue creation including playground reproduction links, formatter/linter bug templates, and environment detection
• references/discussions.md - GitHub discussions workflow including GraphQL queries, category selection logic, and search strategies

These references provide implementation details, code examples, and troubleshooting guidance for each workflow type.