Comms Why

Explain why code is shaped the way it is, using git history, PRs, and connected MCP evidence, with citations and honest confidence. Use for "why does X work this way", "why did we pick Y", design rationale, regressions, and postmortems. Use comms-how for runtime behavior.

23 stars 1 forksGit & Code Review

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add jpoehnelt/skills --skill comms-why
Manual install
git clone --depth 1 https://github.com/jpoehnelt/skills.git /tmp/skills
mkdir -p ~/.claude/skills
cp -r /tmp/skills/comms-why ~/.claude/skills/comms-why

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Why

Investigate the motivation behind code. `comms-how` explains what code does. This skill explains what forces led to its shape. Be careful and precise. Separate what you know from what you infer.

Repo facts: where the repo keeps design records, ADRs, or plans, if anywhere (`AGENTS.md` or `CLAUDE.md`).

## 1. Pin the target and question

The target is a chunk of code, a pattern, or a named decision. If it is vague, pick the best interpretation from context, state it, and proceed.

## 2. Build the code anchor

Gather evidence with these commands. Capture long outputs in scratch files, then read bounded excerpts:

- `git blame -L <start>,<end> <file>` for the last-touch commits.
- `git log --follow --oneline -20 -- <file>` for recent history.
- `git log --follow -p -5 -- <file> > <history-file>` when patches matter. Read targeted excerpts from the saved file.
- `git log -1 --format=%B <sha>` for the full message. Look for PR numbers like `(#1234)` and issue IDs.
- PR bodies, reviews, and comments through the GitHub MCP tools (`pull_request_read`, `issue_read`, `search_pull_requests`). As an alternative when `gh` is available, save `gh pr view <number> --json title,body,comments,reviews > <pr-file>` and display a bounded selection:

```sh
jq '{title, body: .body[:4000], comments: [.comments[-10:][] | {url, body: .body[:1500]}], reviews: [.reviews[-5:][] | {state, body: .body[:1500]}]}' <pr-file>
```
Read the full skill on GitHub

Details

Skill name
comms-why
Path
comms-why/SKILL.md
License
MIT
Repo updated
12 November 2026

FAQ

What does the Comms Why skill do?

Explain why code is shaped the way it is, using git history, PRs, and connected MCP evidence, with citations and honest confidence. Use for "why does X work this way", "why did we pick Y", design rationale, regressions, and postmortems. Use comms-how for runtime behavior.

How do I install the Comms Why skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add jpoehnelt/skills --skill comms-why. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Comms Why popular?

It lives in jpoehnelt/skills, which has 23 GitHub stars and 1 forks.

Related skills

Agents Correct

23

jpoehnelt/skills

Find the mistakes agents keep repeating in a repo and make each one impossible, trying architecture first, then types, lint, tests, and docs last. Use when the operator keeps correcting the same mistake, or for /agents-correct.

AI, LLMs & Agents

Agents Create Verification Skill

23

jpoehnelt/skills

Generate a project-local verify skill that drives the app like a user through a browser with Playwright, a CLI, or HTTP. Use for /agents-create-verification-skill, "make a verify skill for this repo", or when a project has no scripted way to prove UI, CLI, or service behavior.

AI, LLMs & Agents

Agents Reflect

23

jpoehnelt/skills

After a work session, review what went wrong and right and turn each lesson into a concrete edit to an existing skill or AGENTS.md line. Use when the user says "reflect" or /agents-reflect.

AI, LLMs & Agents

Eng Cutover Verification

23

jpoehnelt/skills

Prove a migration, module split, library swap, datastore or deploy-tool cutover, compatibility removal, or multi-PR cleanup is complete. Use when retiring paths, adapters, dependencies, generated outputs, or config, validating merged main, or proving a rebase preserved a patch series.

Git & Code Review

Alterlab Pra PR Writer

21

AlterLab-IEU/AlterLab-FC-Skills

This skill should be used when the user asks about "press release", "media kit", "crisis communication", "PR writing", "public relations writing", "corporate communications", "media advisory", "speech writing", "spokesperson brief", "act as a PR writer", "PR writer mode", "media relations", "crisis statement", "internal communications", or needs expertise in writing professional public relations materials across all corporate communication formats. Part of the AlterLab FC Skills collection (Public Relations & Advertising department).

Git & Code ReviewIn 1 list

Gh CI Triage

23

jpoehnelt/skills

Diagnose failing GitHub Actions CI from log evidence and choose a fix, rerun, merge-forward, or escalation. Use when a PR or default-branch run is red, cancelled, or flaky, or a visual baseline or artifact is missing.

Git & Code Review

Browse the most popular Claude skills, all git & code review skills, or write your own with the skills generator.