Skip to content

Commit 05c098a

Browse files
shatakshiiiishatakshiiii
committed
feat: add agent skills for PR workflows and cross-repo sync
Add pr-new, pr-review, pr-contributor-review, and tox skills adapted from ansible/apme. Add sync-skills workflow to propagate skills weekly to 10 consumer repos. Related: AAP-44292
1 parent 442c6e7 commit 05c098a

7 files changed

Lines changed: 796 additions & 0 deletions

File tree

‎.agents/skills/README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Agent Skills
2+
3+
Agent skills for development workflow automation in team-devtools.
4+
5+
## Available Skills
6+
7+
### Pull Requests (`pr-*`)
8+
9+
| Skill | Purpose | Arguments |
10+
|-------|---------|-----------|
11+
| `pr-new` | Prepare and submit a pull request | `[branch-name] [--title 'PR title']` |
12+
| `pr-review` | Handle PR review feedback | `<PR number>` |
13+
| `pr-contributor-review` | Review and prepare a contributor's PR (upstream/fork) | `<PR number or URL>` |
14+
15+
### Utilities
16+
17+
| Skill | Purpose | Arguments |
18+
|-------|---------|-----------|
19+
| `tox` | tox environment reference (lint, test, docs, pkg) | `[environment-name]` |
20+
21+
## Skill Structure
22+
23+
```
24+
skills/
25+
├── README.md ← You are here
26+
├── pr-new/
27+
│ └── SKILL.md
28+
├── pr-review/
29+
│ └── SKILL.md
30+
├── pr-contributor-review/
31+
│ └── SKILL.md
32+
└── tox/
33+
└── SKILL.md
34+
```
35+
36+
## SKILL.md Format
37+
38+
Each skill has YAML frontmatter:
39+
40+
```yaml
41+
---
42+
name: skill-name
43+
description: >-
44+
What the skill does. When to use it. Trigger phrases.
45+
argument-hint: "[expected arguments]"
46+
user-invocable: true
47+
metadata:
48+
author: Ansible DevTools Team
49+
version: 1.0.0
50+
---
51+
```
52+
53+
## Version
54+
55+
- **Version**: 1.0.0
56+
- **Author**: Ansible DevTools Team
57+
- **License**: GPL-3.0-or-later

