Skip to content
Skills Library
Programming · Review & audit

validate-pr-description

/validate-pr-description

Validate a PR title and body against conventional commit format, issue-linking keywords, and template compliance before submission. Use when you say `validate my PR description`, `check my PR title`, or `is this PR body compliant`. Do NOT use to open, update, or push a PR (use the github skill or push-pr), and do NOT use to review the code diff (use review).

Repository
ai-agents ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Validate a PR title and body against conventional commit format, issue-linking keywords, and template compliance before submission. Use when you say `validate my PR description`, `check my PR title`, or `is this PR body compliant`. Do NOT use to open, update, or push a PR (use the github skill or push-pr), and do NOT use to review the code diff (use review).

Arguments

/validate-pr-description [pr-title path-to-body-file]
Original author description

Validate a PR title and body against conventional commit format, issue-linking keywords, and template compliance before submission. Use when you say `validate my PR description`, `check my PR title`, or `is this PR body compliant`. Do NOT use to open, update, or push a PR (use the github skill or push-pr), and do NOT use to review the code diff (use review).

How it works

  1. Triggers
  2. Inputs
  3. Process
  4. Verification
  5. Anti-Patterns
  6. Extension Points
Original SKILL.md headings · 126 lines, 1,107 words
SKILL.md preview
---
name: validate-pr-description
version: 1.0.0
description: Validate a PR title and body against conventional commit format, issue-linking keywords, and template compliance before submission. Use when you say `validate my PR description`, `check my PR title`, or `is this PR body compliant`. Do NOT use to open, update, or push a PR (use the github skill or push-pr), and do NOT use to review the code diff (use review).
license: MIT
argument-hint: '[pr-title path-to-body-file]'
user-invocable: true
---

# Validate PR Description

Check a PR title and body against the three things this repository's gates read:
the conventional-commit title, the issue-linking keyword, and the template
sections the spec-coverage job parses. Catch them before submission, where the
fix costs one edit instead of one CI round.

Migrated from `.claude/commands/validate-pr-description.md` under ADR-064, which
makes skills the single user-invocable surface. `user-invocable: true` is what
fires it as `/validate-pr-description` in both Claude Code and Copilot CLI.

## Triggers

`validate my PR description`, `check my PR title`, `is this PR body compliant`,
`validate PR metadata`

## Inputs

| Input | Source | Required |
|-------|--------|----------|
| PR title | `$0`, or stated in conversation | Yes |
| PR body | `$1` as a path to a file, or pasted text | Yes |
| Target repository | current checkout | Yes |

## Process

### Phase 1: Resolve the inputs

Read the title and body from the arguments when given. When they are not, ask for
both rather than inferring them from the branch or the last commit: a PR body is
usually longer than any commit message, and validating the wrong text reports a
pass that does not describe the PR.

When the body arrives as a path, read the file. When it arrives as pasted text,
work from the text directly.

### Phase 2: Run the three checks

| # | Check | Rule | Failure meaning |
|---|-------|------|-----------------|
| 1 | Conventional commit title | `<type>(<scope>)?: <description>`, type one of `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `revert` | Release tooling cannot classify the change |
| 2 | Issue-linking keyword | body holds at least one of `Closes #N`, `Fixes #N`, `Resolves #N`, or a past-tense variant | The issue stays open after merge, and the PR fails the repository's issue-linkage rule |
| 3 | Template compliance | Summary non-empty, Changes has at least one item, Type of Change has at least one marked checkbox | The spec-coverage job reports FAIL on an unpopulated section |

Prefer the repository's own validator when it ships one, because it is the same
code the gate runs. Resolve the script root through a plugin-root variable so the
invocation works in a plugin install and not only in the upstream checkout:

```bash
SCRIPTS_DIR="${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr"
uv run python "$SCRIPTS_DIR/validate_pr_description.py" \
  --title "[title]" \
  --body-file "[path-to-body.md]"
```

When that script is absent, validate manually against the table above. Say which
path you took: a manual pass and a validator pass are not the same evidence.

### Phase 2b: Check file mentions against the diff

When the body is a file and the checkout ships `scripts/validation/pr_description.py`,
run its local mode. It runs the same file-mention check the required
`Validate PR` check runs, so a pass here rules out a `File mentioned but not in
diff` failure. It does not cover the dash or closing-keyword checks. Local mode
reads committed `HEAD`, so commit first:

```bash
uv run --frozen python -I scripts/validation/pr_description.py --body-file "[path-to-body.md]" --base origin/main
```

