Skip to content

Commit d7e3488

Browse files
fboschfbosch
committed
docs(skills): expand ai-commit and ai-pr skill documentation
1 parent 468900b commit d7e3488

File tree

3 files changed

+290
-43
lines changed

3 files changed

+290
-43
lines changed

‎.agents/skills/ai-commit/SKILL.md‎

Lines changed: 99 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,107 @@
11
---
22
name: ai-commit
3-
description: Generate atomic Commitizen messages from staged diffs.
3+
description: Generate atomic Commitizen-style commit messages from staged git diffs. Use when the user asks to create a commit message, write a commit, or needs help with git commit messages. Automatically analyzes staged changes and produces properly formatted conventional commit messages with appropriate type, scope, and description.
44
---
55

6-
## Rules
7-
- Types: feat|fix|docs|style|refactor|perf|test|build|ci|chore.
8-
- Imperative mood ("add", "fix", "update", not "added", "fixes").
9-
- <72 chars total.
10-
- Describe this commit's staged changes only.
11-
- Be specific and atomic, like a changelog entry.
12-
- Focus on what changed in the diff, not branch name or prior work.
13-
- If a ticket number is provided in context, scope must be AB#<ticket>.
6+
# AI Commit Message Generator
7+
8+
Generate atomic, well-structured commit messages following Conventional Commits and Commitizen conventions.
9+
10+
## Commit Message Format
11+
12+
**Structure:**
13+
```
14+
<type>(<scope>): <subject>
15+
16+
[optional body]
17+
```
18+
19+
**Rules:**
20+
- Total length < 72 characters for subject line
21+
- Use imperative mood ("add", "fix", "update" - not "added", "fixes", "updating")
22+
- Be specific and atomic - describe exactly what this commit changes
23+
- Focus on the staged diff content, not branch names or prior work
24+
- Scope is optional but recommended for clarity
25+
26+
**Types:**
27+
- `feat`: New feature or functionality
28+
- `fix`: Bug fix
29+
- `docs`: Documentation changes only
30+
- `style`: Code style/formatting (no logic changes)
31+
- `refactor`: Code restructuring (no behavior change)
32+
- `perf`: Performance improvement
33+
- `test`: Adding or updating tests
34+
- `build`: Build system or dependencies
35+
- `ci`: CI/CD configuration changes
36+
- `chore`: Maintenance tasks
37+
38+
## Scope Guidelines
39+
40+
**When ticket numbers are provided:**
41+
- Use format: `AB#<ticket-number>`
42+
- Example: `fix(AB#50147): prevent null pointer in validation`
43+
44+
**When no ticket number:**
45+
- Use module/feature name
46+
- Examples: `feat(auth): add password reset`, `fix(api): handle timeout errors`
47+
48+
**When changes span multiple areas:**
49+
- Use broader scope or omit scope
50+
- Example: `refactor: standardize error handling across services`
1451

