Skip to content

Commit 0de9658

Browse files
feat: add contributor-pr-description skill (#190)
* feat: add contributor-pr-description skill * fix: explicit configuration for new skill * fix: add internal metadata to skill
1 parent 6fe4e74 commit 0de9658

3 files changed

Lines changed: 59 additions & 0 deletions

File tree

‎tool/dart_skills_lint/.agents/skills/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
*.log
44

55
# Un-ignore specific checked-in skills
6+
!contributor-pr-description/
67
!add-dart-lint-validation-rule/
78
!check-downstream-consumers/
89
!dart-skills-lint-integration/
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
name: contributor-pr-description
3+
description: Guidelines and format for writing pull request descriptions in this repository. Use this skill whenever the user asks you to draft a pull request description, submit a PR, or update a PR description.
4+
metadata:
5+
internal: true
6+
---
7+
8+
# Pull Request Description Guidelines
9+
10+
When writing a pull request (PR) description, your goal is to provide reviewers with enough context to understand what you did, why you did it, and how they can verify it. A good PR description speeds up the review process and serves as documentation for future contributors.
11+
12+
## Identity Verification
13+
14+
If you are in an environment where there are multiple GitHub identities (e.g., an AI agent identity and a primary user identity), **you must verify your identity before pushing or creating a PR**.
15+
16+
Before committing, pushing, or opening a PR, ensure you are using the identity that the user expects based on the type of work and the repository you are working on. Verify your active GitHub CLI auth (`gh auth status`) and ensure your Git commit author (`git commit --author="..."`) matches the correct identity for the task.
17+
18+
## PR Description Template
19+
20+
Always use the following template (or a very similar structure) when drafting a PR description:
21+
22+
```markdown
23+
## Summary
24+
[Provide a clear, 1-2 sentence summary of what this PR does.]
25+
26+
## Motivation and Context
27+
[Explain why this change is necessary. What problem does it solve? If it's a bug fix, what was the broken behavior?]
28+
29+
## Related Issues
30+
[If this PR fixes an open issue, link to it using keywords. e.g., "Fixes #123" or "Closes #456". If it relates to an issue but doesn't close it, use "Related to #789".]
31+
32+
## What changed
33+
[Optional: Provide a bulleted list of the most important technical changes made in the code. This is useful for larger PRs.]
34+
- Added `FooClass` to handle XYZ.
35+
- Updated `BarMethod` to return `Result`.
36+
37+
## Testing Instructions
38+
[Explain how reviewers can test your changes locally. Mention any manual verification steps.]
39+
- Run `dart test` to ensure all tests pass.
40+
- [Any specific manual testing steps]
41+
42+
```
43+
44+
## Tone and Style
45+
46+
1. **Be clear and concise**: Avoid rambling. Use bullet points for readability.
47+
2. **Focus on the "Why"**: The diff shows *what* changed. The description should explain *why* it changed.
48+
3. **Be professional**: Use natural, accessible language.
49+
50+
## Examples of Bad vs Good Summaries
51+
52+
**Bad**: "Fixed the bug." (Too vague, doesn't explain what bug)
53+
**Bad**: "Changed line 42 in `main.dart` to use `foo` instead of `bar`." (Focuses too much on the code, which is visible in the diff)
54+
55+
**Good**: "Fixes a crash when the user clicks 'Submit' without entering an email address by adding validation to the input form." (Explains the problem and the solution)

‎tool/dart_skills_lint/dart_skills_lint.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,7 @@ dart_skills_lint:
3535
- path: ".agents/skills/definition-of-done"
3636
rules:
3737
prevent-skills-sh-publishing: error
38+
- path: ".agents/skills/contributor-pr-description"
39+
rules:
40+
prevent-skills-sh-publishing: error
3841

0 commit comments

Comments
 (0)