Exit 1 is a CRITICAL finding, usually `File mentioned but not in diff`. Report the
path and the fix: remove it, move it out of the change heading (`## Changes`,
`## What changed`, and the like), or wrap it in a code fence. With no change
heading, a bold or bulleted path counts anywhere, so remove or fence it. Do not
suggest the `description-validation-bypass` label; a human maintainer decides
that. Exit 2 means the check could not run: an unreadable or non-UTF-8 body
file, an unknown or invalid base ref, or git unavailable. For a missing
`origin/main`, pass `--base` with the ref the PR targets.
When the script is absent, or the body is pasted text with no file, say this
check was not run.

### Phase 3: Report

Report per check, not as a single verdict. For each failure give the offending
text and the corrected form, so the author edits rather than re-derives.

A closing keyword is a claim that the PR closes the issue. Verify it against the
diff before recommending one. When the diff does not deliver what the issue asks,
recommend `Refs #N` and say why, rather than upgrading a reference the merge will
act on.

## Verification

- [ ] Title checked against the conventional-commit pattern, and the type named
- [ ] Body searched for every accepted issue-linking keyword, not just `Closes`
- [ ] All three template sections inspected, with the failing one named
- [ ] Validator path stated: the repository script ran, or the check was manual
- [ ] File mentions checked against the diff with `pr_description.py --body-file`, or the check stated as not run
- [ ] Every failure reported with its offending text and a corrected form
- [ ] Any recommended closing keyword checked against the diff first

## Anti-Patterns

| Avoid | Why | Instead |
|-------|-----|---------|
| Inferring the title from the branch name or last commit | Validates text that is not the PR's, and reports a pass the PR does not have | Ask for the title and body |
| Reporting one aggregate verdict | The author cannot tell which of the three checks failed | Report per check |
| Recommending `Closes #N` because the PR mentions the issue | A closing keyword acts on merge; an unsupported one closes live work | Verify against the diff, downgrade to `Refs #N` with a reason |
| Rewriting the body wholesale | The author loses their own wording to a style preference | Name the failing section and the minimal edit |
| Calling a manual pass a validator pass | Two different levels of evidence read as one | State which ran |

## Extension Points

- **New title types.** The type list mirrors the repository's commit convention.
  When that convention gains a type, update the Phase 2 table and the validator
  together, not one of them.
- **New template sections.** The three checked sections are the ones the
  spec-coverage job parses. A new parsed section is a new row, not new prose.
- **Other forges.** The keyword list is GitHub and GitLab behavior. On Azure
  DevOps and Bitbucket the same keywords are traceability markers with no
  auto-close, so a missing keyword is a weaker finding there.

<!-- vendor-portability-exec: Phase 2b runs scripts/validation/pr_description.py, an upstream-only script a plugin install lacks. The allowed-tools grant names the same command. The phase says what to report then. Issue #6405. -->
<!-- vendor-portability: Phase 2b and its allowed-tools grant name scripts/validation/pr_description.py only for checkouts that carry it, and reports the check as not run otherwise. Issue #6405. -->

Versions

RepositoryScoreLicence
This page · rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT

Identical content appears in 4 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version c4f90d31d97b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100v1-pr-description
    Use when writing or updating a GitHub PR title or description. Triggers on "write PR description", "update PR body", or "PR title".
  • 100gh-pr-metadata
    Update the current GitHub PR title and body for this repository so they match the repo's pull request template and conventional-commit title style. Use when a PR title is vague or misformatted, when the PR body is missing required sections or checklist items, when Codex needs to…
  • 100pr-creation
    MUST be used when creating pull requests. Handles context gathering, title generation (conventional commit format), body formatting, and PR creation via GitHub CLI. Creates PRs as drafts by default. Triggers on: 'create PR', 'open PR', 'ready for review', 'push for PR', 'send for review'.
  • 100pr-description
    Use when writing a pull request title or body, when about to run gh pr create, when about to git push on a branch that already has an open PR, or when the user says /pr-description, "write the PR description", or "update the PR title". Don't use for commit messages, changelogs, or review comments.
  • 90pr-description
    Drafts pull request title and body from validated diff and opens or updates PR via GitHub MCP. Triggers when a change is ready to open or update a PR.
  • 100github-title-description
    This skill should be used when drafting or rewriting a GitHub PR title and/or description. It produces a user-impact title (not conventional-commits formatted) and a Why / What / Test Plan body with optional Breaking changes / Related issues sections. Use both for fresh drafts…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.