1552
## Examples
16-
- fix(AB#50147): prevent null pointer in user validation
17-
- feat(AB#50147): add email field to registration form
18-
- refactor(AB#50147): extract validation logic to helper function
19-
- test(AB#50147): add edge case tests for empty input
53+
54+
**Feature addition:**
55+
```
56+
feat(AB#50147): add email field to registration form
57+
58+
Include validation for email format and uniqueness check
59+
```
60+
61+
**Bug fix:**
62+
```
63+
fix(AB#50147): prevent null pointer in user validation
64+
65+
Add null check before accessing user.profile object
66+
```
67+
68+
**Refactoring:**
69+
```
70+
refactor(AB#50147): extract validation logic to helper
71+
72+
Move validation functions to utils/validators.ts for reuse
73+
```
74+
75+
**Test addition:**
76+
```
77+
test(AB#50147): add edge case tests for empty input
78+
79+
Cover null, undefined, and empty string scenarios
80+
```
81+
82+
**Documentation:**
83+
```
84+
docs(api): update authentication endpoint examples
85+
86+
Add JWT token format and refresh token flow details
87+
```
88+
89+
**Simple change:**
90+
```
91+
fix(AB#50271): correct timezone offset calculation
92+
```
93+
94+
## Process
95+
96+
1. **Analyze the staged diff** - Review what files changed and how
97+
2. **Determine the type** - Based on what changed (feat/fix/refactor/etc)
98+
3. **Identify the scope** - Use ticket number if available, otherwise module name
99+
4. **Write subject line** - Imperative, specific, < 50 chars
100+
5. **Add body if needed** - For complex changes, explain why or how (optional)
101+
6. **Verify format** - Check length, mood, and conventional commit structure
20102

21103
## Output
22-
- Commit message only; no markdown or explanations.
104+
105+
Provide ONLY the commit message text. No markdown formatting, no explanations, no preamble.
106+
107+
If the commit is simple, output just the subject line. If more context is needed, include a blank line and body.

‎.agents/skills/ai-pr/SKILL.md‎

Lines changed: 187 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,191 @@
11
---
22
name: ai-pr
3-
description: Generate concise PR descriptions from git diffs and commit context.
3+
description: Generate concise PR descriptions from git diffs and commit context. Use when the user asks to create a PR description, write a pull request summary, or needs help documenting changes for code review. Automatically analyzes git diffs and commit history to produce well-structured PR descriptions with summary, changes, testing info, and breaking changes.
44
---
55

6-
## Instructions
7-
- Omit trivial changes entirely (formatting-only, whitespace, comment removal, import reordering, empty lines).
8-
- Include only functional code changes, bug fixes that change behavior, new features, API/config changes, tests, significant docs.
9-
10-
## Language rules
11-
- Plain technical language (no marketing: avoid "enhanced", "optimized", "robust").
12-
- Lexical level = CEFR B1: short, common words; max 12 words per sentence.
13-
- Prefer simple verbs: added/removed/changed/fixed/updated.
14-
- Describe only what the diff or commits explicitly show; never guess intent.
15-
- For fixes: mention what was broken only if visible, plus how diff fixes it.
16-
- For other changes: state what changed from/to; include reasons only when explicitly stated.
17-
- Prefer lists; use backticks for `files`/`functions`/`APIs`.
18-
- Keep each bullet under 12 words for readability.
19-
20-
## Structure
21-
- Title: use commit type and ticket from context (present tense, concise).
22-
- Summary section: max 2 short sentences describing overall change.
23-
- Changes section: bullet list (max 5 items). Only substantive changes.
24-
- Testing section: bullet list; mention commands or "- Not stated".
25-
- Breaking Changes section: include only when diff obviously breaks behavior.
26-
27-
## Output
28-
**CRITICAL: Your response must contain ONLY the PR content below. Do not include ANY explanatory text, thoughts, analysis, or meta-commentary before or after the PR content.**
29-
30-
- First line is the PR title only.
31-
- Blank line after title.
32-
- Then markdown PR description using the provided section headings.
33-
- Do not output anything else.
6+
# AI Pull Request Description Generator
7+
8+
Generate clear, concise PR descriptions from git diffs and commit messages.
9+
10+
## Core Principles
11+
12+
**Focus on functional changes:**
13+
- Include code behavior changes, bug fixes, new features, API changes, tests
14+
- Omit trivial changes: formatting, whitespace, comment-only edits, import reordering
15+
16+
**Plain technical language:**
17+
- Avoid marketing terms ("enhanced", "optimized", "robust", "improved")
18+
- Use simple verbs: add, remove, change, fix, update
19+
- Keep sentences under 12 words
20+
- Use backticks for `files`, `functions`, `APIs`, `variables`
21+
22+
**Describe what is visible:**
23+
- Only describe what the diff or commits explicitly show
24+
- Never guess intent or future implications
25+
- State what changed from/to
26+
- Include reasons only when explicitly stated in commits
27+
28+
## PR Structure
29+
30+
```markdown
31+
[Type]([Ticket]): [Brief Description]
32+
33+
## Summary
34+
[1-2 sentences describing overall change]
35+
36+
## Changes
37+
- [Functional change 1]
38+
- [Functional change 2]
39+
- [Functional change 3]
40+
41+
## Testing
42+
- [Test approach or commands]
43+
- Not stated (if no testing info available)
44+
45+
## Breaking Changes
46+
- [Breaking change] (only if diff obviously breaks behavior)
47+
- None (if no breaking changes)
48+
```
49+
50+
## Title Format
51+
52+
Use commit type and ticket number from context:
53+
- `feat(AB#12345): add user authentication`
54+
- `fix(AB#12345): prevent null pointer in validation`
55+
- `refactor(AB#12345): extract helper functions`
56+
- `docs(AB#12345): update API examples`
57+
58+
If no ticket number:
59+
- `feat: add user authentication`
60+
- `fix: prevent crash on empty input`
61+
62+
## Writing Guidelines
63+
64+
**Summary section:**
65+
- Max 2 short sentences
66+
- Describe the overall goal or problem solved
67+
- Present tense, active voice
68+
69+
**Changes section:**
70+
- Max 5 bullets
71+
- Each bullet under 12 words
72+
- List only substantive functional changes
73+
- Order by importance/impact
74+
75+
**Testing section:**
76+
- List test commands run or test files added
77+
- Mention testing approach if stated in commits
78+
- Use "- Not stated" if no testing info available
79+
80+
**Breaking Changes section:**
81+
- Include only when diff obviously breaks existing behavior
82+
- Describe what breaks and how
83+
- Use "- None" if no breaking changes
84+
85+
## Examples
86+
87+
**Feature PR:**
88+
```
89+
feat(AB#50147): add email validation to registration
90+
91+
## Summary
92+
Add email format validation and uniqueness check to registration form.
93+
94+
## Changes
95+
- Add `validateEmail` function to `utils/validators.ts`
96+
- Update `RegistrationForm` to check email format
97+
- Add unique email constraint to database schema
98+
- Display error message for invalid or duplicate emails
99+
100+
## Testing
101+
- Run `npm test` for unit tests
102+
- Manual testing with valid/invalid email formats
103+
104+
## Breaking Changes
105+
- None
106+
```
107+
108+
**Bug Fix PR:**
109+
```
110+
fix(AB#50271): prevent null pointer in user profile
111+
112+
## Summary
113+
Fix crash when accessing user profile with missing data.
114+
115+
## Changes
116+
- Add null check before accessing `user.profile.avatar`
117+
- Set default avatar when profile image is missing
118+
- Update `ProfileCard` component error handling
119+
120+
## Testing
121+
- Add test case for users without profile data
122+
- Verify no crash with null profile
123+
124+
## Breaking Changes
125+
- None
126+
```
127+
128+
**Refactoring PR:**
129+
```
130+
refactor(AB#50198): extract validation to shared module
131+
132+
## Summary
133+
Move validation functions to shared module for reuse across forms.
134+
135+
## Changes
136+
- Create `utils/validators.ts` with shared functions
137+
- Update `LoginForm` to use shared validators
138+
- Update `RegistrationForm` to use shared validators
139+
- Remove duplicate validation code
140+
141+
## Testing
142+
- Existing tests pass with refactored code
143+
- No behavior changes
144+
145+
## Breaking Changes
146+
- None
147+
```
148+
149+
**PR with breaking changes:**
150+
```
151+
feat(AB#50299): migrate to new authentication API
152+
153+
## Summary
154+
Update authentication to use v2 API endpoints.
155+
156+
## Changes
157+
- Replace `/auth/login` with `/v2/auth/token` endpoint
158+
- Update auth response parsing for new format
159+
- Add token refresh flow
160+
- Update tests for new API
161+
162+
## Testing
163+
- Integration tests with v2 API
164+
- Manual testing of login and token refresh
165+
166+
## Breaking Changes
167+
- Old `/auth/login` endpoint no longer supported
168+
- Auth tokens now require refresh after 1 hour
169+
```
170+
171+
## Process
172+
173+
1. **Analyze git diff** - Review changed files and specific code changes
174+
2. **Review commit messages** - Extract context about intent and testing
175+
3. **Identify type and scope** - Determine PR type (feat/fix/refactor) and ticket number
176+
4. **Filter changes** - Exclude trivial formatting/whitespace changes
177+
5. **List functional changes** - Focus on behavior changes, max 5 bullets
178+
6. **Extract testing info** - From commits or test file changes
179+
7. **Check for breaking changes** - Look for API/behavior changes
180+
8. **Write concise description** - Follow structure, keep language simple
181+
182+
## Output Format
183+
184+
**CRITICAL:** Output ONLY the PR content. No explanatory text, thoughts, or meta-commentary.
185+
186+
1. First line: PR title only
187+
2. Blank line
188+
3. Markdown PR description with section headings
189+
4. Nothing else
190+
191+
Do not add any preamble like "Here's the PR description:" or any analysis afterward.

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ storybook-static
2727
.config/codex/config.toml
2828
.config/gtk-4.0/**/*
2929
.config/gtk-3.0/**/*
30+
.codex/**
31+
!.codex/skills/**/*
32+
.agents/skills/.system
3033

3134
# window state rules (auto-generated)
3235
.config/hypr/window-state-rules.conf
@@ -63,6 +66,7 @@ checkhealth.log
6366
*.swo
6467
*~
6568
*.bak
69+
*.backup
6670

6771
# Ignore log files
6872
*.log

0 commit comments

Comments
 (0)