The Agent Skill

The repository carries two agent skills under skills/, each a SKILL.md an agent loads once a task touches it, with reference files it reads only as the task needs them.

skills/spider-sense/ teaches the loop itself rather than the commands alone: start the application under the agent, mark a moment, exercise it, read the findings, fix, compare, check (The Loop). An agent that has only the CLI’s help knows every option and none of the method.

skills/spider-sense-sql-tuning/ teaches query tuning: the index to add, the rewrite, the fetch join, the batch, each verified with compare and check. It is read when a finding names a statement rather than a request.

Both are distilled from this manual, and the manual stays the source of truth.

What is in it

skills/spider-sense/SKILL.md carries what every task needs: what Spider Sense gives an agent that a dashboard does not, the loop as a script of commands, how to start each kind of application under the agent, how to read a finding, and the rules that keep an answer honest. Four reference files carry the rest, and an agent reads only the one its task touches.

File What it is for

File	What it is for
`references/cli.md`	every command, its flags, its exit codes, and the real output of each one
`references/findings.md`	each finding kind: its rule, its severity, its numbers, and the fix with Java examples
`references/running.md`	starting each kind of application under the agent, ports, forwarding, troubleshooting
`references/sql.md`	the schema in the columns that matter, and read-only SQL over it

references/cli.md

every command, its flags, its exit codes, and the real output of each one

references/findings.md

each finding kind: its rule, its severity, its numbers, and the fix with Java examples

references/running.md

starting each kind of application under the agent, ports, forwarding, troubleshooting

references/sql.md

the schema in the columns that matter, and read-only SQL over it

The rules in SKILL.md are what a manual cannot enforce on its own. Prefer the text output over --json, because it is smaller and it is the same data. Keep the window small, because the default --since=15m drags in whatever ran before. Never quote a number the tool did not print. Quote the trace id as evidence, because a claim about an endpoint that names no trace cannot be checked. Run check before calling a fix done, and say which rules it passed with which limits.

init

java -jar spider-sense.jar init [--dir=<project dir>] [--jar=<path>] [--no-skill] [--mcp]

init prepares a project to be worked on under Spider Sense. It is the one command that reads nothing: no HTTP, no database, no running Spider Sense. It writes a short block into the project’s CLAUDE.md and copies the skills into the project’s .claude/skills/.

--dir is the project directory, and it defaults to the working directory.

--jar is the jar path written into the block. Without it, init writes the distributable jar the command was started from. The path is written absolute, as given or as discovered, and never made relative to the project. When neither is known, which happens with exploded classes in an IDE and no --jar, init says which option it needs and exits 2.

The block

The block is delimited by <!-- spider-sense:start -→ and <!-- spider-sense:end -→, each on a line of its own, and this is it:

<!-- spider-sense:start -->
## Spider Sense

Spider Sense is a local-development APM for this project, and the jar is at `/home/me/tools/spider-sense.jar`.
Start the application under it with `java -javaagent:/home/me/tools/spider-sense.jar -jar <app jar>`, or, when the start command is not yours to change, with `JAVA_TOOL_OPTIONS="-javaagent:/home/me/tools/spider-sense.jar" ./gradlew bootRun` (or `./gradlew run`).
The UI is then at <http://127.0.0.1:4000> unless the port was changed.

Ask it from the terminal; every answer is Markdown made for an agent:

```bash
java -jar /home/me/tools/spider-sense.jar findings --since=start  # ranked: N+1, slow queries, slow endpoints, errors, exhausted pools
java -jar /home/me/tools/spider-sense.jar trace <id>  # one request as a tree
java -jar /home/me/tools/spider-sense.jar mark before  # name a moment, exercise, then compare
java -jar /home/me/tools/spider-sense.jar compare --before=before --after=after
java -jar /home/me/tools/spider-sense.jar check --max-p95-ms=300 --max-n-plus-one=0
java -jar /home/me/tools/spider-sense.jar help  # every command and every option
```

