agentleFS
it-bensit-bens/cc-port/.claude/skills/writing-pr-descriptions/SKILL.md

writing-pr-descriptions

Skill6 starsChanged 22 days agoMITView on GitHub

Use when drafting or rewriting the description for a cc-port pull request.

7 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions7 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 7

    1. PostHog/posthog★ 41ksame name
    2. PostHog/posthog-foss★ 731same name
    3. lox/agent-skills★ 15same name
    4. jamestexas/agents★ 2same name
    5. adamziel/Skills★ 1same name
    6. rliang/skills★ 0same name
    7. ViktorSoroka07/claude-delivery-skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Call in this order (gh-tooling MCP, not the gh CLI):

    line 80
  2. Very specific:

    If pr_view returns nothing, stop and report the PR number as not found.

    line 89
  3. Very specific:

    If the reason for the change is still unclear after reading the diff, ask the user via AskUserQuestion.

    line 149
  4. Very specific:

    Commit subjects are vague (fix, update, cleanup).

    line 153
  5. Distinctive:

    Search for em dash (—) and en dash (–).

    line 239
  6. Distinctive:

    Check for banned sentence patterns: "This PR introduces…", "It's worth noting…", contrastive reframes, summary openings.

    line 241

“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing PR Descriptions

Requirements

  • PR number: a positive integer. Ask if missing.
  • Working directory: cc-port repository root, on any branch (the data is fetched via gh-tooling, not the local working tree).
  • The PR must exist and be visible to the configured gh-tooling MCP.

Workflow

digraph pr_description {
    entry [shape=doublecircle, label="PR number?"];
    gather [shape=box, label="Gather"];
    pr_found [shape=diamond, label="pr_view\nreturned data?"];
    not_found [shape=octagon, style=filled, fillcolor=red, label="STOP:\nPR not found"];
    classify [shape=box, label="Classify files\nby module"];
    detect [shape=box, label="Detect change type"];
    confident [shape=diamond, label="Confidence\n>= MEDIUM?"];
    ask_type [shape=box, label="AskUserQuestion:\ntype + scope"];
    special [shape=box, label="Detect special cases"];
    is_dep [shape=diamond, label="Dep update?"];
    is_break [shape=diamond, label="Breaking?"];
    flag_break [shape=box, label="Require\nBreaking Changes"];
    filter [shape=box, label="Filter auxiliary\nchanges"];
    intent_clear [shape=diamond, label="Intent clear?"];
    ask_intent [shape=box, label="AskUserQuestion:\nintent"];
    route [shape=diamond, label="Route by type"];
    t_dep [shape=box, label="Dependency template"];
    t_ci [shape=box, label="CI template"];
    t_build [shape=box, label="Build/release template"];
    t_docs [shape=box, label="Documentation template"];
    t_std [shape=box, label="Standard template"];
    antislop [shape=box, label="Anti-slop pass"];
    clean [shape=diamond, label="Clean?"];
    present [shape=doublecircle, label="Present output"];

    entry -> gather;
    gather -> pr_found;
    pr_found -> not_found [label="no"];
    pr_found -> classify [label="yes"];
    classify -> detect;
    detect -> confident;
    confident -> ask_type [label="LOW"];
    ask_type -> special;
    confident -> special [label="HIGH/MEDIUM"];
    special -> is_dep;
    is_dep -> t_dep [label="yes"];
    is_dep -> is_break [label="no"];
    is_break -> flag_break [label="yes"];
    is_break -> filter [label="no"];
    flag_break -> filter;
    filter -> intent_clear;
    intent_clear -> ask_intent [label="no"];
    ask_intent -> route;
    intent_clear -> route [label="yes"];
    route -> t_ci [label="ci"];
    route -> t_build [label="build/release"];
    route -> t_docs [label="docs"];
    route -> t_std [label="feat/fix/\nrefactor/perf"];
    t_dep -> antislop;
    t_ci -> antislop;
    t_build -> antislop;
    t_docs -> antislop;
    t_std -> antislop;
    antislop -> clean;
    clean -> antislop [label="no, rewrite"];
    clean -> present [label="yes"];
}

Gather

Call in this order (gh-tooling MCP, not the gh CLI):

ToolPurpose
pr_viewTitle, body, labels, base/head refs, author
pr_filesChanged file list with status (added / modified / removed / renamed)
pr_diffThe actual diff text
pr_commitsCommit subjects on the PR

If pr_view returns nothing, stop and report the PR number as not found.

The full diff is the primary source. The description must not contain a change the diff does not show.

Classify files by module

Group the changed files. Modules are taken from AGENTS.md §Navigation; categories below add cross-cutting buckets.