‎.agents/skills/pr-contributor-review/SKILL.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
name: pr-contributor-review
3+
description: >
4+
Use when reviewing and preparing a contributor's pull request (upstream or
5+
fork). Use when the user asks to review a PR, get a contributor PR ready,
6+
update a contributor's branch, or ensure a PR meets project standards before
7+
merge.
8+
argument-hint: "<PR number or URL>"
9+
user-invocable: true
10+
metadata:
11+
author: Ansible DevTools Team
12+
version: 1.0.0
13+
---
14+
15+
# Review Contributor PR
16+
17+
This skill defines how to review and assist with a **contributor's** pull
18+
request (someone else's PR, e.g. from a fork or another branch). Use it when
19+
you are helping make a contributor PR merge-ready, not when submitting your
20+
own PR (use `pr-new` for that).
21+
22+
## Goals
23+
24+
- PR is **up to date with upstream main** (no merge conflicts, clean rebase).
25+
- **Quality gates pass**: `tox -e lint` and `tox -e py` on the full tree.
26+
- **PR description** follows the project template (Summary, Changes, Test plan)
27+
so reviewers and history have clear context.
28+
- Avoid pushing to the contributor's branch with failing CI or an outdated base.
29+
30+
## Workflow
31+
32+
### 1. Fetch PR metadata and diff
33+
34+
Use the GitHub API or `gh pr view` to get:
35+
36+
- PR number, title, body, base/head refs, author.
37+
- List of changed files and patch/diff.
38+
39+
Confirm the **base** branch (e.g. `ansible:main`) and that you know which
40+
remote/branch you will push to if you make changes.
41+
42+
### 2. Check if the branch is up to date with upstream
43+
44+
- Fetch `upstream main` (or the base branch).
45+
- Compare base ref of the PR to current `upstream/main`. If upstream has
46+
newer commits, the contributor's branch should be rebased (or merged) onto
47+
`upstream/main` before merge.
48+
49+
If you are going to push changes to the contributor's branch (e.g. adding
50+
fixes or improving the PR):
51+
52+
- Rebase the **local** branch that mirrors their PR onto `upstream/main`
53+
before pushing. That way the PR stays mergeable and CI runs against the
54+
latest main.
55+
56+
### 3. Run quality gates before pushing
57+
58+
Run tox quality gates on the **entire** tree, not only the changed files:
59+
60+
```bash
61+
tox -e lint
62+
tox -e py
63+
```
64+
65+
Fix any failures (line length, untyped decorators, docstring sections, format,
66+
test regressions) before pushing to the contributor's branch.
67+
68+
Do **not** run `ruff`, `mypy`, `pytest`, or `prek` directly — always use tox.
69+
See the `/tox` skill for the full environment reference.
70+
71+
Do **not** push to the contributor's branch if tox fails; fix in a new commit
72+
and then push so CI stays green.
73+
74+
### 4. PR description quality
75+
76+
- If the PR body is minimal or missing structure, suggest or apply the
77+
**pr-new** template: Summary, Changes, Test plan.
78+
79+
- You can update the PR body via GitHub (if you have permission) or draft
80+
text for the maintainer/contributor to paste:
81+
82+
```bash
83+
gh pr edit <N> --repo ansible/team-devtools --body-file path/to/body.md
84+
```
85+
86+
- Keep the description accurate: list what changed and how to verify (tests,
87+
manual steps).
88+
89+
### 5. Pushing to the contributor's branch
90+
91+
- Only push to the contributor's fork/branch if you have permission and the
92+
user has asked you to.
93+
94+
- Before pushing:
95+
96+
1. Rebase onto `upstream/main` so the PR is up to date.
97+
2. Ensure `tox -e lint` and `tox -e py` pass (see step 3).
98+
3. Use `--force-with-lease` when pushing a rebased branch:
99+
`git push <remote> <local-branch>:<their-branch> --force-with-lease`.
100+
101+
- After pushing, the PR will update automatically. Optionally update the PR
102+
description to mention the new commits.
103+
104+
### 5a. Comment on review threads
105+
106+
When you push fixes that address a review comment, reply on that thread so
107+
the resolution is visible. Follow the **`pr-review`** skill for the full
108+
procedure (REST reply endpoint, finding comment IDs, GraphQL thread resolution).
109+
110+
### 5b. Track all deferred work as issues
111+
112+
When reviewing a contributor PR, any suggestion that work should happen in a
113+
follow-up PR — whether from you, the contributor, or another reviewer — **MUST**
114+
be captured as a GitHub issue immediately. Do not leave "TODO for later" or
115+
"out of scope, will address separately" without creating an issue. Untracked
116+
follow-ups are invisible debt.
117+
118+
```bash
119+
gh issue create --repo ansible/team-devtools \
120+
--title "<type>(scope): <description from review>" \
121+
--body "$(cat <<'EOF'
122+
## Context
123+
124+
<What was deferred and why>
125+
126+
Flagged during review of PR #N: <link to comment>
127+
128+
## Proposal
129+
130+
<What should be done>
131+
132+
EOF
133+
)"
134+
```
135+
136+
Include the issue URL in the PR comment thread so reviewers can verify tracking.
137+
138+
### 6. What not to include in the review
139+
140+
- **Local-only or environment-specific issues** (e.g. commit signing, SSH
141+
config, IDE settings) should not be part of the contributor-PR review
142+
checklist unless they are project policy. Document those separately or in
143+
maintainer docs if needed.
144+
145+
## Checklist (quick reference)
146+
147+
When reviewing or preparing a contributor PR:
148+
149+
- [ ] Fetched PR and know base/head and remotes.
150+
- [ ] Branch is up to date with upstream main (rebase if needed before push).
151+
- [ ] `tox -e lint` and `tox -e py` pass.
152+
- [ ] PR description has Summary, Changes, and Test plan (pr-new style).
153+
- [ ] If pushing to their branch: rebase onto upstream main, tox green, then
154+
`git push <remote> <local>:<their-branch> --force-with-lease`.
155+
- [ ] If you addressed a review comment: follow the `pr-review` skill to reply
156+
on the thread with explanation + commit SHA and resolve it.
157+
158+
## References
159+
160+
- **tox skill** (`/tox`): Full tox environment reference.
161+
- **pr-new** skill: PR body template and commit conventions.
162+
- **pr-review** skill: Responding to review comments and resolving threads.
163+
- **AGENTS.md**: Commit message standards and static check requirements.

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

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
name: pr-new
3+
description: >
4+
Prepare and submit a pull request. Syncs with upstream,
5+
creates a feature branch, runs quality gates (tox -e lint, tox -e py),
6+
updates documentation as needed, commits with conventional commits,
7+
then creates the PR via gh. Use when the user asks to submit, create, or open
8+
a pull request, or says "submit PR", "open PR", "create PR", "new PR".
9+
argument-hint: "[branch-name] [--title 'PR title']"
10+
user-invocable: true
11+
metadata:
12+
author: Ansible DevTools Team
13+
version: 1.0.0
14+
---
15+
16+
# PR New
17+
18+
## Workflow
19+
20+
### Step 1: Sync with upstream and create a feature branch
21+
22+
Always start from the latest upstream main:
23+
24+
```bash
25+
git fetch upstream
26+
git checkout -b <branch-name> upstream/main
27+
```
28+
29+
Use a descriptive branch name (e.g., `feat/add-jira-labels`, `fix/check-constraints`).
30+
31+
If changes already exist on the current branch (e.g., from an in-progress session), cherry-pick or rebase them onto the new branch.
32+
33+
### Step 2: Run quality gates
34+
35+
```bash
36+
tox -e lint
37+
tox -e py
38+
```
39+
40+
**Both must pass cleanly on the full tree** — not just the files you changed.
41+
If the branch has pre-existing violations (e.g., from an old base), rebase onto `upstream/main` first.
42+
43+
Do **not** run `ruff`, `mypy`, `prek`, or `pytest` directly — always use tox.
44+
See the `/tox` skill for the full environment reference.
45+
46+
### Step 3: Update documentation
47+
48+
Check whether your changes affect areas covered by existing docs. Update any that apply:
49+
50+
| Doc | When to update |
51+
|-----|----------------|
52+
| `README.md` | Project overview, dependency diagrams, setup changes |
53+
| `docs/guides/` | New dev workflows, guide additions |
54+
| `docs/stats/` | Statistics or metrics changes |
55+
56+
### Step 4: Commit with conventional commits
57+
58+
Use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format:
59+
60+
```
61+
<type>[optional scope]: <description>
62+
63+
[optional body]
64+
65+
[optional footer(s)]
66+
```
67+
68+
Common types for this project:
69+
70+
| Type | When to use |
71+
|------|-------------|
72+
| `feat` | New feature (CLI command, workflow, utility) |
73+
| `fix` | Bug fix |
74+
| `docs` | Documentation only |
75+
| `style` | Code style/formatting (no logic change) |
76+
| `refactor` | Code restructuring (no feature or fix) |
77+
| `test` | Adding or updating tests |
78+
| `build` | Build system, dependencies |
79+
| `ci` | CI/CD configuration |
80+
| `chore` | Maintenance tasks |
81+
82+
Scopes reflect project areas: `jira`, `check`, `docs`, `ci`, `deps`, `config`.
83+
84+
Examples:
85+
- `feat(jira): add bulk issue creation support`
86+
- `fix(check): handle missing platform constraints gracefully`
87+
- `docs: update release process guide`
88+
- `ci: add Python 3.14 to test matrix`
89+
90+
Include ticket references in the commit footer:
91+
- `Fixes: #123` for GitHub issues
92+
- `Related: AAP-123` for JIRA tickets
93+
- Do not use URLs — use plain text references
94+
95+
### Step 5: Push and create the pull request
96+
97+
```bash
98+
git push -u origin HEAD
99+
100+
gh pr create --repo ansible/team-devtools --title "conventional commit style title" --body "$(cat <<'EOF'
101+
## Summary
102+
- Concise description of what changed and why
103+
104+
## Changes
105+
- List of notable changes
106+
107+
## Test plan
108+
- [ ] `tox -e lint` passes
109+
- [ ] `tox -e py` passes
110+
- [ ] Docs updated (if applicable)
111+
EOF
112+
)"
113+
```
114+
115+
The PR targets upstream's `main` branch from the fork. Return the PR URL to the user.
116+
117+
### Maintaining the PR
118+
119+
When pushing additional commits to an existing PR, **always update the PR body** to reflect the new changes:
120+
121+
```bash
122+
gh pr edit <pr-number> --body "$(cat <<'EOF'
123+
...updated body...
124+
EOF
125+
)"
126+
```
127+
128+
The Summary, Changes, and Test plan sections must stay current with all commits on the branch, not just the initial one.
129+
130+
### Responding to review feedback
131+
132+
After pushing the PR, reviewers (human or Copilot) may leave comments. Follow
133+
the **`pr-review`** skill for the full procedure: checking CI status, replying
134+
to comments, resolving threads, and re-checking for new Copilot reviews.

0 commit comments

Comments
 (0)