Guide · Agent skill
How to use the Investigate First agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Investigate First is an agent skill from the caveman project's skills collection. It tells an AI agent to diagnose a problem with evidence before it touches product code, which is useful when a failure has an unknown cause, behaves intermittently, or a system has become slower. This guide explains what the skill does, how to install it, how to trigger it, and where it fits best.
Investigate FirstJuliusBrussee/caveman · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the Investigate First skill ZIP from this page.
- 2Unzip the skill. Unzip the folder so it contains agents/openai.yaml and SKILL.md.
- 3Place the skill folder. Move it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project.
- 4Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 5Describe the problem. Ask in plain language about an unknown cause, intermittent failure, or slowdown.
- 6Review the report. Read the observed symptom, ranked hypotheses and proof before approving any fix.
What is the Investigate First skill and what does it make the agent do?
An agent skill is a set of instructions that an AI agent loads when a task matches the skill's description. Investigate First covers ambiguous failures: unknown causes, intermittent behavior, performance regressions, and investigations that need evidence-ranked hypotheses.
When the skill is active, the agent gathers evidence before changing product code. It separates the symptom it actually observed from the cause it infers, traces inputs, state transitions, ownership boundaries, and failure output, and ranks hypotheses by how well the evidence supports them and how cheaply each can be ruled out. It does not edit until one credible mechanism explains the evidence. It then reports the cause and the proof.
- Separates observed symptoms from inferred causes
- Traces inputs, state transitions, ownership boundaries and failure output
- Ranks hypotheses by evidence and cheap falsification value
- Stops exploring once the evidence names the cause or the exact blocker
- Makes no fix unless the task authorizes implementation
How do you install the Investigate First skill?
Download the ZIP for the skill from this page and unzip it. The skill folder contains agents/openai.yaml and SKILL.md. Then choose one of these locations depending on how you use your agent.
For a personal setup available across projects, unzip the skill into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
~/.claude/skills/How do you trigger the skill with a natural request?
You do not need a special command. The skill is meant to load when your request matches its description, so describe the problem in plain language. Phrases that mention an unknown cause, an intermittent failure, or a slowdown are the ones it was written for.
If you want the agent to investigate without fixing, say so directly. The skill already avoids edits unless implementation is authorized, so stating that you want findings first makes the boundary clear.
- "This checkout fails about one time in ten and I don't know why. Find the cause before changing anything."
- "Our API response time doubled after last week's deploy. Investigate the regression and rank the likely causes with evidence."
- "The nightly job sometimes writes duplicate rows. Trace where this could happen and tell me what you observe."
What should you expect the agent to produce?
A typical run starts with the observed symptom, followed by traced inputs, state changes and error output, and a ranked list of hypotheses. The agent keeps exploring only until the evidence is enough to name a cause or identify the exact blocker.
The final report states the cause and the proof behind it. If you had not authorized implementation, the agent reports the finding and leaves the code as it was. You then decide whether to ask for the fix.
- Observed symptom, kept separate from inference
- Hypotheses ranked by evidence
- Named cause with the proof, or the exact blocker if no cause is clear
What does the skill need, and what are the safety notes?
The skill lists no required dependencies. It does not run scripts and does not use the network, according to its listing. Its files are agents/openai.yaml and SKILL.md.
Because it runs no scripts and makes no network calls, it adds no extra execution or outbound access by itself. Its effect comes from the instructions it gives the agent, which may still read your code and logs while investigating. Review the SKILL.md file if you want to see exactly what instructions the agent receives. The skill is licensed under Apache-2.0.
- Requirements: none listed
- Runs scripts: no
- Uses network: no
- Licence: Apache-2.0
When should you not use Investigate First?
The skill adds time to every task. For simple, well-understood fixes, that investigation adds little value and slows the agent down. If you already know the change you want, ask for it directly.
It is also a poor fit when you want the agent to implement a change right away. The skill says not to fix unless implementation is authorized, so it will pause to investigate instead of editing.
- Simple, well-understood fixes
- Tasks where you want an immediate implementation
What people use it for
- Finding why a checkout fails only sometimes
- Tracing a performance regression after a deploy
- Locating where duplicate database rows can come from
- Explaining an error whose cause is not obvious before deciding on a fix
Frequently asked questions
How do I install the investigate-first skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.
Does the investigate-first skill require anything else?
The listing shows no required dependencies. The skill runs no scripts and uses no network access.
Is the investigate-first skill free?
The skill is licensed under Apache-2.0, as listed on this page. Check the licence terms in the source repository for details.
Will the skill change my code automatically?
No. The skill tells the agent not to edit until one cause clearly explains the evidence, and not to make a fix unless the task authorizes implementation.
What is the difference between this skill and just asking the agent to fix a bug?
Without the skill, an agent may go straight to a fix. Investigate First makes it separate observation from guesses, rank hypotheses by evidence, and report the proof before changing anything.
Why isn't my skill triggering?
The skill loads when your request matches its description, which covers unknown causes, intermittent behavior, and performance regressions. Check that the folder sits in the correct location and that it contains SKILL.md. Describing the problem in those terms helps.
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
Investigate First suits developers stuck on a bug with no obvious cause, teams chasing intermittent failures or slowdowns, and anyone who wants evidence before a fix. It is a poor choice for simple, well-understood changes or when you want the agent to implement something immediately, since it slows those tasks down and holds off on edits.
Download the skill