CategoryPath patterns
CLIcmd/cc-port/**
move commandinternal/move/**
export commandinternal/export/**
import commandinternal/importer/**
Manifestinternal/manifest/**
Rewrite primitiveinternal/rewrite/**
Lock primitiveinternal/lock/**
Filesystem primitiveinternal/fsutil/**
Claude state primitiveinternal/tool/claude/**
Scan primitiveinternal/scan/**
UI primitiveinternal/ui/**
Other internalsinternal/** not matched above
Tests*_test.go, testdata/**
CI.github/workflows/**, .github/actions/**
Build / Release.goreleaser.yml, Makefile, packaging
Documentation*.md, docs/**, AGENTS.md, CLAUDE.md, README.md, DEVELOPMENT.md
Configgo.mod, go.sum, .golangci.yml, .editorconfig, repo-root configs

Detect change type

See references/type-detection.md for the decision tree, project-specific type guidance, scope rules, confidence levels, and breaking-change indicators. Apply the rules to the file classification from the previous step.

  • HIGH / MEDIUM confidence: use the type and scope directly.
  • LOW confidence: AskUserQuestion with the candidate types from the analysis. Confirm both type and scope before proceeding.

Detect special cases

Dependency-update PRs:

  • Author is renovate[bot] or dependabot[bot], or the change is exclusively go.mod / go.sum.
  • The dependency-update flag overrides the type-derived template.

Breaking changes: see the Breaking-Change Detection section in references/type-detection.md. When any indicator triggers, the description must include a ## Breaking Changes section with migration guidance regardless of which template is selected.

Filter auxiliary changes

Tests and documentation support the main change. They are not mentioned as items unless the PR is exclusively about them.

PR containsMention tests?Mention docs?
Only testsYesn/a
Only docsn/aYes
Code + testsNon/a
Code + docsNoNo
Code + tests + docsNoNo

A test or doc change that captures a behaviour change (a new invariant test, a new contract row in a module README) belongs in the description because it documents the contract, not the housekeeping. Use judgement.

Resolve unclear intent

If the reason for the change is still unclear after reading the diff, ask the user via AskUserQuestion. Do not guess.

Signs of unclear intent:

  • Commit subjects are vague (fix, update, cleanup).
  • Mixed changes across unrelated modules with no shared theme.
  • Deleted code with no obvious replacement.
  • Renames or moves with no explanation in the commits.

Apply template

Route by the type from "Detect change type" and the flags from "Detect special cases". The dependency-update flag overrides the type:

SelectorTemplate
Dependency-update flag setDependency
type=ciCI-only
type=build or type=releaseBuild/Release
type=docsDocumentation-only
otherwise (feat / fix / refactor / perf)Standard

Focus the Summary on user-visible effect (commands, flags, behaviour) rather than internal mechanics, unless the PR's whole point is the internal mechanic. Name specifics: function names, flag names, file paths, exact limits, not abstractions.

Standard:

## Summary

{1-3 sentences. Start with an action verb. State what changed and why it matters to a user of cc-port.}

## Changes

### {Category 1}

- {Bullet describing one change. Use specifics: command names, flag names, module names, exact behaviour.}
- {Another change in the same category.}

### {Category 2}

- {Change description.}

{If breaking changes:}

## Breaking Changes

{What breaks. Migration path. Include the before/after command or code snippet.}

CI-only:

## Summary

{One sentence describing the workflow or pipeline change and why.}

Build/Release:

## Summary

{One sentence describing the packaging, goreleaser, or build change and why.}

Documentation-only:

## Summary

{What was added or revised, and why. Reference the surface (README, docs/architecture.md, module README) by name.}

Dependency:

## Summary

Updates dependencies.

## Updated Dependencies

| Package | From | To |
|---|---|---|
| {package} | {old} | {new} |

Anti-slop pass

PR descriptions are user-facing prose. Re-read references/writing-rules-anti-ai-slop.md and check the draft literally:

  1. Search for em dash (—) and en dash (–). Remove every instance.
  2. Re-read each word against the banned vocabulary list.
  3. Check for banned sentence patterns: "This PR introduces…", "It's worth noting…", contrastive reframes, summary openings.
  4. Vary sentence rhythm.
  5. Replace abstractions with specifics: name the function, the flag, the file, the limit.

Rewrite affected text and re-check. Do not exit this step until the draft passes every check.

Present

Output:

  1. A header: **Suggested Title:** {type}({scope}): {subject} followed by file count and detected type.
  2. The description inside a fenced markdown block.
  3. Offer to copy the description (without fences) to the clipboard via pbcopy (macOS) or xclip -selection clipboard (Linux). Ask first.

The session's gh-tooling MCP is read-only. The user applies the description themselves; do not attempt to mutate the PR via gh-tooling or the gh CLI.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.