# Pr Maestro

> Single-entry PR automation skill using Python tools for tag, PR creation, and template application with deterministic behavior.

- Skill: `samuel-venturin/pr-maestro` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add samuel-venturin/pr-maestro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samuel-venturin/pr-maestro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: samuel-venturin (https://skillmd.com/u/samuel-venturin)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/samuel-venturin/pr-maestro

---


# PR Maestro Skill

Use this as the single skill for PR automation when the user asks to:
- create or update pull requests with repository template;
- automate tag + PR flow;
- avoid manual trial-and-error with gh commands.

## Runtime model

All logic must run through Python scripts in:
- `~/.claude/skills/pr-maestro/tools`

Central configuration lives in:
- `~/.claude/skills/pr-maestro/tools/config.json`

`pr_maestro.py` is the entrypoint and applies runtime policy from config (including Python bytecode behavior for spawned Python tools).

Do not manually reconstruct the workflow in chat when these scripts are available.

## Tools

- `pr_maestro.py`: end-to-end orchestrator (recommended entrypoint)
- `pr_create_or_get.py`: idempotent PR creation (create if missing, return if existing)
- `pr_template_apply.py`: apply `.github/pull_request_template.md` to an existing PR via REST patch

## Default execution

```bash
python3 ~/.claude/skills/pr-maestro/tools/pr_maestro.py --base develop --bump auto
```

Behavior note:
- PR create/update flow is enabled by default.
- Use `--no-create-or-update-pr` only when you want tag-only execution.
- Bytecode writing is disabled by default via config (`python.writeBytecode=false`).
- PR body generation is always refined (context-aware, no generic TODO placeholders).
- Quality gate runs by default before PR update/create.
- Quality gate commands are picked automatically per project type via `quality.profiles` in
  `config.json` — detected by a marker file/glob at the repo root: `package.json` → Node profile
  (`pnpm coverage`, `pnpm run typecheck`, `pnpm run lint`); `*.sln` → .NET profile (`dotnet build -c
  Release`, `dotnet test -c Release`). Falls back to `quality.defaultProfile`, and if no profile
  matches at all, to the legacy flat `quality.commands`/`quality.blockingCommands` keys (so existing
  configs keep working unchanged). The detected profile name is reported as `qualityGate.profile` in
  the JSON output.
- If any configured (blocking) command fails, PR generation/update is blocked.
- `Tests` and `Coverage` sections are filled from real command results and coverage artifact (`coverage/lcov.info`, when the profile produces one).

## "How to test manually" section

The generated PR body always includes a "🧭 How to test manually" section, right before the
checklist. Its content is optional and pulled from a file, never generated by this skill itself
(this skill is fully deterministic Python, no LLM calls):

```bash
python3 ~/.claude/skills/pr-maestro/tools/pr_maestro.py --base develop --how-to-test-file /path/to/tutorial.md
```

Recommended flow when a manual test tutorial exists or makes sense for the PR:
1. Run the `qa-test-tutorial` skill first (Phase A) to produce the tutorial Markdown for the ticket.
2. Save that Markdown to a temp `.md` file.
3. Chain `pr_maestro.py --how-to-test-file <file>` (the flag is forwarded automatically to the
   update path via `pr_template_apply.py` as well).

If `--how-to-test-file` is omitted or the file is empty, the section shows a placeholder pointing to
the `qa-test-tutorial` skill instead of a fabricated tutorial — never invent test steps here.

Note: only the Phase A tutorial *text* goes into the PR body. Any Phase B evidence (screenshots)
captured by `qa-test-tutorial` stays as files for the user to attach manually to the Jira US — this
skill has no Jira integration.

## Safety rules

- Never fabricate test evidence.
- Never create duplicate PRs.
- Prefer GitHub REST patch for body/title updates.
- Keep output machine-readable (JSON) for deterministic chaining.