The loop — start, mark, exercise, findings, fix, compare, check — is in the skill at `.claude/skills/spider-sense/SKILL.md`.
Query tuning — an index to add, a rewrite, a fetch join, a batch — is in the skill at `.claude/skills/spider-sense-sql-tuning/SKILL.md`.
<!-- spider-sense:end -->

The jar path above is the one init resolved, and everything else is written as it stands. No port of the project is written: the block names the Spider Sense UI’s own default, http://127.0.0.1:4000, and nothing else. The last two lines name skills/spider-sense/ and skills/spider-sense-sql-tuning/ of the Spider Sense repository instead of the project’s own copies when --no-skill kept the skills from being installed.

init is idempotent. A second run replaces everything between the markers, including the jar path when it has changed, and leaves the rest of the file byte for byte as it was. Nothing else in the file is parsed or reformatted. When CLAUDE.md does not exist it is created with the block alone, and when it exists without the markers the block is appended after one blank line.

The skill copy

init copies every directory under skills/ — each one’s SKILL.md and references/*.md — into <dir>/.claude/skills/ under the same name, unless --no-skill is given, which skips all of them. It overwrites the files it owns and leaves anything else in those directories alone.

It is a copy rather than a pointer, because the jar is the distributable and the repository it was built from may not be on the machine at all. The files travel inside the jar, so no checkout is needed.

What it prints

wrote CLAUDE.md block (jar: /home/me/tools/spider-sense.jar)
installed skill to /home/me/project/.claude/skills/spider-sense (5 files)
installed skill to /home/me/project/.claude/skills/spider-sense-sql-tuning (4 files)

One line per skill, each with the number of files it wrote. The first line is updated CLAUDE.md block (…) when the markers were already in the file. The skill lines become the single line skipped skills (--no-skill) when the skills were not installed. --mcp adds a third line, wrote .mcp.json (spider-sense over stdio) or updated .mcp.json (…), and writes the stdio MCP server into the project’s .mcp.json (MCP). Without --mcp nothing is written and nothing is printed about it, because a host with a shell is meant to use the CLI.

The command then exits 0.

The Gradle task

spiderSenseInit runs init with the project directory and the jar the build resolved (Tasks):

./gradlew spiderSenseInit

The jar path it writes is wherever Gradle resolved the jar to, which for a Maven Central jar is a file under ~/.gradle/caches/. That path stays valid until the version changes, so run the task again after a version bump. Re-running init by hand after a bump does the same, because it replaces the block including the jar path.

Installing the skills by hand

init is the normal way, and it installs for Claude Code. Copy the directories yourself when the jar is not at hand, or when the target is another tool.

Claude Code

Claude Code reads a project’s .claude/skills/, which is where init puts the skills. Copy the directories there instead to get the same result, so that collaborators get them by cloning and install nothing of their own:

git clone --depth 1 https://github.com/benelog/spider-sense /tmp/spider-sense
mkdir -p .claude/skills
cp -r /tmp/spider-sense/skills/spider-sense .claude/skills/
cp -r /tmp/spider-sense/skills/spider-sense-sql-tuning .claude/skills/

A project-level copy is also what Cursor and GitHub Copilot read, so one directory serves three tools.

Codex

Codex reads skills from ~/.codex/skills for every project, and from a project’s own .codex/skills. Copy skills/spider-sense and skills/spider-sense-sql-tuning into either one.

Cursor

Cursor reads a project’s .cursor/skills/ and the user-level ~/.cursor/skills/. It also reads the project’s .claude/skills/, so a project already set up for Claude Code needs nothing more.

GitHub Copilot

Copilot reads a project’s .github/skills/, and ~/.copilot/skills/ for the coding agent and the CLI. It too reads the project’s .claude/skills/.

The manual is the source of truth

Nothing in the skills is new information. Every statement in them is this manual, compressed for an agent’s context window instead of a reader’s screen. A question a skill cannot settle is answered here, and a release that changes a command or a finding changes the skills alongside it.

A host without a shell is taught the same loop through the MCP server’s instructions field rather than through the skill, so neither host is taught something the other is not (MCP).