Skills, not prompts: how my coding agents take a bug from report to pull request

For a while I kept explaining the same things to my coding agents. Reproduce the bug first. Create the ticket before you touch the code. Don't skip the failing test. Don't tell me CI is green when you haven't looked. Every new session started from zero.

So I stopped writing prompts and started writing skills. I now have about twenty of them, and they turn "fix this bug" into a repeatable workflow that ends in a reviewed pull request. This post covers how they're organised, what the main pipeline looks like, and the guardrails that make the output trustworthy.

What a skill is, and where mine live

A skill is a Markdown file with a name, a short description of when to use it, the steps to follow and the rules that must not be broken. The agent reads the descriptions and loads a skill when the task matches, much like a developer reaching for a checklist.

Mine live in one master folder, ~/.agents/skills. From there they're synced into Claude Code and opencode, and Codex picks them up too. One copy to edit, three agents that behave the same way.

The most valuable part isn't the steps, it's the lessons. When something goes wrong, the fix goes into the skill so it never goes wrong again. Two examples:

• Jira's API rejects wiki markup in some fields with a bare HTTP 400 and no explanation. The ticket skill now says: send the content as ADF (Atlassian's document format), then verify the ticket by searching for it.
• Multi-line commit messages broke in zsh, and PRs against the main branch ran no CI. Both are written down, so the agent works around them instead of rediscovering them.

The main pipeline: from bug report to pull request

The flagship skill handles a production bug in a PHP B2B shop from the first report to an open pull request. It runs in phases, and the agent updates a to-do list after each one, so I can see where it is.

1. Reproduce with real data. Search the tracker for duplicates, read the project's notes for agents, and reproduce the bug locally against a synced copy of the data. Log in as the affected user and inspect the page in a real browser. The phase ends with an evidence table and a one-sentence root cause, before any code changes.
2. Ticket first. Create the Jira ticket in the team's format and move it through the workflow, so the work is visible from the start.
3. Branch. One hotfix branch per ticket, named after it.
4. Smallest fix at the root cause, with unit tests for the happy path, the failure fallback and the edge cases (missing product, empty query).
5. An end-to-end regression test that must fail without the fix. The Playwright test runs green with the fix. Then the agent reverts only the fix and the test has to fail, showing the wrong data. Then the fix goes back in and the test is green again. A test that passes either way proves nothing.
6. The gate: the full unit test suite and static analysis (PHPUnit and PHPStan) run before every commit. Then commit, push, and open the PR.
7. Report: the PR link and the evidence go into a comment on the ticket, followed by a final summary for me.

Prove the root cause with data before writing the fix. Prove the test with a revert before trusting it.

Small skills that compose

The pipeline doesn't do everything itself. It calls smaller skills, each of which also works on its own:

• Ticket creation: the team's bilingual format, acceptance criteria in the right field, verified afterwards.
• Browser building blocks: log in to the admin backend, impersonate a shop user, add a product to the cart, run the checkout. Each one records the traps found while writing it: which of two identical forms to use, and which class change means "the button is ready".
• The pre-commit gate: set up the test databases, run the full suite and static analysis, and report exact counts.
• Pull request creation: a fixed template (ticket link, description, testing, how to test, deployment notes), using only git and gh. No ticket key means no PR.

After the PR: the review loop

A second workflow takes over when reviewers have commented:

1. Collect every review comment on the PR through the GitHub API.
2. Fix them, then check each thread and mark it fixed, partial, unresolved or not applicable.
3. Run the tests and static analysis again, and repeat.
4. Stop after three rounds without progress and hand over to a human instead of going in circles.
5. Commit, push and watch the CI checks until they're green.
6. Reply to every thread, citing the commit that addressed it.

Before anything is committed or posted, the agent scans for email addresses and other personal data.

Beyond bug fixes

• Technical planning: turn a GitHub issue into a backend implementation plan before coding. The rule is to never propose a single solution. The agent offers two or three options with trade-offs, the developer decides, and the output is a plan file. Nothing is committed.
• Performance profiling: measure a backend path over several iterations (p50/p95/p99 wall time, CPU, peak memory, SQL query count and time). Then apply one change, measure again, and revert. One change at a time, and benchmark scripts are never committed. It ends with a before/after table.
• Code review: review local changes before pushing, or someone else's PR, against a checklist covering correctness, security, conventions, performance, tests and docs.

The guardrails that repeat everywhere

Looking across all the skills, the same rules keep appearing. They matter more than any single step:

• Never invent facts. No made-up CI results, test runs, ticket states or deployments. If something wasn't run, the report says "not run" and why. A PR existing doesn't mean it's deployed.
• Tests are never skipped, weakened or deleted. Pre-existing failures are separated from new ones, with evidence. A blocked or partial run is not a green run.
• Humans approve anything public or irreversible. The same boundary holds outside work: my browser skills that draft marketplace listings fill in the form, then stop and ask before pressing "Publish".
• Credentials come from the environment only (for example gh auth). Credential files are never read and tokens are never printed.

The tooling underneath

• A Jira MCP server I wrote, with 20 tools: search, create, update and transition issues, comments, attachments, epics, and test cases and runs.
• Playwright MCP driving a real browser, for reproducing bugs and walking through flows.
• Plain CLIs, mainly git and gh, and the project's own test tools.

If you want to start

1. Start with the workflow you explain most often. That's your first skill.
2. Write guardrails as rules, not hopes. "Never skip tests" belongs in the file, not in your head.
3. Make the agent prove things. Evidence tables, exact test counts, a test that fails without the fix.
4. Every surprise becomes a line in a skill. That's how the workflow gets better instead of just longer.
5. Keep one master copy and sync it to every agent you use.

If you're working on something like this, or want it set up in your team, see AI engineering & MCP servers. And if you'd rather see what I build for fun, there's a write-up of the multiplayer sailing game on this site.