Guide · Agent skill
How to use the Caveman LLM Gateway Setup agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The caveman-setup skill is a set of instructions that an AI coding agent reads and follows to connect an existing app to the Caveman gateway, a proxy that records how much each LLM call sends and costs. It is aimed at developers whose app already calls OpenAI, Anthropic or similar APIs and who want per-app spend visibility. After this guide you will know how to install the skill, ask for the setup in plain words, and check what the agent reports back.
Caveman LLM Gateway SetupJuliusBrussee/caveman · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the caveman-setup ZIP from this page and unzip it. Keep the caveman-setup folder intact.
- 2Place it in the skills folder. Move the folder to ~/.claude/skills/ for all projects, or to .claude/skills/ inside one repository.
- 3Gather your gateway values. Have your gateway base URL, CAVE_API_KEY, provider key mode (stored or byok) and dashboard URL ready.
- 4Ask for the setup in plain words. Open the repository in your agent and ask it to set up caveman or add LLM spend observability.
- 5Review the wiring. Check the callsites the agent lists and the diff to base URLs, headers and the env file.
- 6Read the verification report. Confirm the report shows a real HTTP status and usage numbers from the test request.
What the caveman-setup skill makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions. When the skill is installed and relevant, the agent follows those instructions while working in your repository. This skill tells the agent to find every LLM call in the code, point each one at the Caveman gateway instead of the provider, add one authentication header, store the gateway key in an environment variable, and send one small test request to confirm it works.
The skill describes the gateway as record mode: it measures what your app sends and what it costs, and changes nothing else. The skill says it does not optimize or alter requests, and it does not claim any savings.
- Finds LLM callsites from dependency files and source imports
- Changes only the base URL and adds the gateway auth header
- Puts CAVE_API_KEY in the env file the repo already uses and adds that file to .gitignore if it is not ignored
- Sends one request capped at a small max_tokens and reports the real HTTP status and usage numbers
Install the skill: download the ZIP and unzip it
Download the ZIP for caveman-setup from this page and unzip it. To make the skill available to all your projects, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside the repository
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with a natural request
You do not need a special command. The skill's description matches requests such as "set up caveman" or a request to add LLM spend observability. Start the agent in the repository you want to wire and ask in plain words.
Before the agent edits anything, it needs four values: the gateway base URL, the CAVE_API_KEY, whether provider keys are stored in Caveman Cloud or sent by the app (byok), and the dashboard base URL. If any is missing, the agent stops and asks for it rather than guessing.
- "Set up caveman for this repo so our OpenAI spend shows up on the dashboard."
- "Add Caveman LLM spend observability to this app."
- "Wire this repository through the Caveman gateway in byok mode."
What you need before you start
You need a Caveman Cloud account or a self-hosted gateway URL, plus its CAVE_API_KEY. You also need the app's existing LLM provider keys if you use byok mode. The agent needs read and edit access to the repository's dependency files and source code, and it must be able to send an HTTP request to the gateway to verify the setup.
The skill does not work standalone without a gateway URL and key. It also has no purpose in an app that makes no LLM calls, because the agent is designed to stop and report that there is nothing to wire.
- Caveman Cloud account or self-hosted gateway URL and CAVE_API_KEY
- Existing provider keys (byok mode only)
- Access to dependency files and source code
- Ability for the agent to send an HTTP request to the gateway
Safety notes: scripts and network use
According to the skill's listing, it runs no scripts and does use the network. The network use is the verification request to the gateway, and the wiring routes your app's LLM requests through the gateway, so prompts and responses pass through a third-party proxy.
The skill treats the key as a secret: it belongs in an env var, is never committed, and is never printed in full. With stored provider keys the agent never sees the provider key. With byok, the app's existing provider key stays where it already is. Check that sending traffic through the gateway is allowed in your project before you run the setup.
- No scripts are run by the skill
- Network is used for the single verification request
- Do not use it where prompts must not pass through a third-party proxy
- Review the diff the agent makes before committing
Read the report and tips
The final report should include the HTTP status and usage numbers from the real verification response. If verification fails, the skill asks the agent to report the failure instead of claiming success. Savings are reported as $0 because this skill only measures.
Keep changes minimal: the skill asks for coherent wiring without drive-by refactors. Confirm the app slug it chose, since spend for the whole app groups under that slug on the dashboard.
- Look for an HTTP status and usage numbers in the report
- Expect the app slug to group spend on the dashboard
- Expect no optimization to be enabled
What people use it for
- Tracking spend per app for a support chatbot that calls OpenAI
- Adding one measurement layer to an API service that calls Anthropic
- Giving a team a consistent integration across several repositories that already use the Caveman Cloud gateway
Frequently asked questions
How do I install the caveman-setup skill?
Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects or in a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings, Capabilities, Skills.
Is the caveman-setup skill free?
The skill is licensed under Apache-2.0. This page does not state any pricing for Caveman Cloud, so check the provider's own terms for gateway costs.
What do I need to use caveman-setup?
You need a Caveman Cloud account or self-hosted gateway URL and its CAVE_API_KEY, access to the repository code, and the ability for the agent to send an HTTP request. In byok mode you also need the app's existing provider keys.
Does the skill change my prompts or make requests cheaper?
The skill says it only measures. It does not optimize or alter requests, and it does not claim any savings, since verified savings are $0 until an optimizer is explicitly turned on.
Why does the agent stop and ask for values?
The skill requires a gateway URL, CAVE_API_KEY, provider key mode and dashboard URL. If any is missing, it stops and asks instead of guessing a URL or creating a key.
What should I do if the verification request fails?
The skill tells the agent to report the failure using its failure template rather than claiming success. Check the gateway URL, the key in your env file, and the app slug, then ask the agent to rerun the check.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use caveman-setup if you run an app that calls OpenAI, Anthropic or similar APIs, already have Caveman gateway access, and want per-app spend visibility with a minimal code change. Pick something else if your app makes no LLM calls, if prompts cannot pass through a third-party proxy, or if you have no gateway URL and key.
Download the skill