How to use the Security Audit agent skill (security-audit)

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file and supporting reference files. An agent that loads SKILL.md skills, such as Claude Code, reads these instructions when a task matches the skill's description, so it follows a specific method instead of general habits.

Once installed, this skill makes the agent look for weaknesses that cross a real trust boundary, for example one user reaching another user's data. Each finding is explained with source-code evidence, a safe way to reproduce it, a priority, and the smallest sensible fix.

• Guidance mode (default): answers security questions and runs focused reviews without creating files.
• Full audit mode: runs a six-phase workflow and writes report files, including a REPORT.md and FINDINGS-DETAIL.md, and may run sandboxed local tests.

How do you install the Security Audit skill?

Download the ZIP for skills/security-audit from the directory page and unzip it. Then place the resulting folder in one of two locations: your user skills folder at ~/.claude/skills/, or a project-specific folder at .claude/skills/ inside the repository you are working in.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/ (available across your projects).
• Project install: .claude/skills/ inside one repository (shared with that project).

How do you trigger the skill with natural requests?

You do not need a special command. Describe the task in plain language. The skill's description covers security questions, focused reviews, vulnerability research, security audits and pen tests, so requests like the ones below will load it.

Be explicit when you want the full workflow. The skill runs the complete audit only for an explicit codebase audit or pen-test request, a full, comprehensive or end-to-end review, or a request for report artifacts. If your request could mean either mode, the skill is designed to ask one focused question before creating any files.

• Guidance: "Is this JWT validation in our login handler safe?"
• Focused review: "Review the file upload code in src/uploads for path traversal."
• Full audit: "Run a full security audit of this repository and write the report files."
• Pen test: "Perform an explicit pen-test style review of the API service in this repo."

What does a full audit produce?

In full audit mode the agent runs all six phases and writes files to an output directory. By default this is a new run folder under ~/security-audit-skill/<repo-name>/ outside the target repository. The shared run files include run-metadata.json, architecture.md, coverage-ledger.json, findings.json, REPORT.md, FINDINGS-DETAIL.md and NEEDS-VALIDATION.md.

Findings that depend on a deployment, provider, platform or runtime fact that is not available locally are listed as needs-validation rather than confirmed. The skill explains the missing fact and a safe local or owner-side check that would resolve it.

What does the skill need before it runs?

The skill needs an agent that loads SKILL.md skills. For full audit mode that includes sandboxed execution, it also needs a local OS-level sandbox able to enforce no network access, a read-only target, and resource limits before any target code runs. Without that sandbox, the skill only reports needs-validation items and does not execute target code.

It uses whatever build tools the target project already has installed locally. The skill says not to install dependencies, so prepare the project's tooling before you start.

• Agent that loads SKILL.md files (for example Claude Code).
• For full audit mode: a local OS-level sandbox with no network, read-only target and resource limits.
• Build tools already installed locally for the target project. No dependency installation.

What are the safety limits you should know about?

The skill runs scripts, but it does not use the network. Source inspection is read-only. Target-controlled builds, tests and processes only run inside an OS-enforced sandbox with an empty environment, a read-only target, output limited to a scratch folder, and explicit CPU, memory, process, file-size, disk and time limits.

The skill is written to use dummy principals and fixtures, and it explicitly forbids probing deployed endpoints, external services, shared infrastructure or production identities. Those rules guide the agent, but they do not replace your own judgement: do not point it at systems you do not own or have permission to test.

• Runs scripts: yes. Uses network: no.
• Does not probe live or production systems.
• Does not publish artifacts, alter releases, or spend paid API quota.
• Not a replacement for a professional penetration test or formal security certification; it is limited to the files and sandboxed checks it can run.

What tips help you get useful results?

Start with a focused question about one file, handler or trust boundary. Narrow requests produce more precise evidence than asking for everything at once. Use the full audit only when you want a complete, reportable review, since it writes files and takes longer.

Read the needs-validation list carefully. Those items are not failures of the skill; they are facts that only you or your deployment can confirm.

• Name the trust boundary you care about, such as tenant isolation or an auth callback.
• Share the target path so the agent reviews the right code.
• Treat needs-validation items as a checklist for your own environment.
• Keep the output folder outside the repository unless you have deliberately chosen otherwise and version control ignores it.