Why your AI Agent needs both a key and a map

You asked Claude to generate a bitrise.yml. It came back clean: right steps, reasonable workflow names, valid YAML. You almost merged it.

Then you noticed it’s using before_run instead of step bundles. There are no version locks on steps. The triggers are structured in a format Bitrise deprecated months ago.

It’s a valid config, but it would never pass code review.

The quality of an agent's interaction with your CI/CD comes down to two things: what it can do and what it knows. These are different problems: call it access vs knowledge, the key vs the map. At Bitrise, we built two tools to close the gap: the Bitrise MCP Server and the using-bitrise-ci agent skill. The interesting part is what happens when they work together.

The difference between access and knowledge

Imagine you’re onboarding a new engineer. On day one, you give them system access: a Bitrise account, API credentials, permissions to trigger builds and view logs. Now they can do things.

But they don't know your conventions yet. They don't know you use step bundles instead of before_run. They don't know your pipelines use explicit depends_on relationships, or that secrets never get committed to the repo. They can produce configs that look clean, but fail at runtime. Or worse, work today and create problems three weeks later.

Like an over-confident junior dev, an AI agent without context will just fill in the blanks with plausible guesswork. That's not a flaw you can prompt your way around. It's a structural problem, and it needs a structural answer. That's why we took a two-layered approach to designing an AI agent that actually speeds up your CI/CD integration work.

• The MCP server is the access layer: what the agent can do. It connects the agent to the Bitrise API, so it can trigger builds, read logs, validate configs, and manage projects, with auth handled transparently across the board.
• The agent skill is the knowledge layer: what the agent knows. It loads Bitrise CI conventions, configuration patterns, step versioning, and pipeline best practices into the agent's context.

What each layer does

The Bitrise MCP Server is an MCP-compatible interface to the Bitrise API. You can connect it to Claude Desktop, VS Code, Cursor, or any MCP-compatible host and the agent can trigger builds, pull logs, list apps and workflows, validate YAML, and manage workspace members: all direct, no copy-pasting required. And it's free on all Bitrise plans.

The using-bitrise-ci skill is a knowledge file that loads into the agent's context. It covers the things that separate a technically correct config from a good config, such as:

• Step bundles over the deprecated before_run/after_run pattern
• Explicit depends_on for new pipelines, legacy stages only where they already exist
• Major version pinning (git-clone@8, not git-clone)
• New per-workflow trigger format for new files, trigger_map preserved in existing configs
• Secrets in the Bitrise web UI are never committed to the repo

The full list goes deeper, but the point is that experienced engineers carry all this stuff in their heads already. No API endpoint can teach an agent any of it, but a skill file can.

The gap when you use only one

MCP without the skill: The agent has access but no knowledge. It calls the API but doesn't know the conventions. Ask it to create a pipeline and you'll get YAML that validates but uses deprecated patterns and incorrect step versions. If you've ever reviewed a PR from someone who read the docs intro and skimmed the rest, that's the output.

Skill without MCP: The agent has knowledge but no access. It gives expert advice it can't act on. It knows exactly how your bitrise.yml should look, but can't pull your current config, can't validate against the real API, can't check your build logs, and can't trigger a build to verify its fix.

Both together: The agent reads your config via MCP, understands what's wrong using the skill, proposes a fix that follows best practices, validates it through the API, and triggers a build to confirm. Most AI tooling gives you either smart suggestions or direct actions. Skill-plus-MCP gives you both at once: an agent that acts on real knowledge of how your pipelines should be built and meaningfully reduces fiddly config work and code review bottlenecks.

It’s worth noting that there are some scenarios when one layer is enough. The skill works offline or when you're writing a bitrise.yml from scratch: you don't need API access for expert-level config advice. MCP alone handles quick operations fine: trigger a build, check deploy status, add a user to a workspace.

In practice: debugging a failed iOS build

Your build just failed. You type: "Why did my last iOS build fail?"

The agent pulls the build log and your bitrise.yml through MCP. It scans the log, and because the using-bitrise-ci skill is loaded, it doesn't just see a generic error: it recognizes a code signing failure caused by a missing provisioning profile. More importantly, it knows that on Bitrise, the fix isn't hardcoding paths in the YAML. It's checking the Apple service connection in project settings.

It proposes the config change, validates it via the API, and tells you exactly what to check in the UI. You didn't have to switch tabs or paste a log, and the suggested fix actually follows your team's conventions.

Why not just give the agent CLI access?

A common alternative: let the agent shell out to the Bitrise CLI or curl the API directly, guided by a skill file that describes the endpoints. It works, but it pushes all the complexity onto the agent.

The agent has to manage auth tokens, construct each request from scratch, poll for build completion manually, and parse raw output with no guardrails. Plus, the CLI will happily validate a config that uses every deprecated pattern in the book. And if the agent has shell access with your API token, it has whatever permissions that token carries and there’s no way to scope it down.

Skill-plus-MCP solves this at the infrastructure level. MCP provides typed tools with structured inputs and outputs, handles auth and session management, and supports scoped access via --enabled-api-groups: you can restrict the agent to read-only, builds only, or whatever fits your risk tolerance. The skill adds the judgement layer: catching deprecated patterns, wrong step versions, and convention violations before they reach your repo.

It's also portable. A CLI approach only works when the agent has a shell. Skill-plus-MCP works in Claude Desktop, VS Code, Cursor, Windsurf, or anywhere else that speaks the protocol.

Get started

Install the skill with the Skills CLI:

npx skills add bitrise-io/agent-skills

It loads automatically when the conversation involves Bitrise CI, or you can invoke it directly with /using-bitrise-ci in Claude.

Connect the MCP server via the Bitrise MCP repo. The remote server at mcp.bitrise.io supports Claude Desktop, VS Code, Cursor, Windsurf, Gemini CLI, and more.

Then run an experiment: find the bitrise.yml that no one on your team wants to touch, the one that works but everyone knows is held together with duct tape. Point the agent at it. See what it catches. We've been doing this internally and it's humbling.

Both tools are open source. The skill is at bitrise-io/agent-skills, and the MCP server is at bitrise-io/bitrise-mcp. Tell us what you find.