feat: add agent skills for PR workflows and cross-repo sync

.agents/skills/README.md

@@ -0,0 +1,57 @@
+# Agent Skills
+
+Agent skills for development workflow automation in team-devtools.
+
+## Available Skills
+
+### Pull Requests (`pr-*`)
+
+| Skill | Purpose | Arguments |
+|-------|---------|-----------|
+| `pr-new` | Prepare and submit a pull request | `[branch-name] [--title 'PR title']` |
+| `pr-review` | Handle PR review feedback | `<PR number>` |
+| `pr-contributor-review` | Review and prepare a contributor's PR (upstream/fork) | `<PR number or URL>` |
+
+### Utilities
+
+| Skill | Purpose | Arguments |
+|-------|---------|-----------|
+| `tox` | tox environment reference (lint, test, docs, pkg) | `[environment-name]` |
+
+## Skill Structure
+
+```
+skills/
+├── README.md                   ← You are here
+├── pr-new/
+│   └── SKILL.md
+├── pr-review/
+│   └── SKILL.md
+├── pr-contributor-review/
+│   └── SKILL.md
+└── tox/
+    └── SKILL.md
+```
+
+## SKILL.md Format
+
+Each skill has YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: >-
+  What the skill does. When to use it. Trigger phrases.
+argument-hint: "[expected arguments]"
+user-invocable: true
+metadata:
+  author: Ansible DevTools Team
+  version: 1.0.0
+---
+```
+
+## Version
+
+- **Version**: 1.0.0
+- **Author**: Ansible DevTools Team
+- **License**: GPL-3.0-or-later

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

@@ -0,0 +1,163 @@
+---
+name: pr-contributor-review
+description: >
+  Use when reviewing and preparing a contributor's pull request (upstream or
+  fork). Use when the user asks to review a PR, get a contributor PR ready,
+  update a contributor's branch, or ensure a PR meets project standards before
+  merge.
+argument-hint: "<PR number or URL>"
+user-invocable: true
+metadata:
+  author: Ansible DevTools Team
+  version: 1.0.0
+---
+
+# Review Contributor PR
+
+This skill defines how to review and assist with a **contributor's** pull
+request (someone else's PR, e.g. from a fork or another branch). Use it when
+you are helping make a contributor PR merge-ready, not when submitting your
+own PR (use `pr-new` for that).
+
+## Goals
+
+- PR is **up to date with upstream main** (no merge conflicts, clean rebase).
+- **Quality gates pass**: `tox -e lint` and `tox -e py` on the full tree.
+- **PR description** follows the project template (Summary, Changes, Test plan)
+  so reviewers and history have clear context.
+- Avoid pushing to the contributor's branch with failing CI or an outdated base.
+
+## Workflow
+
+### 1. Fetch PR metadata and diff
+
+Use the GitHub API or `gh pr view` to get:
+
+- PR number, title, body, base/head refs, author.
+- List of changed files and patch/diff.
+
+Confirm the **base** branch (e.g. `ansible:main`) and that you know which
+remote/branch you will push to if you make changes.
+
+### 2. Check if the branch is up to date with upstream
+
+- Fetch `upstream main` (or the base branch).
+- Compare base ref of the PR to current `upstream/main`. If upstream has
+  newer commits, the contributor's branch should be rebased (or merged) onto
+  `upstream/main` before merge.
+
+If you are going to push changes to the contributor's branch (e.g. adding
+fixes or improving the PR):
+
+- Rebase the **local** branch that mirrors their PR onto `upstream/main`
+  before pushing. That way the PR stays mergeable and CI runs against the
+  latest main.
+
+### 3. Run quality gates before pushing
+
+Run tox quality gates on the **entire** tree, not only the changed files:
+
+```bash
+tox -e lint
+tox -e py
+```
+
+Fix any failures (line length, untyped decorators, docstring sections, format,
+test regressions) before pushing to the contributor's branch.
+
+Do **not** run `ruff`, `mypy`, `pytest`, or `prek` directly — always use tox.
+See the `/tox` skill for the full environment reference.
+
+Do **not** push to the contributor's branch if tox fails; fix in a new commit
+and then push so CI stays green.
+
+### 4. PR description quality
+
+- If the PR body is minimal or missing structure, suggest or apply the
+  **pr-new** template: Summary, Changes, Test plan.
+
+- You can update the PR body via GitHub (if you have permission) or draft
+  text for the maintainer/contributor to paste:
+
+  ```bash
+  gh pr edit <N> --repo ansible/team-devtools --body-file path/to/body.md
+  ```
+
+- Keep the description accurate: list what changed and how to verify (tests,
+  manual steps).
+
+### 5. Pushing to the contributor's branch
+
+- Only push to the contributor's fork/branch if you have permission and the
+  user has asked you to.
+
+- Before pushing:
+
+  1. Rebase onto `upstream/main` so the PR is up to date.
+  2. Ensure `tox -e lint` and `tox -e py` pass (see step 3).
+  3. Use `--force-with-lease` when pushing a rebased branch:
+     `git push <remote> <local-branch>:<their-branch> --force-with-lease`.
+
+- After pushing, the PR will update automatically. Optionally update the PR
+  description to mention the new commits.
+
+### 5a. Comment on review threads
+
+When you push fixes that address a review comment, reply on that thread so
+the resolution is visible. Follow the **`pr-review`** skill for the full
+procedure (REST reply endpoint, finding comment IDs, GraphQL thread resolution).
+
+### 5b. Track all deferred work as issues
+
+When reviewing a contributor PR, any suggestion that work should happen in a
+follow-up PR — whether from you, the contributor, or another reviewer — **MUST**
+be captured as a GitHub issue immediately. Do not leave "TODO for later" or
+"out of scope, will address separately" without creating an issue. Untracked
+follow-ups are invisible debt.
+
+```bash
+gh issue create --repo ansible/team-devtools \
+  --title "<type>(scope): <description from review>" \
+  --body "$(cat <<'EOF'
+## Context
+
+<What was deferred and why>
+
+Flagged during review of PR #N: <link to comment>
+
+## Proposal
+
+<What should be done>
+
+EOF
+)"
+```
+
+Include the issue URL in the PR comment thread so reviewers can verify tracking.
+
+### 6. What not to include in the review
+
+- **Local-only or environment-specific issues** (e.g. commit signing, SSH
+  config, IDE settings) should not be part of the contributor-PR review
+  checklist unless they are project policy. Document those separately or in
+  maintainer docs if needed.
+
+## Checklist (quick reference)
+
+When reviewing or preparing a contributor PR:
+
+- [ ] Fetched PR and know base/head and remotes.
+- [ ] Branch is up to date with upstream main (rebase if needed before push).
+- [ ] `tox -e lint` and `tox -e py` pass.
+- [ ] PR description has Summary, Changes, and Test plan (pr-new style).
+- [ ] If pushing to their branch: rebase onto upstream main, tox green, then
+      `git push <remote> <local>:<their-branch> --force-with-lease`.
+- [ ] If you addressed a review comment: follow the `pr-review` skill to reply
+      on the thread with explanation + commit SHA and resolve it.
+
+## References
+
+- **tox skill** (`/tox`): Full tox environment reference.
+- **pr-new** skill: PR body template and commit conventions.
+- **pr-review** skill: Responding to review comments and resolving threads.
+- **AGENTS.md**: Commit message standards and static check requirements.

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

@@ -0,0 +1,134 @@
+---
+name: pr-new
+description: >
+  Prepare and submit a pull request. Syncs with upstream,
+  creates a feature branch, runs quality gates (tox -e lint, tox -e py),
+  updates documentation as needed, commits with conventional commits,
+  then creates the PR via gh. Use when the user asks to submit, create, or open
+  a pull request, or says "submit PR", "open PR", "create PR", "new PR".
+argument-hint: "[branch-name] [--title 'PR title']"
+user-invocable: true
+metadata:
+  author: Ansible DevTools Team
+  version: 1.0.0
+---
+
+# PR New
+
+## Workflow
+
+### Step 1: Sync with upstream and create a feature branch
+
+Always start from the latest upstream main:
+
+```bash
+git fetch upstream
+git checkout -b <branch-name> upstream/main
+```
+
+Use a descriptive branch name (e.g., `feat/add-jira-labels`, `fix/check-constraints`).
+
+If changes already exist on the current branch (e.g., from an in-progress session), cherry-pick or rebase them onto the new branch.
+
+### Step 2: Run quality gates
+
+```bash
+tox -e lint
+tox -e py
+```
+
+**Both must pass cleanly on the full tree** — not just the files you changed.
+If the branch has pre-existing violations (e.g., from an old base), rebase onto `upstream/main` first.
+
+Do **not** run `ruff`, `mypy`, `prek`, or `pytest` directly — always use tox.
+See the `/tox` skill for the full environment reference.
+
+### Step 3: Update documentation
+
+Check whether your changes affect areas covered by existing docs. Update any that apply:
+
+| Doc | When to update |
+|-----|----------------|
+| `README.md` | Project overview, dependency diagrams, setup changes |
+| `docs/guides/` | New dev workflows, guide additions |
+| `docs/stats/` | Statistics or metrics changes |
+
+### Step 4: Commit with conventional commits
+
+Use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Common types for this project:
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature (CLI command, workflow, utility) |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Code style/formatting (no logic change) |
+| `refactor` | Code restructuring (no feature or fix) |
+| `test` | Adding or updating tests |
+| `build` | Build system, dependencies |
+| `ci` | CI/CD configuration |
+| `chore` | Maintenance tasks |
+
+Scopes reflect project areas: `jira`, `check`, `docs`, `ci`, `deps`, `config`.
+
+Examples:
+- `feat(jira): add bulk issue creation support`
+- `fix(check): handle missing platform constraints gracefully`
+- `docs: update release process guide`
+- `ci: add Python 3.14 to test matrix`
+
+Include ticket references in the commit footer:
+- `Fixes: #123` for GitHub issues
+- `Related: AAP-123` for JIRA tickets
+- Do not use URLs — use plain text references
+
+### Step 5: Push and create the pull request
+
+```bash
+git push -u origin HEAD
+
+gh pr create --repo ansible/team-devtools --title "conventional commit style title" --body "$(cat <<'EOF'
+## Summary
+- Concise description of what changed and why
+
+## Changes
+- List of notable changes
+
+## Test plan
+- [ ] `tox -e lint` passes
+- [ ] `tox -e py` passes
+- [ ] Docs updated (if applicable)
+EOF
+)"
+```
+
+The PR targets upstream's `main` branch from the fork. Return the PR URL to the user.
+
+### Maintaining the PR
+
+When pushing additional commits to an existing PR, **always update the PR body** to reflect the new changes:
+
+```bash
+gh pr edit <pr-number> --body "$(cat <<'EOF'
+...updated body...
+EOF
+)"
+```
+
+The Summary, Changes, and Test plan sections must stay current with all commits on the branch, not just the initial one.
+
+### Responding to review feedback
+
+After pushing the PR, reviewers (human or Copilot) may leave comments. Follow
+the **`pr-review`** skill for the full procedure: checking CI status, replying
+to comments, resolving threads, and re-checking for new Copilot reviews.