The Complete Production SOP: How to Deploy and Run Bruno Git-Friendly API Collection Spec in Autonomous AI Agents
Step-by-step SOP to install and run the Bruno Git-Friendly API Collection skill in Codex, Claude Code, and Cursor. Automate version-controlled .bru APIs safely.
Technical Overview & Architectural Context
Autonomous coding agents like Claude Code, Codex, and Cursor frequently fail when tasked with maintaining API collections. When prompted to generate or update API requests, LLMs default to monolithic Postman JSON v2.1 exports. These bloated files cause severe Git merge conflicts, obscure simple delta changes, leak authentication tokens into version control, and rapidly consume context windows. Furthermore, LLM hallucinations routinely introduce malformed JSON syntax inside nested script blocks. The 'Bruno Git-Friendly API Collection Spec' skill enforces strict procedural boundaries by guiding agents to author declarative, plain-text Bruno (.bru) specifications. By restricting requests to modular folder hierarchies with separated meta, HTTP verb, headers, body, and test blocks, the skill guarantees clean Git diffs, zero token leakage through environment variable abstraction, and deterministic CI/CD test execution via the @usebruno/cli runner.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your agent directory to enable trigger-based discovery.
Autonomous agent frameworks (including Claude Code, Codex, and Cursor project rules) look for skill definitions either in global agent directories (~/.agents/skills) or project-scoped configuration trees (.agents/skills or .cursor/rules). Mounting this skill provides the parser with exact YAML frontmatter triggers and execution bounds, preventing agents from falling back to unstructured curl scripts or bloated JSON schemas.
mkdir -p .agents/skills/bruno-git-friendly-api-docs && curl -fsSL https://askills.dev/api/skills/bruno-git-friendly-api-docs/raw -o .agents/skills/bruno-git-friendly-api-docs/SKILL.md---
name: "bruno-git-friendly-api-docs"
description: "Manage version-controlled, collaborative API request collections with Bruno Bru files."
metadata:
author: "UseBruno"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "create bruno api collection"
- "write .bru request file"
- "run bruno collection cli"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Store the skill in the repository root under .agents/skills/ so all team members and CI-based agents share identical deterministic rules without re-downloading.
Ensure that the agent runtime respects fs_write: 'workspace'. Never allow an agent to write .bru files outside the repo tree.
Environment Secrets & Bruno Workspace Initialization
Initialize the bruno.json collection root and configure environment secrets isolation.
Bruno collections require a root `bruno.json` descriptor to establish collection identity and environments. Instruct the agent to scaffold this manifest and set up an environments directory. Secrets must be parameterized via process environment lookups or untracked .env files rather than hardcoded in .bru files.
npx @usebruno/cli --version || npm install -D @usebruno/cli{
"version": "1",
"name": "Service API Collection",
"type": "collection",
"ignore": [
"node_modules",
".git"
]
}Direct the agent to reference {{process.env.API_KEY}} within Bruno environment files rather than embedding raw bearer tokens.
Add `environments/*.local.bru` to your project's `.gitignore` to prevent developers or agents from committing real credentials.
Intent Matching & Trigger Invocation
Trigger the agent to generate human-readable, declarative .bru files matching your routes.
Invoke the skill using precise trigger phrasing. The agent will read route definitions from your controllers/routers and map them into modular Bruno requests containing meta, HTTP method, headers, and test assertion blocks conforming strictly to the Bru syntax parser.
claude "create bruno api collection for auth endpoints with login and refresh token flows"meta {
name: User Login
type: http
seq: 1
}
post {
url: {{baseUrl}}/api/v1/auth/login
body: json
auth: none
}
headers {
Content-Type: application/json
}
body:json {
{
"email": "[email protected]",
"password": "{{userPassword}}"
}
}
tests {
test("should return 200 OK and token", function() {
expect(res.getStatus()).to.equal(200);
expect(res.getBody().token).to.be.a('string');
});
}Require the agent to assign sequential `seq` values in meta blocks so collection CLI test runs execute in logical dependency order.
Ensure the agent does not enclose JSON keys or string payloads in unescaped double quotes inside the body:json block.
Verification, Linting & Output Quality Gate
Execute automated self-healing validation using the Bruno CLI in CI or local terminal.
Before accepting agent changes, require the agent to validate the syntax of generated .bru files and run local verification against a mock or live testing server. If syntax errors or schema violations occur, the agent must catch exit codes and self-heal.
npx @usebruno/cli run auth --env Local#!/usr/bin/env bash
set -euo pipefail
echo "Validating Bruno files syntax..."
find . -name "*.bru" -type f -exec grep -q "meta" {} \; || {
echo "Error: Found invalid .bru file missing meta block"
exit 1
}
echo "Bruno syntax check passed."Use `git diff --stat` during the verification gate to confirm that only modular .bru files were created without unrequested modifications to app code.
Running `bru run` in CI without mock or network stubs will fail if net_access is disabled in agent sandbox policies; provide an in-memory test runner if necessary.
Real-World Scenario: Scaffold Git-Controlled Payment Gateway API Collection with Automated Assertions
“create bruno api collection for our new Stripe webhook and checkout session endpoints in ./api-docs/payments. Include input schemas, mock headers, and assertions verifying 201 status and session ID returns.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent attempted to wrap JSON payloads in additional quotation marks or improperly closed the block delimiter (e.g., missing closing curly brace or syntax misalignment between Bru block headers and body content).
Sed or prompt instruction to repair: Ensure body:json starts immediately on the next line and is valid JSON without backticks:
body:json {
"key": "value"
}Root Cause: The agent runtime sandbox does not have the Bruno CLI installed globally, or npx execution is restricted by the sandbox policy.
npm install --save-dev @usebruno/cli && npx @usebruno/cli run ./path-to-collectionFrequently Asked Questions (Bruno Git-Friendly API Collection Spec SOP)
Q:Can I use Bruno Git-Friendly API Collection Spec across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification supported across all modern agent runtimes. Simply place the file in `.agents/skills/` or reference it within `.cursorrules` / CLAUDE.md to share procedural rules across your team's development environments.
Q:How does Bruno Git-Friendly API Collection Spec prevent context window overflow during long agent sessions?
Traditional Postman collections consist of multi-megabyte JSON trees that exhaust LLM token limits and induce hallucination. Bruno splits each endpoint into an isolated, human-readable `.bru` plain-text file. The agent only reads and modifies the single targeted `.bru` file needed for the task, keeping token usage under 500 tokens per operation.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100. It requires only standard workspace filesystem write access (`fs_write: workspace`) to generate text files, while network access and shell execution can remain strictly sandboxed or disabled.
Ready to equip your autonomous agent with Bruno Git-Friendly API Collection Spec?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.