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. They have the same form as Spider Silk’s skill, and init installs a copy of every one of them into a project’s .claude/skills/.

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). The CLI’s help lists every command and option, but not the order to run them in or how to read a finding.

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. An agent reads it when a finding names a statement rather than a request. It reads the finding’s schema block for the indexes a table already has and the predicate columns none of them leads with, and designs the index from that rather than asking the database.

Every statement in both comes from this manual, and where a skill and the manual differ the manual is right.

What is in it

skills/spider-sense/SKILL.md carries what every task needs: what the CLI gives an agent that a dashboard does not (findings, marks, compare, check, and answers with the application down), 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 for reporting a result (quote only numbers the tool printed, name the trace id, run check before calling a fix done). The loop is the six steps of The Loop: start under the agent and confirm with status, mark before and exercise, read the top finding with its suspect-change lines first, fix and restart, mark after with compare and check, and resolve once check passes. Four reference files carry the rest, and an agent reads only the one its task touches.

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 it usually wants with Java examples, such as a fetch join or a batch for n-plus-one and an index or a rewrite for slow-query

references/running.md

starting each kind of application under the agent (Gradle run, Spring Boot bootRun, a plain java -jar, a test task), ports, forwarding, troubleshooting

references/sql.md

the tables and columns a query normally needs, and read-only SQL over them

SKILL.md states the rules the agent follows, and these five are among them. 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 also covers whatever ran in those 15 minutes before the run being measured. 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>] [--url=<base url>] [--gradle] [--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 or AGENTS.md (which file) 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 path of the distributable jar the command was started from. The launcher sets the system property spidersense.jar to its own absolute path before it invokes the CLI, because the CLI itself runs out of the nested server jar extracted to a temporary directory and could never find the distributable on its own. The path is written absolute, as given or as discovered, and never made relative to the project. When no jar path is known, which happens with exploded classes in an IDE and no --jar, init says which option it needs and exits 2.

--url is the base URL of the Spider Sense the project’s application sends to, such as http://127.0.0.1:4106. init asks nothing there. It writes the URL into the block, so the agent asks that Spider Sense rather than the one on the default port. The URL is written as the CLI reads it: trailing slashes go, and one typed without a scheme, such as 127.0.0.1:4106, gets http:// in front (The direct-file fallback).

--gradle says that the project applies the Gradle plugin. The block then starts the application with the plugin’s bootRun and runs the CLI through the plugin’s spiderSense task. spiderSenseInit passes both options (The Gradle task).

The block

The block is delimited by <!-- spider-sense:start -→ and <!-- spider-sense:end -→, each on a line of its own. In a Gradle project, with neither --url nor --gradle, it reads as follows:

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

Spider Sense is a local-development observability tool 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>`.
Under Gradle, apply the `net.benelog.spidersense` plugin and run `./gradlew bootRun -PspiderSense.jar=/home/me/tools/spider-sense.jar` (or `run`): it puts the agent on the application's JVM and not on the Gradle daemon.
When the start command is not yours to change, `JAVA_TOOL_OPTIONS="-javaagent:/home/me/tools/spider-sense.jar" <command>` attaches it; a `./gradlew` command then needs `--no-daemon`, or the daemon hosts a Spider Sense of its own on port 4000.
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 findings --since=15m  # the last 15 minutes instead; start exists once the application has reported
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, /home/me/tools/spider-sense.jar, is the one init resolved, and every other line is written exactly as shown. A jar path that holds a space, or any character a shell would split or expand at, is quoted in the commands, so the agent can copy each into a shell as it stands. A word of a command is in single quotes, with each ' of the path written '\'': java -javaagent:'/opt/my tools/spider-sense.jar' -jar <app jar>. Inside JAVA_TOOL_OPTIONS, whose own quotes the JVM reads, the path is in single quotes, or in double quotes when it holds a ', and a path that holds both has each ' as "'" between single-quoted runs, which the JVM joins: JAVA_TOOL_OPTIONS="-javaagent:'/opt/my tools/spider-sense.jar'" <command>. There a $, a backtick and a " get a \, because the shell still reads them inside the variable’s double quotes. The sentence that names where the jar is keeps it unquoted. One method, Init.block, generates the block, and a test compares its output with the block printed above. Without --url the block names no port of the project, only the Spider Sense UI’s own default, http://127.0.0.1:4000. The --since=15m line stands beside --since=start because start is a mark Spider Sense records when an application first reports (Automatic start marks), so before that --since=start names no mark.

The build files in --dir and the options --gradle and --url change a few lines, and nothing else does, so one directory and one command line always give the same block.

When What changes

build.gradle, build.gradle.kts, settings.gradle or settings.gradle.kts in --dir, and no pom.xml

nothing: the block above

pom.xml in --dir, and none of the Gradle files

The Gradle sentence becomes "Under Maven, run mvn spring-boot:run -Dspring-boot.run.agents=<jar>: the Spring Boot plugin puts the agent on the JVM it forks for the application." The JAVA_TOOL_OPTIONS sentence ends at attaches it., with nothing about ./gradlew (Maven).

Both, or neither

Both sentences, the Gradle one first, because init does not guess the build tool of a directory that has both kinds of build file or neither.

--gradle

The build-tool sentences become "This project applies the net.benelog.spidersense Gradle plugin, so ./gradlew bootRun (or run) starts it under Spider Sense: the plugin puts the agent on the application’s JVM and not on the Gradle daemon." Every CLI line becomes the plugin’s task, such as ./gradlew -q spiderSense --args="findings --since=start", which asks the Spider Sense the build’s spiderSense { } block names (Tasks).

--url=<base url>

The UI sentence becomes The UI is then at <base url>. Without --gradle, every CLI line but help ends in --url=<base url>, such as java -jar /home/me/tools/spider-sense.jar findings --since=start --url=http://127.0.0.1:4106.

When --no-skill kept the skills from being installed, 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.

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. A file that does not exist is created with the block alone, and one that exists without the markers gets the block appended after one blank line. A file with a start marker and no end marker after it, which is a block whose end was edited away, stops init before it writes anything, with a message on stderr naming the file and the marker’s line and exit code 2, because a second block appended after it would have the next run replace the text in between.

The block goes into the file the project’s agent reads. Claude Code reads CLAUDE.md, and Codex and most other agents read AGENTS.md.

The project has The block goes into

CLAUDE.md, or neither file

CLAUDE.md, created when it is not there

AGENTS.md and no CLAUDE.md

AGENTS.md

both

both, the same block in each

The skill copy

init copies every directory under skills/, with its SKILL.md and references/*.md, into <dir>/.claude/skills/ under the same name. --no-skill skips all of them, and so does --mcp. It overwrites the files it owns and leaves anything else in those directories alone. A skill whose directory, or a directory or file in it, is a symbolic link is left as it is, link and target, because a skill kept elsewhere and linked into the project is not init’s to write: its skill line becomes `left /home/me/project/.claude/skills/spider-sense, which is a link.

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 are packaged inside the jar, so no checkout is needed. The server module’s build packages the repository’s whole skills/ directory into its resources under spider-sense/skills/, together with a generated spider-sense/skills/index.txt that lists the paths relative to skills/ (spider-sense/SKILL.md, spider-sense/references/cli.md, spider-sense-sql-tuning/SKILL.md, and so on), because a class loader cannot list a directory. A new skill is therefore a new directory under skills/ and nothing else. The repository’s skills/ stays the single source, and nothing is duplicated under src/main/resources.

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)

