Guide · Agent skill
How to use the Caveman Cloud Workflow Discovery agent skill (caveman-discover)
Updated · written with AI from the project's own documentation and checked against our catalogue data
caveman-discover is an agent skill for the Caveman Cloud gateway. It tells an AI coding agent to find every place in your repository that calls a language model, give each distinct job a readable label such as support-reply or nightly-digest, and add those labels to your gateway requests so spend is broken down by job. This guide is for engineers who already route LLM traffic through Caveman Cloud and want to know how to install, trigger and review the skill.
Caveman Cloud Workflow DiscoveryJuliusBrussee/caveman · Apache-2.0 Download the skill Quick start
- 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or into the project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm prerequisites. Make sure the repository already has a Caveman Cloud gateway account and API key configured, and that its code uses a Caveman SDK, a raw provider SDK, or the caveman CLI.
- 3Start the request. Ask the agent to discover workflows in the repository or to break LLM spend down by workflow.
- 4Review the proposed table. Read each proposed workflow slug, job, location and labeling mechanism. Look closely at any entries marked review.
- 5Approve the changes. Reply with your approval so the agent applies the minimal labeling diff to the callsites.
- 6Verify one labeled request. Let the agent run one existing test, dev script or curl request and confirm it succeeds without a 400 header error.
- 7Check the dashboard. Open /activity?tab=workflows and look for each workflow once it has run, noting that scheduled jobs appear only after their next run.
What an agent skill is and what caveman-discover makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that an AI coding agent loads when a request matches the skill. This one is named caveman-discover and its description says it finds and labels every LLM workflow in the repository so Caveman Cloud groups spend by workflow instead of one bucket.
A workflow here means a job the code performs, such as answering a support ticket or building a nightly digest, not a technology. Without labels, all gateway traffic lands in one unlabeled-workflow bucket. The agent's job is to find the workflows, name them, wire the labels and verify that nothing broke.
- Step 1: inventory workflows from entry points such as HTTP handlers, scheduled jobs, CLI scripts, eval harnesses and agent definitions.
- Step 2: name each workflow with a slug (lowercase letters, digits, underscores and hyphens, 1 to 96 characters).
- Step 3: propose a labeling table and wait for your approval before changing code.
- Step 4: wire labels with the lightest mechanism at each callsite, then exercise one labeled request.
- Step 5: report what was labeled, what was verified and what was not wired.
Install the caveman-discover skill
Download the ZIP from the skill's page in this directory, then choose one of two locations. For a personal install available across projects, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it applies only to that repository.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills. The ZIP contains SKILL.md, which is the only file listed for this skill.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ inside the repository
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the requirements before you start
The skill assumes that your setup is already in place. It does not create a Caveman Cloud account or key for you. The repository must already have a Caveman Cloud gateway account and API key configured, and the code must use either the Caveman SDK or a raw provider SDK, or use the caveman CLI for wrapped coding agents.
The agent also needs access to edit source files and to run the repository's existing test or dev commands. The skill runs scripts and uses the network, so review what it does before approving.
- A Caveman Cloud gateway account and API key already configured in the repository
- A Caveman SDK or raw provider SDK in the codebase, or the caveman CLI for wrapped coding agents
- Repository access to edit source files and run existing test or dev commands
- Runs scripts: yes. Uses network: yes.
Trigger the skill with a natural request
The skill is operator-invoked, so you start it yourself. The skill's description lists phrases such as discover workflows or breaking LLM spend down by workflow. Ask the agent in plain language from the root of the repository where the skill is installed.
The agent will not edit code on the first pass. It inventories the repository and returns a table of proposed labels. Reply with your approval before it applies the changes.
- Discover workflows in this repo and propose labels for Caveman Cloud.
- Break down our LLM spend by workflow.
- Find every LLM workflow here so Caveman Cloud can group spend by job.
Read and approve the proposed labeling table
The proposed table lists each workflow, the job it performs, the file and line where it is called, and the mechanism that will add the label. Workflows whose purpose was inferred from a filename are marked review. Check each slug, because names are long-lived and renaming later splits spend history.
Callsites that do not go through the Caveman gateway are not labeled. They appear under not wired in the report, since labels only travel on gateway traffic.
- Shared helpers are labeled at their callers, not inside the helper.
- Re-running the skill on an already-labeled repository should change nothing.
- Labels can be added per trace, as a client default, as a request header, or as a CLI flag or environment variable, depending on the SDK in use.
Verify and find the results on the dashboard
After approval, the agent runs one labeled path using commands the repository already uses, such as a test, a dev script or one curl request. Confirm that the request succeeds. If the gateway rejects a label with a 400 response and the error cave_invalid_request_header, the slug is invalid and must be corrected.
Labeled spend appears on the dashboard at /activity?tab=workflows as each workflow runs. Jobs on a schedule only show up when their schedule fires.
- Rejected label returns 400 with cave_invalid_request_header: fix the slug
- Scheduled jobs appear after their next scheduled run
- Anything still unlabeled shows as unlabeled-workflow
/activity?tab=workflowsWhat people use it for
- Splitting token spend for a support bot into a support-reply bucket separate from a nightly summary job.
- Seeing how much an eval suite that calls a real model costs compared with production request handlers.
- Finding LLM calls hidden in cron jobs, queue workers or GitHub Actions and giving each its own label.
- Auditing a repository with several LangGraph graphs or agent definitions so each job is tracked separately.
Frequently asked questions
Is the caveman-discover skill free to use?
The source does not state pricing or licence terms for Caveman Cloud itself. The skill is listed under Apache-2.0 licence, so check that licence text for the terms that apply to the skill code. You still need a Caveman Cloud gateway account and API key to make labeled traffic show up.
What do I need before caveman-discover can work?
You need a Caveman Cloud gateway account and API key already configured in the repository, a Caveman SDK or raw provider SDK in the codebase or the caveman CLI for wrapped coding agents, and repository access to edit files and run existing test or dev commands.
Where do I install the caveman-discover skill?
Download the ZIP from the skill's page and unzip it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder for one repository. In the Claude apps you can upload it under Settings → Capabilities → Skills.
Will the skill change my code without asking?
No. The skill must first present a proposed table of workflow labels and wait for your approval before editing any code. After approval it applies the labels, and re-running it on an already-labeled repo should change nothing.
Why is a callsite listed as not wired?
Labels only travel on requests routed through the Caveman gateway. If a callsite does not go through the gateway, the skill does not label it and lists it under not wired in its report. Wiring gateway routing is a job for the caveman-setup skill, which the source points to.
Why does my labeled request return a 400 error?
The gateway enforces a slug grammar of lowercase letters, digits, underscores and hyphens, 1 to 96 characters. An invalid label returns 400 with the error cave_invalid_request_header, so correct the slug and try again.
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-discover if your team already sends LLM traffic through Caveman Cloud and wants spend split by job, and you are willing to review a small code diff before approving it. Pick something else if your repository is not routed through the gateway, if you need a general code audit or cost tool unrelated to Caveman Cloud, or if nobody on the team can review code changes carefully.
Download the skill