HOW IT WORKS
How it works
You don't learn commands or call skills by name. You say what you want in plain English. The agent finds the skill that fits, follows it, proves the bug, then moves to the next lead on its own. This page shows exactly what that looks like — what you say, what comes back, how it moves from one step to the next, and what it leaves on disk.
# The mental model
1 · You describe
State the target, that it's authorized, and what you want ("test this API for access-control bugs"). No skill names, no flags.
2 · It matches & loads
Each skill's description is a
trigger line packed with signals. The agent loads the one that fits and works its
Method section.
3 · It proves & pivots
It confirms impact with the least action, writes it down, and the finding becomes the lead that loads the next skill.
Scope is always first. Before anything touches a
target, the agent loads tradecraft-scope-roe and confirms authorization. If scope is
unclear it stops and asks. See Authorized Use.
# How to talk to it
Good requests carry three things: the target, that it's authorized, and the goal. The more concrete the signals (URL, tech, vuln class), the more precisely the right skill loads.
Reaches the right skill
Too vague — it'll ask first
You can also name a skill if you want to force it — "use web-ssrf on the import feature" — but you rarely need to. Describing the situation is enough.
# A full session, annotated
Here is one authorized engagement from first message to report. Each block is what you'd actually see; the notes explain what happened and where it pivots.
*.acme.tld weren't in the program, it would refuse here./api/v1/orders is a strong BOLA signal — that lead is what loads the next skill.exploit-chaining is loaded when several findings combine into
something worse than any one alone.# How pivoting works
A "pivot" is just: a result becomes the trigger for the next skill. The agent works one lead at a time and loads the next skill as the evidence points to it. The routing is signal-driven:
| What it just saw (the lead) | What loads next |
|---|---|
| A new in-scope domain, nothing mapped yet | recon-* → recon-techstack-fingerprinting |
| Numeric/UUID object IDs in an API | api-bola, web-idor |
| App fetches a URL you control (webhook, "import") | web-ssrf |
| A parameter names a file/template | web-lfi-path-traversal, web-ssti |
| Two small bugs that combine | exploit-chaining |
| Valid creds / a foothold on an internal net | privesc-*, ad-*, network-pivoting-tunneling |
| A captured hash or handshake | network-credential-cracking |
| A confirmed finding, ready to write up | reporting-triage-validation → reporting-* |
The overall shape is always the same loop — scope → recon → attack → foothold → escalate → report → (defend) — but which skills fire, and in what order, is driven entirely by what the target reveals.
# What an engagement produces
Everything is kept in a per-target workspace — run ./secskills new <target>
to scaffold it — so notes and loot never mix between engagements. These paths are git-ignored,
so they never end up in the repo.
engagements/acme/ scope.txt # the authorized targets — the hard boundary roe.md # rate limits, don'ts, disclosure terms notes.md # timestamped running log — the source of truth findings/ # one file per confirmed finding + evidence loot/ # captured artifacts (kept minimal)
A notes.md entry reads like the mechanism, not just a command:
# 14:32 goal: confirm cross-tenant read on /api/v1/orders
cmd: GET /api/v1/orders/1041 (account B token)
result: 200 — returns account A's order (name, address, total)
why: object id trusted; ownership never re-checked at the data layer
next: test PATCH /users/{id} for write-IDOR → possible ATO chain
Because the log records why it worked and the next lead, the report almost writes itself — and you can hand the workspace to a teammate and they can continue.
# Steering it
Modes
Each skill is tagged pentest, bugbounty,
and/or defense. Say which you're doing — a destructive step safe in a lab won't run
against a live bug-bounty target, and human-factor (social-eng-*) is pentest-only.
Keep it in bounds
It refuses out-of-scope and third-party targets, honors rate limits, and proves impact with the least data. Tell it to "stop at proof" or "don't touch X" and it will.
Force or skip a skill
"Use web-ssti here" loads it directly; "skip cracking, just report the weak PSK" steers past a step you don't want.
Go defensive
The same library turns findings into detections and
hardening — "convert this into a Sigma rule" loads defense-detection-sigma.
# Using one skill on its own
You don't need a whole engagement. Any single SKILL.md is readable on its
own — open it, or paste it into any agent, to get the mechanism, the exact commands, the gotchas,
and how to verify success for that one technique.
# read a skill directly cat skills/web/web-ssrf/SKILL.md # or ask the agent for just that technique › walk me through testing this import feature for SSRF