---
id: gh-caveman-discover
name: "caveman-discover"
url: https://skills.yangsir.net/skill/gh-caveman-discover
author: juliusbrussee
domain: ai-dev-tools-workflow
tags: ["workflow-tagging", "llm-cost-tracking", "developer-tools", "automation", "observability"]
install_count: 100800
rating: 4.80 (120 reviews)
github: https://github.com/juliusbrussee/caveman/tree/main/skills/caveman-discover
---

# caveman-discover

> 此技能自动为代码仓库中的 LLM 工作流（如支持工单回复、夜间摘要任务）添加可追踪标签，实现按工作流维度的成本监控。它通过盘点入口、命名规范、最小化改动接入网关，帮助团队清晰掌握每项 AI 任务的资源消耗，优化预算分配。

**Stats**: 100,800 installs · 4.8/5 (120 reviews)

## Before / After 对比

### 工作流成本追踪效率

**Before**:

在没有此技能前，开发者需要手动翻阅代码库，逐个调用点判断属于哪个工作流，再手工添加标签，过程繁琐且容易遗漏。

**After**:

使用此技能后，自动盘点工作流并生成标记方案，只需确认即可应用，显著提升标记速度和准确性。

| Metric | Before | After | Change |
|---|---|---|---|
| 标记耗时 | 180分钟 | 15分钟 | -92% |

## Readme

You are labeling this repository's LLM workflows for Caveman Cloud. A
*workflow* is a job the code performs — "answer a support ticket", "build the
nightly digest", "run the eval suite" — not a technology. Every gateway
request can carry a workflow label; unlabeled traffic all lands in one
`unlabeled-workflow` bucket. Your job: find the workflows, name them well,
wire the labels, and verify nothing broke.

This changes code, so it goes through the user's normal review: **propose the
table first, apply after the user agrees.** Re-running on an already-labeled
repo must change nothing (idempotent).

This skill is operator-invoked. An `unlabeled-traffic` Cave Plan observation is
review-only and does not create an advisory file, proposal, or Draft PR. Do not
infer that telemetry selected a callsite or authorized an edit. Independently
inventory the repository, present the labeling table, and wait for the user's
approval before changing code.

## Step 1 — Inventory the workflows

Walk the repo from its entry points, not from its imports:

- HTTP/RPC handlers that call an LLM (directly or through layers)
- Scheduled jobs: cron definitions, queue consumers, workers, GitHub Actions
  that invoke LLM code
- CLI commands and scripts (`scripts/`, `bin/`, package.json scripts)
- Eval / test harnesses that burn real tokens
- Distinct agents or chains inside a framework (each LangGraph graph, each
  crew, each agent definition is usually its own workflow)

One workflow = one job a human would name. Ten callsites inside the same
request handler are one workflow; one shared `llm.ts` helper used by three
jobs is three workflows (label at the callers, never the shared helper).

## Step 2 — Name them

Slug grammar (the gateway enforces this): lowercase `[a-z0-9_-]`, 1–96 chars.
Name the job, not the tech:

- Good: `support-reply`, `nightly-digest`, `pr-review`, `eval-suite`,
  `onboarding-email`
- Bad: `openai-calls` (tech), `main` (says nothing), `SupportReply` (invalid),
  `johns-test-3` (won't age)

Names are forever-ish — renaming later splits the spend history. When a job's
purpose isn't clear from the code, derive the slug from the file name and mark
it `review` in the table rather than inventing a purpose.

## Step 3 — Propose, then apply

Present this table and ask to proceed:

```
| workflow | job | where | how it gets labeled |
|---|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 | defaultHeaders on the reply client |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 | header on the digest client |
| eval-suite (review) | scripts/eval.ts:8 — purpose inferred from filename | scripts/eval.ts:8 | env override at invocation |
```

Then wire each label with the lightest mechanism available at that callsite:

- **@caveman-ai/sdk / caveman_cloud SDK**: per-trace `workflow` option, or
  `defaultWorkflow` on the client a single-job service constructs.
- **Raw provider SDKs** (OpenAI/Anthropic/LangChain/LiteLLM/Vercel): add
  `"x-cave-workflow": "<slug>"` to the same `defaultHeaders` /
  `default_headers` / `extra_headers` block that already carries
  `x-cave-api-key`. Shared client used by several jobs → pass the header per
  call (every SDK above accepts per-request header overrides), or give each
  job its own thin client.
- **Wrapped coding agents** (`caveman wrap`): `--workflow <slug>` flag or
  `CAVE_WORKFLOW=<slug>` env at the invocation site (cron line, CI step).
- **Raw HTTP**: add the `x-cave-workflow` header to the request.

Label the callers, keep the diff minimal, match the repo's style. If a
callsite is not routed through the Caveman gateway at all, don't label it —
list it under "not wired" in the report (labels only travel on gateway
traffic; wiring is the caveman-setup skill's job).

## Step 4 — Verify

Run whatever the repo already uses to exercise one labeled path (a test, a
dev script, one curl). Then confirm: the request still succeeds (the gateway
rejects an invalid label with 400 `cave_invalid_request_header` — fix the slug
if so). Labeled spend appears on the dashboard at `/activity?tab=workflows` as
each workflow next runs; jobs on a schedule show up when the schedule fires,
and that's worth saying in the report rather than pretending they're live.

## Step 5 — Report

```
## Workflows labeled

| workflow | job | where |
|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 |

Verified: <the labeled path you actually exercised, and what you observed>
Lands at: <DASHBOARD>/activity?tab=workflows — each row appears as that workflow
next runs. Anything still unlabeled shows as `unlabeled-workflow`.
Not wired (no gateway routing, so no label): <list or "none">
Marked review: <slugs whose purpose was inferred from filenames, or "none">
```

If you found no LLM entry points at all: say exactly that, and point at the
setup skill (`<docs origin>/docs/agent-setup.md`) instead of manufacturing a
table.


---
*Source: https://skills.yangsir.net/skill/gh-caveman-discover*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-caveman-discover/markdown*