init prints one line each on stdout: the block, then one line per skill in the index’s order, each with the number of files it wrote. The first line is updated CLAUDE.md block (…) when the markers were already in the file, and names AGENTS.md when the block went there. When it went into both files, there are two block lines, CLAUDE.md first. The skill lines become the single line skipped skills (--no-skill) when the skills were not installed. --url and --gradle change the block and none of these lines.

--mcp hands the host the MCP server instead of the CLI, because the manual warns against enabling both in one host (Choosing an interface). It writes the stdio MCP server into the project’s .mcp.json and adds a last line, wrote .mcp.json (spider-sense over stdio) or updated .mcp.json (…) (Configuring a host). A --url goes into the server’s arguments as well as into the block, because with --mcp the agent asks through the server and through nothing else. It installs no skill, and the skill lines become skipped skills (--mcp), because both skills teach the loop through the CLI and the server’s instructions carry it instead. The skills an earlier init installed go: their files are deleted, and so is each directory they leave empty, while a file init did not install stays, and the skill lines become one per skill, such as removed skill from /home/me/project/.claude/skills/spider-sense (5 files). A file counts as installed when it holds the bytes this jar carries for it, so one edited by hand, or written by an init of another version, stays, and init prints left <file>, which differs from this jar’s copy for it. A linked skill stays whole, link and target, with the line left <directory>, which is a link. The block keeps its first paragraph, with the jar and the ways to start the application under it, and in place of the CLI’s lines and the skill lines it reads:

Ask it through the tools of the `spider-sense` MCP server in `.mcp.json`: `status` first, to confirm the application is collecting, then `mark`, `findings`, `trace`, `compare`, `check` and `resolve`; the server's instructions carry the loop.

An existing .mcp.json that is not a JSON object stops init before it writes anything, with a message on stderr and exit code 2. Without --mcp, init writes no server, because a host with a shell is meant to use the CLI, and init should not hand it a second tool for the same answers. It takes away the spider-sense server an earlier init --mcp wrote into .mcp.json, keeping every other entry, and prints removed spider-sense from .mcp.json as its last line; a .mcp.json without that server, or one it cannot read as a JSON object, it leaves alone and says nothing about.

init reads every file it changes, and checks that it can write every file it writes, before it writes any, so a file it cannot read or write stops it the same way, with the file named. A read-only CLAUDE.md, AGENTS.md or .mcp.json, or a .claude it cannot create the skills in, prints spider-sense: /home/me/project/.mcp.json is not writable; nothing was written. A file that is not UTF-8, such as a CLAUDE.md saved as UTF-16, prints spider-sense: could not read /home/me/project/CLAUDE.md: not UTF-8; nothing was written. It writes the skills and .mcp.json before the block that names them, so a write that fails all the same never leaves a block naming what is not there; it prints the lines of what was written, then spider-sense: could not write <file>: <reason> with the operating system’s reason, and exits 2.

The command then exits 0.

The Gradle task

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

./gradlew spiderSenseInit

It also passes --gradle, so the block starts the application with ./gradlew bootRun and asks with ./gradlew -q spiderSense --args="…". When the spiderSense { } block names a collector, a host or a port, it passes --url= with the base URL they imply, so the block’s UI line names the port the application’s Spider Sense listens on.

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 to install the skills, and it installs them 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. Copying the directories there by hand gives the same result, and collaborators then get the skills by cloning the project 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/

Cursor and GitHub Copilot also read the project’s .claude/skills/, 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. Copilot also reads the project’s .claude/skills/.

The manual is the source of truth

Nothing in the skills is new information. Every statement in them comes from this manual, shortened so that a skill fits in an agent’s context window. What a skill leaves out is in this manual, and a release that changes a command or a finding changes the skills in the same release.

A host without a shell is taught the same loop through the MCP server’s instructions field rather than through the skill, so a host on MCP gets the same steps as a host on the CLI (MCP).