feat: add GitHub workflow skills for PR enrichment and collaboration (#3)

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

.claude-plugin/marketplace.json

@@ -17,6 +17,14 @@
         "./skills/diataxis-gen-readme",
         "./skills/diataxis-organize-docs"
       ]
+    },
+    {
+      "name": "gh",
+      "description": "GitHub workflow skills for enriching PR descriptions, automating code review context, and streamlining collaboration through the gh CLI",
+      "source": "./",
+      "skills": [
+        "./skills/gh-enrich-pr-description"
+      ]
     }
   ]
 }

skills/gh-enrich-pr-description/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: gh-enrich-pr-description
+description: Enrich GitHub PR descriptions with root-cause context, related issues/PRs, and CC mentions. Use when creating or editing a PR, when a PR has an empty or sparse description, or when the user asks to improve a PR description.
+---
+
+# Enrich PR Description
+
+Analyze branch changes and git history to build a rich PR description with three sections: a contextual summary, related issues/PRs, and people to CC.
+
+## When to Use
+
+- User asks to create a PR (before `gh pr create`)
+- User asks to improve/fix a PR description
+- A PR has an empty or sparse body
+- User asks who to CC or what to reference
+
+## Workflow
+
+### 1. Gather Context
+
+Run these in parallel to understand the full picture:
+
+```bash
+# Current branch and diff against base
+git log --oneline main..HEAD
+git diff main...HEAD
+
+# PR if it already exists
+gh pr view --json number,title,body,url,baseRefName,headRefName 2>/dev/null
+```
+
+### 2. Investigate the "Why"
+
+For each changed file, dig into the history to understand the origin of the problem:
+
+```bash
+# Blame the changed lines on the base branch to find who introduced them
+git blame main -- <file> | sed -n '<start>,<end>p'
+
+# Show the originating commit
+git log -1 --format='%H %an <%ae> %s' <commit-sha>
+
+# Find the PR that introduced the commit
+gh pr list --search "<commit-sha-prefix> OR <ticket-id>" --state merged --json number,title,author,url
+```
+
+Key questions to answer:
+- What is the root cause of the problem?
+- Is this a permanent vs transient condition being mishandled?
+- What contract or convention was violated?
+- Is there a sibling/similar function that handles the same case correctly?
+
+### 3. Find Related Issues and PRs
+
+Search for related work using ticket IDs, keywords, and function names:
+
+```bash
+# By ticket ID from branch name or commit messages
+gh pr list --search "<TICKET-ID>" --state all --json number,title,author,url,state
+
+# By keywords from the change
+gh pr list --search "<keyword>" --state all --limit 10 --json number,title,author,url,state
+```
+
+Classify each related PR/issue:
+- **Origin** -- introduced the code being fixed
+- **Related** -- touches the same area or feature
+- **Alternate** -- different approach to the same problem
+- **Blocked by / Blocks** -- dependency relationship
+
+### 4. Identify People to CC
+
+From git blame and related PRs, collect GitHub usernames of people who:
+- Authored the code being changed (from `git blame`)
+- Authored related open PRs in the same area
+- Are reviewers on related PRs
+
+Extract GitHub usernames from PR data:
+
+```bash
+gh pr view <number> --json author --jq '.author.login'
+```
+
+### 5. Compose the Description
+
+Use this structure:
+
+```markdown
+## Summary
+
+[2-4 sentences explaining WHAT changed and WHY. Focus on the root cause
+and why the previous behavior was wrong. Include the mechanism of failure.]
+
+> [!NOTE]
+> [Optional callout for additional context, such as a sibling function
+> that handles the same case correctly, or a related convention.]
+
+## Related
+
+- #<number> -- <relationship>: <brief description>
+- #<number> -- <relationship>: <brief description>
+
+CC @<username> @<username>
+```
+
+### 6. Apply the Description
+
+For an existing PR:
+
+```bash
+gh pr edit <number> --body "$(cat <<'EOF'
+<composed description>
+EOF
+)"
+```
+
+For a new PR, pass it to `gh pr create --body`.
+
+## Quality Checks
+
+- [ ] Summary explains the root cause, not just the symptom
+- [ ] Summary describes the mechanism (how the bug manifests)
+- [ ] Related PRs include the one that introduced the issue
+- [ ] Each related PR has a relationship label (origin, related, alternate)
+- [ ] CC list includes the author of the originating code
+- [ ] No speculative CC -- only people with direct involvement