github-project-skill

---
name: github-project
description: "GitHub repository setup and platform-specific features. This skill should be used when creating new GitHub repositories, configuring branch protection rules, setting up GitHub Issues/Discussions/Projects, creating sub-issues and issue hierarchies, managing PR review workflows, configuring Dependabot/Renovate auto-merge, setting up merge queues with GraphQL enqueuePullRequest mutations, or checking GitHub project configuration. Focuses on GitHub platform features, not CI/CD pipelines or language-specific tooling. By Netresearch."
---

# GitHub Project Skill

GitHub platform configuration and repository management patterns. This skill focuses exclusively on **GitHub-specific features**.

## 🔌 Compatibility

This is an **Agent Skill** following the [open standard](https://agentskills.io) originally developed by Anthropic and released for cross-platform use.

**Supported Platforms:**
- ✅ Claude Code (Anthropic)
- ✅ Cursor
- ✅ GitHub Copilot
- ✅ Other skills-compatible AI agents

> Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.


## Scope Boundaries

**This Skill Covers:**
- Branch protection rules and PR workflows
- CODEOWNERS configuration
- GitHub Issues, Discussions, Projects
- Sub-issues and issue hierarchies (parent/child relationships)
- Dependabot/Renovate auto-merge
- GitHub Releases configuration
- Repository collaboration features

**Delegate to Other Skills:**
- CI/CD pipelines → `go-development`, `php-modernization`, `typo3-testing`
- Security scanning (CodeQL, gosec) → `security-audit`
- SLSA, SBOMs, supply chain → `enterprise-readiness`
- Git branching strategies, conventional commits → `git-workflow`

## Triggers

**Setup & Configuration:**
- Creating a new GitHub repository
- "Check my GitHub project setup"
- "Configure branch protection"
- "Set up GitHub Issues/Discussions"
- "How do I require PR reviews?"
- "Auto-merge Dependabot PRs"
- "Configure CODEOWNERS"

**Sub-Issues & Issue Hierarchies:**
- "Create sub-issues"
- "Add child issues to parent"
- "Link issues as parent/child"
- "Break down issue into sub-tasks"
- "Set up issue hierarchy"
- "Convert checklist to sub-issues"

**Troubleshooting (PR Merge Blocked):**
- "PR can't be merged" / "merge is blocked"
- "unresolved conversations" / "unresolved comments"
- "required reviews not met"
- "CODEOWNERS review required"
- "status checks failed" (for branch protection context)
- `gh pr merge` returns error

**Troubleshooting (Auto-Merge Failures):**
- "auto-merge not working" / "Dependabot PR not merging"
- "Merge method squash merging is not allowed"
- "Merge method merge commit is not allowed"
- "required status check not found"
- "status check name mismatch"
- PRs stuck with auto-merge enabled
- "Protected branch rules not configured" (--auto requires branch protection)
- Merge queue not processing PRs

**Troubleshooting (Ruleset Conflicts):**
- "Rebase is not an allowed merge method"
- "Squash is not an allowed merge method"
- "Merge commit is not an allowed merge method"
- Ruleset merge method mismatch warning on PR

**Merge Queue Configuration:**
- "set up merge queue"
- "enqueuePullRequest"
- "auto-merge with merge queue"
- "GraphQL merge queue mutation"

**Branch Migration:**
- "rename master to main"
- "change default branch"
- "migrate from master"
- "prevent master branch"
- "block master from being created"

## Installation

### Marketplace (Recommended)

Add the [Netresearch marketplace](https://github.com/netresearch/claude-code-marketplace) once, then browse and install skills:

```bash
# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
```

### npx ([skills.sh](https://skills.sh))

Install with any [Agent Skills](https://agentskills.io)-compatible agent:

```bash
npx skills add https://github.com/netresearch/github-project-skill --skill github-project
```

### Download Release

Download the [latest release](https://github.com/netresearch/github-project-skill/releases/latest) and extract to your agent's skills directory.

### Git Clone

```bash
git clone https://github.com/netresearch/github-project-skill.git
```

### Composer (PHP Projects)

```bash
composer require netresearch/github-project-skill
```

Requires [netresearch/composer-agent-skill-plugin](https://github.com/netresearch/composer-agent-skill-plugin).
## Workflows

### New Repository Setup

To set up a new GitHub repository:

1. Create essential files: README.md, LICENSE, SECURITY.md
2. Configure `.github/` directory structure (see `references/repository-structure.md`)
3. Set up branch protection on `main` branch
4. Configure CODEOWNERS for automatic reviewer assignment
5. Create issue and PR templates
6. Enable Dependabot or Renovate for dependency updates
7. Configure auto-merge workflow for dependency PRs
8. Set up release notes configuration

Run verification: `./scripts/verify-github-project.sh /path/to/repo`

### Branch Configuration

**Required branch settings:**

| Setting | Value | Rationale |
|---------|-------|-----------|
| Default branch name | `main` | Industry standard |
| Default branch protected | ✅ | Prevent direct pushes |
| Allowed merge method | **Merge commits only** | Preserve complete history |
| Delete branch on merge | ✅ | Keep repo clean |

To configure via GitHub CLI:

```bash
# Ensure default branch is named "main"
gh api repos/{owner}/{repo} --jq '.default_branch'

# Configure merge settings (merge commits only, delete on merge)
gh repo edit --enable-merge-commit --disable-rebase-merge --disable-squash-merge --delete-branch-on-merge
```

**Note:** If you prefer rebase merging for linear history, use `--enable-rebase-merge --disable-merge-commit` instead. Ensure consistency with any GitHub Rulesets (see [Rulesets Configuration](#github-rulesets-configuration)).

### Repository Settings

**Complete repository settings:**

| Setting | Value | Rationale |
|---------|-------|-----------|
| Allow merge commits | ✅ | With PR title and description |
| Allow squash merging | ❌ | Preserve commit granularity |
| Allow rebase merging | ❌ | Use merge queue instead |
| Automatically delete head branches | ✅ | Keep repo clean |
| Allow auto-merge | ✅ | Enable merge queue integration |
| Always suggest updating PR branches | ✅ | Keep PRs up-to-date with base |
| Discussions | ✅ | Community Q&A |
| Wikis | ❌ | Use docs folder instead |

**Configure via CLI:**

```bash
# Configure all repository settings
gh repo edit \
  --enable-merge-commit \
  --disable-squash-merge \
  --disable-rebase-merge \
  --delete-branch-on-merge \
  --enable-auto-merge \
  --enable-discussions \
  --disable-wiki

# Set merge commit message format (PR title and description)
gh api repos/{owner}/{repo} \
  --method PATCH \
  -f merge_commit_title=PR_TITLE \
  -f merge_commit_message=PR_BODY

# Enable "always suggest updating PR branches"
gh api repos/{owner}/{repo} \
  --method PATCH \
  -F allow_update_branch=true
```

**Important:** Do NOT enable `required_linear_history` when using merge commits. Linear history requires fast-forward merges only (no merge commits). If you see "not authorized to push" errors, check if `required_linear_history` is enabled and disable it.

### Renaming "master" to "main"

For complete migration steps from `master` to `main` as default branch, see `references/branch-migration.md`.

Quick start:
```bash
git branch -m master main
git push -u origin main
gh repo edit --default-branch main
git push origin --delete master
```

### Branch Protection Configuration

To configure branch protection via GitHub CLI:

```bash
# View current protection
gh api repos/{owner}/{repo}/branches/main/protection

# Set branch protection
gh api repos/{owner}/{repo}/branches/main/protection \
  --method PUT \
  -f required_status_checks='{"strict":true,"contexts":["test","lint"]}' \
  -f enforce_admins=true \
  -f required_pull_request_reviews='{"required_approving_review_

[truncated…]