From Git Commits to Coherent Narratives: A Claude Skill

Every Friday, the same ritual. Open GitHub. Click through repositories. Scan commit history. Check closed issues. Review merged PRs. Piece together what I actually accomplished this week. Write it up in a way that makes sense to someone who wasn’t in the trenches.

It takes 30 minutes on a light week. An hour when things were busy. And the output is always the same: a list of bullet points that somehow fails to capture the actual work.

I built a Claude skill to fix this. Run /github-summary, answer a few questions, and get a narrative document that explains what you did and wh, with inline URLs and actual paragraphs that connect the dots.

The insight behind it: AI tools are most useful when they bridge information silos. GitHub has all the data; issue descriptions, PR reviews, commit messages, timelines. But that data is scattered across pages, repositories, and time. The skill doesn’t do anything a human couldn’t do. It just handles the tedious part: gathering context from multiple sources and holding it all in memory while synthesising.

The Problem With Lists

The typical work summary looks like this:

- Merged PR #312
- Fixed bug in auth flow
- Reviewed PR #320
- Updated documentation
- Closed issues #234, #238, #241

This is technically accurate and completely useless. It doesn’t explain that PR #312 was a security improvement prompted by issue #234, which you discovered while investigating user reports of random logouts. It doesn’t mention that the documentation update was a downstream consequence of the auth changes. The connections are lost.

What stakeholders actually want:

This week I focused on authentication security. I identified a session handling bug affecting Safari users (#234), implemented a fix using PKCE flow (#312), and updated our documentation to reflect the new authentication architecture. I also reviewed the rate limiting middleware (#320) which complements the auth work by preventing brute force attacks.

Now this version tells a story. It shows cause and effect. It demonstrates understanding of how pieces fit together. It’s also tedious to write manually because you need to remember those connections or reconstruct them from commit timestamps.

What the Skill Produces

Here’s an excerpt from a real summary the skill generated:

Key Accomplishments
The week prioritised security enhancements and stability improvements. The team implemented OAuth 2.0 PKCE support for mobile applications while resolving a critical Safari session bug affecting roughly 15% of the user base.
Main Initiatives
Authentication Upgrade: The primary effort involved implementing OAuth 2.0 PKCE (Proof Key for Code Exchange) for mobile applications, replacing the legacy implicit flow. This work spanned multiple repositories and required updates to both backend systems and client SDKs.
Safari Bug Resolution: Investigation revealed that Safari’s ITP blocking session cookies when set without correct SameSite attributes caused unexpected logouts. The solution implemented proper cookie configuration and a fallback mechanism for affected browsers.

The full output includes contribution metrics, notable technical work, and inline links to every PR and issue mentioned. The skill writes it; you review and refine.

What the Skill Does

The /github-summary skill automates the reconstruction. It:

Asks for scope - Which organisation? What time period?
Fetches activity - Issues created, PRs authored, PRs reviewed, commits
Gathers context - Comments, linked items, review feedback, sub-issues
Synthesises narrative - Claude writes the summary with inline URL references

The output includes a TLDR section for quick scanning, then detailed sections for Issues, Pull Requests (authored and reviewed), and Commits. Everything links back to GitHub.

Technical Decisions

Building this taught me things about GitHub’s API that I didn’t expect.

The `--involves` Discovery

My first version only found issues I created. The query was simple:

gh search issues --author @me --owner <org> --created "<start>..<end>"

But this missed tracking issues. When someone else creates an issue and assigns it to you, or you comment on it extensively, that’s still your work. The fix was adding a second query:

gh search issues --involves @me --owner <org> --updated "<start>..<end>"

The --involves flag catches issues where you’re assigned, mentioned, or commented. Merging both queries (and deduplicating) gives a complete picture.

Why Natural Language Output

I considered structured output. Tables. JSON. Markdown checklists. But the use case demanded prose.

Work summaries go to humans. Managers. Stakeholders. Performance review documents. These contexts reward narrative over data. A table of PR numbers is less useful than a paragraph explaining why those PRs matter.

The skill instructs Claude to write in first person, connect related items, and explain significance rather than just listing facts. The TLDR section satisfies the “just give me bullets” crowd while the full narrative serves everyone else.

The Skill Definition

Claude skills live in .claude/skills/<name>/SKILL.md. The file contains instructions that Claude follows when you invoke the skill. Here’s the structure:

---
name: github-summary
description: Generate AI-synthesised summaries of your GitHub activity...
---

# GitHub Summary

## Instructions

### 1. Check Data Source Availability
[Check for MCP tools, fall back to gh CLI]

### 2. Fetch Available Organisations
[Query user's orgs, build selection list]

### 3. Ask for Organisation
[Use AskUserQuestion tool]

### 4. Ask for Time Period
[Last 7/14/30 days, this month, custom]

### 5. Phase 1: Discover Activity Items
[Search queries for issues, PRs, commits]

### 6. Phase 2: Fetch Deep Context
[Get comments, reviews, linked items]

### 7. Synthesise and Write Summary
[Writing guidelines, template structure]

The full skill is ~400 lines of markdown. Most of that is the gh CLI commands and writing guidelines. The structure matters: Claude needs explicit instructions about what to fetch and how to write.

Using It

Installation is one command:

mkdir -p .claude/skills/github-summary
curl -o .claude/skills/github-summary/SKILL.md \
  https://raw.githubusercontent.com/gokhanarkan/claude-github-summary/main/SKILL.md

Then invoke it:

/github-summary

Or use natural language:

Summarise my GitHub activity for the last two weeks

Claude handles the rest. The output lands in your Inbox folder (if you have one) or current directory.

The Pattern Generalises

This skill covers GitHub because that’s where my work happens. But the architecture extends: any workflow where you gather information from multiple sources and synthesise it into coherent output is a candidate.

Meeting notes from calendar + email + Slack. Project status from Jira + GitHub + documentation. Customer feedback from support tickets + surveys + social media.

MCP servers make this practical. Each server exposes a platform’s data through a standard interface. Want to add Linear issues to your summary? Connect the Linear MCP server, add a few lines of instructions to the skill, done. The skill format is just markdown. The MCP servers handle authentication and API complexity. You write the synthesis logic in plain English.

Technical Details

If you’re curious about the implementation: the skill supports two data sources.

Aspect	MCP Server	gh CLI
Setup	Requires configuration	Just `gh auth login`
Context depth	Richer (native tool access)	Requires extra API calls
Speed	Faster for large queries	More network round trips
Debugging	Opaque	Transparent commands

MCP Server is generally better, but gh CLI is useful when you want to see exactly what queries are running. The skill documents both approaches.

Bonus: Copilot Compatibility

The same skill file runs on GitHub Copilot CLI. Just place it in .github/skills/ instead of .claude/skills/. Each AI interprets instructions differently: Claude follows stylistic guidance precisely (producing prose), while Copilot gravitates toward structured formats. If narrative matters, Claude delivers more reliably.

Get the Skill

The skill is open source:

Repository: gokhanarkan/claude-github-summary
Community: Submitted to awesome-claude-skills

Clone it, modify the writing guidelines to match your style, and stop spending Friday afternoons reconstructing what you already did.

Found a bug? Have an idea for improvement? Open an issue or submit a PR. I’d particularly like to hear how you’ve customised the output format for your team’s needs.

URLs in this post: