Claude Skills for Business Analysts: Cutting API Integration Specs from Hours to One Hour

A Technical BA’s actual workflow for using agentic AI to draft Confluence specs that pass review, with the reference page pattern that makes it work.

The last API integration spec I wrote by hand took me close to a full day. New downstream service, ISO 20022 payload variant, the usual choreography of upstream consumers, Kafka topics, error mapping, retry policy, idempotency keys. By the time I was done I had the spec, but I had also lost an afternoon I could have spent on the things a Technical BA is actually paid for. Pushing back on ambiguous requirements. Sitting with developers on edge cases. Cleaning up the test data.

The next one took me about an hour. Not because I cut corners. Because I stopped writing the spec from a blank page.

I built a Claude Code skill that takes three inputs, reads our reference Confluence page and our codebase, and produces a structured first draft into a sandbox Confluence page that I then iterate on until I am happy with it. The actual AI run is around ten minutes. My iteration loop on top of it is another forty or fifty. Total, under an hour. Down from four to six.

This article is the methodology. Not the code. The pattern matters more than the implementation, and once you see it, you can rebuild it in your own shop in an afternoon.

Why the blank-page version of this job is broken

When you write an API integration spec by hand in a regulated environment, you are doing three jobs at the same time. You are remembering the format your team agreed on six sprints ago. You are translating a functional description and an API contract into that format. And you are checking the existing codebase for the integration patterns the team has already adopted so the new spec does not contradict them.

Humans are bad at doing three things at once. We are especially bad at the first one. The “format your team agreed on” drifts the moment one of you skips a section because it felt obvious. Six months later, no two specs in the space look alike, and the team has to re-litigate the format every time a new analyst joins.

The fix is not “write better.” The fix is to encode the format into something an agent can read and apply consistently. Which brings me to the most important part of this whole pattern.

The reference page pattern

Pick one Confluence page in your space that represents the spec format your team has agreed on. Not “a good example.” The example. Get the leads, the architects, and at least one senior developer to sign off on it. This page becomes your anchor.

Every input to the skill points back to this page. The agent reads it before it writes anything. The structure, the heading hierarchy, the level of detail under each section, the way you document error cases, the way you call out Kafka topics, the way you reference upstream and downstream services — all of it lives on this one page.

This sounds trivial. It is not. The reference page is the single highest-leverage artifact in this entire workflow, and most BA teams do not have one. They have a wiki full of inconsistent specs and a vague sense that “the one Sarah wrote last quarter was good.” That is not a reference page. That is folklore.

If you do not have a reference page yet, that is your first weekend project before any of this AI stuff matters. I wrote up the format I use for API specs end to end in API Documentation from Scratch, which is the closest thing to a portable reference page template I have published. Take it, adapt it to your domain, get your team to sign off.

The three inputs the skill takes

Once the reference page exists, the skill needs three things to do its job.

First, a functional description of the new integration. This is the prose. What business problem the integration solves, what the upstream trigger is, what the downstream effect is, what the business rules and error cases look like. Two to four paragraphs is usually enough. If you cannot describe the integration in four paragraphs, you do not understand it yet, and no AI is going to save you.

Second, the new API contract. OpenAPI spec, ISO 20022 message definition, internal proto file, whatever your shop uses. The contract is the source of truth for field names, types, cardinalities, and constraints. The skill reads the contract directly. You do not paraphrase it.

Third, the URL of the existing API Confluence page that the new integration depends on. Almost no API integration in a real bank is greenfield. You are extending, consuming, or routing through something that already exists. The agent needs to read that existing page so the new spec does not contradict the patterns that page already documents.

There is a fourth input that is technically a side effect of the setup, but it matters: the URL of a sandbox Confluence page where the agent writes. More on that in a second.

The sandbox page is non-negotiable

When I first built this skill, I made the agent write directly into the real spec page. It worked. It was also terrifying. One bad run and I had wiped out a page that was already linked from a Jira epic, a Slack thread, and a stakeholder review meeting.

The fix is the sandbox page. The agent always writes to a dedicated scratch page in my own Confluence space. I iterate on it. I run the skill again with adjusted inputs. I refine the prose. I add the diagrams the agent cannot generate yet. I check the field-level mappings against the contract. When I am satisfied, I copy and paste the content into the real spec page in the team space.

This sounds like a small workflow detail. It is actually the safety mechanism that makes the whole pattern usable in a regulated environment. Your audit trail stays clean. Your team’s space does not get polluted with half-baked drafts. And you have full editorial control over what makes it into the canonical spec.

If your team is doing AI-assisted spec writing without a sandbox, you are one bad prompt away from a very awkward stand-up.

The MCP plus PAT setup, in one paragraph

The technical wiring: I use the Atlassian Remote MCP server so the agent can read and write Confluence pages, scoped to a Personal Access Token that only has access to the spaces I work in. No credentials in the skill itself. No API keys floating in code. The AI access for the skill itself is through my GitHub Copilot license. If you are setting this up for your own team, the order of operations is: PAT first, MCP connection second, skill third. Do not skip the PAT step and use a service account. You want every spec the agent writes to be traceable to a human.

The prompting layer that makes the agent actually produce good output is where most of the work lives, and it is also the part most people underestimate. I built up a library of prompts for exactly this kind of agentic BA work over the last year, and the cleaned-up version of it is The Technical BA Prompt Toolkit. The patterns in there are what made the difference between “the agent wrote something” and “the agent wrote something I can ship.”

What the skill actually does in those ten minutes

The agent does four things in sequence, and the order matters.

It reads the reference page first. Before it sees the new integration, before it sees the contract, before anything else. The format is the constraint. Everything else gets fit into the format.

It then reads the existing API Confluence page, the one the new integration depends on. This gives it the context of the system the new spec is extending. It picks up the naming conventions, the error code patterns, the existing topic names, the upstream and downstream services already documented.

It reads the codebase next. Not all of it. The relevant parts: the existing integration handlers, the message mappers, the error mapping layer, the configuration. This is where the agent picks up the patterns the team has actually implemented, not just the ones documented on paper. This is also where most hand-written specs go wrong, because no human reads the entire codebase before writing a spec. The agent does.

Finally it reads the functional description and the new API contract, and produces the draft into the sandbox page. Structured to match the reference page. Field mappings derived from the contract. Error cases pulled from the existing patterns. Kafka topics named consistently with what is already in the code.

The draft is not perfect. It never is. But it is structurally correct, it is internally consistent with the team’s existing patterns, and it does not contradict the contract. Those three things alone account for most of the hours I used to spend writing specs by hand.

What I still do, and why the hour matters

The agent does not replace me. It replaces the part of the job I was bad at.

The forty to fifty minutes I spend iterating is where the actual analysis happens. I pressure test the error cases. I think through the idempotency story. I add the sequence diagrams. I write the test scenarios. I push back on the functional description if the agent surfaced an ambiguity I missed.

That work used to be buried under the slog of formatting and cross-referencing. Now it is the only thing left, and that is the right shape for the job. A Technical BA’s value is not in the typing. It is in the thinking. The skill removed the typing.

This is the broader pattern I keep coming back to: automation of BA work is not about replacing the BA. It is about removing the parts of the job that should never have been the BA’s job in the first place. Cross-referencing five pages to make sure naming is consistent should not be a human task in 2026. Validating that error codes line up across an existing handler and a new spec should not be a human task either. The Technical Skills Guide I wrote for analysts who want to build this kind of leverage into their work is The Technical Skills Guide for BAs, and it covers the muscles you need to build skills like this one yourself.

What can go wrong, and what does

A few honest failure modes, because nobody who actually runs this stuff in production talks about them enough.

The agent will sometimes confidently invent a field that does not exist in the contract. This happens most often when the functional description uses business language that does not map cleanly to a field name. The fix is to be more explicit in the functional description and to always diff the field list in the draft against the contract before you accept it.

The agent will sometimes carry over an outdated pattern from the existing API page. If your reference page is six months old and the team has moved on to a new error mapping convention, the agent does not know. The fix is to keep the reference page alive. Treat it as a living document. Update it the moment a team decision changes the format.

The agent will sometimes produce a draft that is technically correct and structurally clean and completely missing the business judgement that makes a spec actually useful. This is the part that no AI fixes. You still have to read the draft like a BA, not like a copy editor.

The portable lesson

The thing worth taking away from this is not “use Claude Code for API specs.” It is the pattern.

A team-agreed reference artifact. Inputs that point back to it. A sandbox for iteration. An agent that reads the codebase before it writes. A human who owns the final copy.

That pattern works for API integration specs. It also works for non-functional requirements documents, for data dictionaries, for test plan templates, for runbooks, for compliance evidence packages. Anywhere your team has a format that drifts because humans cannot consistently hold it in their heads, you can do the same thing I did.

The hour I saved per spec is not the point. The point is that I now spend that hour on the work only a senior BA can do, instead of on the work an agent could have done all along.

If you are a Technical BA in banking or payments and you want to build the full toolkit for this kind of work, The Complete Tech BA Bundle bundles the documentation, prompt, and skills guides together. Or browse the full catalog at The Tech BA Toolkit and pick what fits your gap.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.