feat: agent-ready — installable SKILL.md skills, AGENTS.md, coding-agents docs

AGENTS.md

@@ -0,0 +1,39 @@
+# Strix — Agent Guide
+
+Strix is an open-source autonomous AI pentesting tool. This file is for AI coding agents that want to **use** Strix (run security scans) or **contribute** to it.
+
+## Using Strix from an agent
+
+Install the agent skills for step-by-step workflows:
+
+```bash
+npx skills add usestrix/strix
+```
+
+- `strix-pentest` — run a headless pentest against code, URLs, domains, or IPs and read results
+- `strix-fix-findings` — remediate findings and re-run Strix to verify
+- `strix-ci-setup` — add diff-scoped PR scanning to CI/CD
+
+Quick reference (details in the skills and https://docs.strix.ai):
+
+```bash
+curl -sSL https://strix.ai/install | bash        # install
+export STRIX_LLM="openai/gpt-5.4"                 # any LiteLLM model id
+export LLM_API_KEY="<key>"
+strix -n -t ./ --scan-mode quick --max-budget 10  # headless scan; always use -n
+```
+
+- Requires Docker running. Scans take minutes (`quick`) to hours (`deep`) — run in the background.
+- Exit codes (headless): `0` clean, `1` fatal error, `2` vulnerabilities found.
+- Artifacts in `strix_runs/<run-name>/`: `penetration_test_report.md`, `vulnerabilities/*.md`, `vulnerabilities.json`, `findings.sarif` (SARIF 2.1.0), `run.json`.
+- Docs index for LLMs: https://docs.strix.ai/llms.txt (full: https://docs.strix.ai/llms-full.txt).
+- Only scan targets the user is authorized to test.
+
+## Contributing to this repo
+
+- Python 3.12+, managed with `uv`. Install dev deps: `make dev-install`.
+- Lint/format/type-check/security, all in one: `make check-all` (ruff, mypy, bandit).
+- Tests: `uv run pytest`.
+- Run from source: `uv run strix --target <target>`.
+- Layout: `strix/agents` (agent graph + prompts), `strix/tools` (proxy, browser, terminal, scanners), `strix/runtime` (Docker sandbox), `strix/report` (findings, SARIF), `strix/skills` (internal knowledge packs the pentest agents load — different from the consumer skills in `skills/`), `strix/interface` (CLI/TUI), `containers/` (sandbox image).
+- Pre-commit hooks: `make pre-commit` (or `uv run pre-commit install`).

README.md

@@ -94,6 +94,18 @@ strix --target ./app-directory
 
 ---
 
+## 🤖 Use Strix from Your Coding Agent
+
+Strix is agent-ready. Give Claude Code, Cursor, Codex, or any [SKILL.md-compatible](https://agentskills.io) agent the ability to run pentests, fix findings, and set up CI scanning:
+
+```bash
+npx skills add usestrix/strix
+```
+
+This installs three skills: **strix-pentest** (run headless scans and read results), **strix-fix-findings** (remediate + re-scan to verify), and **strix-ci-setup** (diff-scoped PR scanning in CI). Agents can also read [`AGENTS.md`](AGENTS.md) for a quick reference and [docs.strix.ai/llms.txt](https://docs.strix.ai/llms.txt) for the full docs index.
+
+---
+
 ## ☁️ Strix Platform
 
 Try the Strix full-stack penetration testing platform at **[app.strix.ai](https://app.strix.ai)** - sign up for free, connect your repos and domains, and launch a pentest in minutes.

docs/docs.json

@@ -46,7 +46,8 @@
             "group": "Integrations",
             "pages": [
               "integrations/github-actions",
-              "integrations/ci-cd"
+              "integrations/ci-cd",
+              "integrations/coding-agents"
             ]
           },
           {

docs/integrations/coding-agents.mdx

@@ -0,0 +1,52 @@
+---
+title: "Coding Agents"
+description: "Use Strix from Claude Code, Cursor, Codex, and other AI agents"
+---
+
+Strix is built to be driven by AI coding agents. Install the official agent skills and your agent knows how to run pentests, remediate findings, and wire Strix into CI.
+
+## Install the Skills
+
+Works with any agent that supports the open [SKILL.md standard](https://agentskills.io) — Claude Code, Cursor, Codex, Gemini CLI, OpenCode, and dozens more:
+
+```bash
+npx skills add usestrix/strix
+```
+
+| Skill | What your agent learns |
+|-------|------------------------|
+| `strix-pentest` | Run headless scans against code, URLs, domains, or IPs with budget caps, and read the results |
+| `strix-fix-findings` | Triage findings, fix root causes, and re-run Strix to verify each fix |
+| `strix-ci-setup` | Add diff-scoped PR security scanning to GitHub Actions or any CI |
+
+Install a single skill with `npx skills add usestrix/strix --skill strix-pentest`, or use one without installing:
+
+```bash
+npx skills use usestrix/strix@strix-pentest | claude
+```
+
+## Agent-Friendly Interfaces
+
+Everything an agent needs is machine-readable:
+
+- **Headless CLI** — `strix -n` runs without the TUI and exits with `0` (clean), `1` (error), or `2` (vulnerabilities found).
+- **Structured results** — every run writes `vulnerabilities.json`, `vulnerabilities.csv`, `findings.sarif` (SARIF 2.1.0), and per-finding Markdown under `strix_runs/<run-name>/`.
+- **Budget controls** — `--max-budget` and `--max-turns` give agents hard cost/time caps.
+- **`AGENTS.md`** — the [repository's agent guide](https://github.com/usestrix/strix/blob/main/AGENTS.md) with a quick reference.
+- **`llms.txt`** — this documentation is indexed at [docs.strix.ai/llms.txt](https://docs.strix.ai/llms.txt) and fully exported at [docs.strix.ai/llms-full.txt](https://docs.strix.ai/llms-full.txt); every page is also available as Markdown by appending `.md` to its URL.
+
+## Example Prompts
+
+Once the skills are installed, prompts like these just work:
+
+```text
+Pentest this repo with Strix (quick mode, $10 budget) and summarize the findings.
+```
+
+```text
+Fix all critical and high findings from the last Strix run, then re-scan to verify.
+```
+
+```text
+Add Strix security scanning to our GitHub Actions so every PR gets tested.
+```

skills/strix-ci-setup/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: strix-ci-setup
+description: Wire Strix security scanning into CI/CD — GitHub Actions, GitLab CI, or any pipeline — so every pull request gets a diff-scoped AI pentest that blocks vulnerable code. Use when the user asks to add security scanning, pentesting, or Strix to their CI pipeline or PR workflow.
+license: Apache-2.0
+metadata:
+  author: usestrix
+  homepage: https://docs.strix.ai
+---
+
+# Set up Strix in CI/CD
+
+Run a diff-scoped Strix scan on every PR: only changed files are tested, `quick` mode keeps it fast, and exit code `2` fails the build when validated vulnerabilities are found.
+
+## GitHub Actions
+
+Create `.github/workflows/security.yml`:
+
+```yaml
+name: Security Scan
+
+on:
+  pull_request:
+
+jobs:
+  strix-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # required for diff-scope resolution
+
+      - name: Install Strix
+        run: curl -sSL https://strix.ai/install | bash
+
+      - name: Run Security Scan
+        env:
+          STRIX_LLM: ${{ secrets.STRIX_LLM }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+        run: strix -n -t ./ --scan-mode quick --max-budget 10
+```
+
+Then tell the user to add two repository secrets: `STRIX_LLM` (model id, e.g. `openai/gpt-5.4`) and `LLM_API_KEY` (the provider key). Do not create these values yourself.
+
+Notes:
+- In CI/headless runs Strix automatically scopes to the PR's changed files (`--scope-mode auto`). If diff resolution fails, keep `fetch-depth: 0` or pass `--diff-base origin/main`.
+- Exit codes: `0` pass, `2` vulnerabilities found (fails the job), `1` setup error.
+- The runner needs Docker (default GitHub-hosted Ubuntu runners have it).
+
+### Optional: upload findings to GitHub code scanning
+
+Strix writes SARIF 2.1.0 to `strix_runs/<run>/findings.sarif`:
+
+```yaml
+      - name: Upload SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: strix_runs
+```
+
+## Other CI systems
+
+Any pipeline works the same way — install, set the two env vars, run headless:
+
+```bash
+curl -sSL https://strix.ai/install | bash
+strix -n -t ./ --scan-mode quick --scope-mode diff --diff-base origin/main --max-budget 10
+```
+
+Gate the pipeline on the exit code. Schedule `standard` scans nightly and `deep` scans for release candidates.
+
+## Hosted alternative
+
+If the user prefers zero CI setup, the managed platform at https://app.strix.ai reviews every PR via the GitHub/GitLab/Bitbucket app with no workflow file or LLM key required.

skills/strix-fix-findings/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: strix-fix-findings
+description: Triage and remediate vulnerabilities found by a Strix pentest, then re-run Strix to verify each fix. Use after a Strix scan reports findings, or when the user asks to fix security issues from a strix_runs report, vulnerabilities.json, or findings.sarif.
+license: Apache-2.0
+metadata:
+  author: usestrix
+  homepage: https://docs.strix.ai
+---
+
+# Fix Strix findings and verify
+
+Turn validated Strix findings into minimal, correct fixes — and prove they work by re-scanning.
+
+## 1. Triage
+
+Read the artifacts in `strix_runs/<run-name>/`:
+
+- `vulnerabilities/*.md` — one finding per file: description, severity, PoC steps or script, affected code locations, remediation guidance.
+- `vulnerabilities.json` — the same findings as JSON (ids, severity, CWE/CVE, `code_locations` with `fix_before`/`fix_after` suggestions when available).
+
+Order work by severity: critical → high → medium → low. Every Strix finding was validated with a working proof-of-concept, so do not dismiss findings as false positives without re-testing the PoC yourself.
+
+## 2. Fix
+
+For each finding:
+
+1. Reproduce it with the PoC from the finding file when feasible.
+2. Fix the root cause, not the specific payload (e.g. parameterize all queries, don't blocklist one string; enforce authorization in the handler, don't hide the endpoint).
+3. Prefer the framework's built-in defense (ORM parameterization, template auto-escaping, CSRF middleware, centralized authz) over ad-hoc sanitization.
+4. Keep the diff minimal and apply the repo's existing patterns. Finding files often include `fix_before`/`fix_after` snippets — use them as a starting point, not verbatim.
+
+Common finding classes and expected fixes: injection → parameterization/escaping at the sink; IDOR/broken access control → object-level authorization checks; SSRF → allowlist + block internal ranges; XSS → context-aware output encoding + CSP; secrets exposure → rotate the secret AND remove it from code/history; auth issues → fix the server-side check (never client-side).
+
+## 3. Verify by re-running Strix
+
+After fixing, re-run Strix scoped to the fixed area and confirm the finding is gone:
+
+```bash
+# Re-test just the changed files (fast)
+strix -n -t ./ --scan-mode quick --scope-mode diff --diff-base origin/main --max-budget 5
+
+# Or re-test with the original finding as focus
+strix -n -t ./ --instruction "Verify the SQL injection in app/api/search.py is fixed. Original PoC: <poc>" --max-budget 5
+```
+
+- Exit code `0` = clean; `2` = findings remain (read the new `strix_runs/<run>/vulnerabilities/` and iterate).
+- Also re-run the PoC manually when it is a simple request/script — fastest signal.
+- Run the project's own test suite to make sure the fix doesn't break behavior.
+
+## 4. Report
+
+Summarize per finding: severity, root cause, fix applied (file:line), verification result (re-scan clean / PoC no longer reproduces). Never include live secrets in the report; if a secret leaked, state that rotation is required.

skills/strix-pentest/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: strix-pentest
+description: Run an autonomous AI penetration test with the Strix CLI against a local codebase, repository, URL, domain, or IP — headlessly, with cost/turn budgets — and read the validated findings (Markdown, JSON, CSV, SARIF) from the run directory. Use when the user asks to pentest, security-scan, or find vulnerabilities in an app, API, website, or repo with Strix.
+license: Apache-2.0
+metadata:
+  author: usestrix
+  homepage: https://docs.strix.ai
+---
+
+# Run a Strix pentest
+
+Strix runs autonomous AI pentesting agents in an isolated Docker sandbox. They dynamically exploit the target and only report findings validated with a working proof-of-concept.
+
+## Prerequisites
+
+1. **Docker running** — check with `docker info`. The first scan pulls the sandbox image automatically.
+2. **Strix installed** — check with `strix --version`. Install if missing:
+   ```bash
+   curl -sSL https://strix.ai/install | bash   # or: pipx install strix-agent
+   ```
+3. **LLM configured** — two environment variables:
+   ```bash
+   export STRIX_LLM="openai/gpt-5.4"      # any LiteLLM model id (openai/..., anthropic/..., openrouter/...)
+   export LLM_API_KEY="<provider api key>"
+   ```
+   Ask the user for these if unset. Never hardcode or commit keys.
+
+## Running a scan
+
+Always use `-n` (non-interactive/headless) when you run Strix — the default TUI blocks agents. Always set `--max-budget` unless the user says otherwise.
+
+```bash
+# Local code (white-box)
+strix -n -t ./ --scan-mode standard --max-budget 10
+
+# Deployed app / API (black-box)
+strix -n -t https://staging.example.com --max-budget 20
+
+# Repo + deployed app together (best coverage)
+strix -n -t https://github.com/org/app -t https://staging.example.com
+
+# Focused testing with credentials or scope hints
+strix -n -t https://app.example.com \
+  --instruction "Use credentials user@example.com:pass123. Focus on IDOR and auth bypass."
+
+# Large monorepo: bind-mount instead of copying
+strix -n --mount ./huge-monorepo
+```
+
+Key flags:
+
+| Flag | Meaning |
+|---|---|
+| `-t, --target` | URL, repo URL, local path, domain, or IP. Repeatable. |
+| `-n, --non-interactive` | Headless, exits on completion. Required for agents. |
+| `-m, --scan-mode` | `quick` (minutes) / `standard` (~30 min) / `deep` (hours, default). |
+| `--instruction` / `--instruction-file` | Credentials, focus areas, scope rules. |
+| `--max-budget USD` | Hard LLM spend cap; scan wraps up cleanly at the limit. |
+| `--max-turns N` | Per-agent turn cap (default 500). |
+| `--resume RUN_NAME` | Resume a prior run from `strix_runs/`. |
+
+Scans take minutes (`quick`) to hours (`deep`). Run them in the background and poll for completion rather than blocking.
+
+## Exit codes (headless)
+
+- `0` — scan completed, no vulnerabilities
+- `1` — fatal error (missing env vars, Docker down, bad config)
+- `2` — vulnerabilities found
+
+## Reading results
+
+Artifacts land in `strix_runs/<run-name>/`:
+
+| File | Contents |
+|---|---|
+| `penetration_test_report.md` | Executive report — read this first. |
+| `vulnerabilities/*.md` | One file per validated finding, with PoC and remediation. |
+| `vulnerabilities.json` / `vulnerabilities.csv` | All findings as structured JSON / CSV index. |
+| `findings.sarif` | SARIF 2.1.0 for GitHub code scanning / ASPM ingestion. |
+| `run.json` | Run metadata, status, targets, usage/cost. |
+
+Summarize findings by severity (critical/high/medium/low/info) and include the PoC evidence when reporting to the user. To fix the findings, use the `strix-fix-findings` skill.
+
+## Safety
+
+Only scan targets the user owns or is authorized to test. If the target looks like third-party infrastructure, confirm authorization first.