Parse skill frontmatter with YAML

.github/workflows/build-release.yml

@@ -70,7 +70,7 @@ jobs:
             TUI_NAME="strix-tui"
             dist/strix --version
           fi
-          uv run pyi-archive_viewer -l "$PYI_BINARY" | grep "strix/bin/$TUI_NAME" >/dev/null
+          uv run pyi-archive_viewer -l "$PYI_BINARY" | grep -E "strix[/\\]+bin[/\\]+$TUI_NAME" >/dev/null
 
           if [[ "${{ matrix.target }}" == "linux-arm64" ]]; then
             file dist/strix
@@ -118,4 +118,4 @@ jobs:
         with:
           prerelease: ${{ !startsWith(github.ref, 'refs/tags/') }}
           generate_release_notes: true
-          files: release/*
+          files: release/**

AGENTS.md

@@ -0,0 +1,49 @@
+# 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 (covers both run modes below)
+- `strix-cloud-api` — drive the managed app.strix.ai platform via REST (no local Docker/LLM needed)
+- `strix-fix-findings` — remediate findings and re-run Strix to verify
+- `strix-ci-setup` — add PR scanning to CI/CD (self-hosted CLI or managed app)
+
+**Two ways to run, same engine — pick per situation:**
+
+- **Open-source CLI (self-hosted):** free, fully local, BYO LLM key, needs Docker. Best for local dev loops, air-gapped/offline, and full control.
+  ```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. A `0` only covers what was analyzed — check `run.json` (`status`, `llm_usage.cost` vs the budget) before calling a run clean.
+  - Artifacts in `strix_runs/<run-name>/`: `penetration_test_report.md`, `vulnerabilities/*.md`, `vulnerabilities.json`, `findings.sarif` (SARIF 2.1.0), `run.json`.
+
+- **Managed cloud (app.strix.ai):** no Docker, no LLM key, no local install; adds team dashboards, scheduling, PR reviews, and downloadable PDF/DOCX reports (Enterprise plan). Best in sandboxed/CI environments and for teams. Use it when local infra isn't available.
+  ```bash
+  # token from Settings → API Access; register the target as an asset, then:
+  curl -sS https://app.strix.ai/api/v1/scans -H "Authorization: Bearer $STRIX_API_TOKEN" \
+    -H "Content-Type: application/json" -d '{"engagement_type":"live_test","domain_ids":["<uuid>"]}'
+  ```
+  - API docs: https://docs.app.strix.ai (OpenAPI: https://docs.app.strix.ai/openapi.json).
+
+- CLI 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

@@ -108,6 +108,18 @@ Try the Strix full-stack penetration testing platform at **[app.strix.ai](https:
 
 ---
 
+## 🤖 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 four skills: **strix-pentest** (run headless scans and read results), **strix-cloud-api** (drive the managed [app.strix.ai](https://app.strix.ai) platform via REST — no local Docker or LLM key), **strix-fix-findings** (remediate + re-scan to verify), and **strix-ci-setup** (PR scanning in CI). Agents can run Strix two ways with the same engine — the open-source CLI locally, or the managed cloud when there's no local infra — and read [`AGENTS.md`](AGENTS.md) for a quick reference, [docs.strix.ai/llms.txt](https://docs.strix.ai/llms.txt) for the CLI docs, and [docs.app.strix.ai](https://docs.app.strix.ai) for the API.
+
+---
+
 ## ✨ Features
 
 ### Agentic Pentesting Tools
@@ -337,6 +349,7 @@ Strix builds on the incredible work of open-source projects like [LiteLLM](https
 
 
 > [!WARNING]
-> Only test apps you own or have permission to test. You are responsible for using Strix ethically and legally.
+> **Authorized use only.** Strix actively tests the targets you point it at, so only run it against systems you own or have **explicit, written permission** to test, and stay within the agreed scope. Unauthorized testing is illegal in most jurisdictions.
+> You alone are responsible for obtaining authorization and complying with the law. Strix is provided "as is" with no warranty or liability for misuse.
 
 </div>

docs/advanced/configuration.mdx

@@ -110,7 +110,7 @@ When remote vars are set, Strix dual-writes telemetry to both local JSONL and th
 
 ## Docker Configuration
 
-<ParamField path="STRIX_IMAGE" default="ghcr.io/usestrix/strix-sandbox:1.2.0" type="string">
+<ParamField path="STRIX_IMAGE" default="ghcr.io/usestrix/strix-sandbox:1.3.0" type="string">
   Docker image to use for the sandbox container.
 </ParamField>
 

docs/advanced/skills.mdx

@@ -68,10 +68,10 @@ Framework-specific testing patterns.
 
 Third-party service and platform security.
 
-| Skill                | Coverage                           |
-| -------------------- | ---------------------------------- |
-| `supabase`           | Supabase RLS bypasses, auth issues |
-| `firebase_firestore` | Firestore rules, Firebase auth     |
+| Skill      | Coverage                                               |
+| ---------- | ------------------------------------------------------ |
+| `supabase` | Supabase RLS bypasses, auth issues                     |
+| `firebase` | Firebase Firestore, Storage rules, Auth, and Functions |
 
 ### Protocols
 

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,61 @@
+---
+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 — self-hosted CLI or managed cloud — with budget caps, and read the results |
+| `strix-cloud-api` | Drive the managed [app.strix.ai](https://app.strix.ai) platform over REST — no local Docker or LLM key needed |
+| `strix-fix-findings` | Triage findings, fix root causes, and re-run Strix to verify each fix |
+| `strix-ci-setup` | Add PR security scanning to GitHub Actions or any CI (self-hosted CLI or managed app) |
+
+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
+```
+
+## Two ways to run — self-hosted or managed
+
+Both use the same engine and produce the same validated findings and SARIF, so agents can pick per situation or combine them:
+
+- **Open-source CLI (self-hosted)** — runs locally in a Docker sandbox with your own LLM key. Free, fully local, air-gap capable. Best for local dev loops and full control.
+- **Managed cloud** — runs on Strix's infrastructure via the [app.strix.ai REST API](https://docs.app.strix.ai). No Docker, no LLM key, no local install; adds team dashboards, scheduling, PR reviews, and downloadable PDF/DOCX reports (Enterprise plan). Best in sandboxed/CI environments and for teams. Create an API token under **Settings → API Access**; the `strix-cloud-api` skill has the full flow.
+
+## 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).
+- **REST API** — the managed platform exposes a documented [OpenAPI](https://docs.app.strix.ai/openapi.json) at `https://app.strix.ai/api/v1` (scans, vulnerabilities, assets, PR reviews, schedules, webhooks) with bearer tokens and scopes.
+- **Structured results** — every run writes `vulnerabilities.json`, `vulnerabilities.csv`, `findings.sarif` (SARIF 2.1.0), and per-finding Markdown under `strix_runs/<run-name>/`; the cloud exposes the same as JSON plus SARIF export.
+- **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.
+```

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "strix-agent"
-version = "1.4.1"
+version = "1.5.0"
 description = "Open-source AI Hackers for your apps"
 readme = "README.md"
 license = "Apache-2.0"

scripts/install.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 
 APP=strix
 REPO="usestrix/strix"
-STRIX_IMAGE="ghcr.io/usestrix/strix-sandbox:1.2.0"
+STRIX_IMAGE="ghcr.io/usestrix/strix-sandbox:1.3.0"
 
 MUTED='\033[0;2m'
 RED='\033[0;31m'

skills/strix-ci-setup/SKILL.md

@@ -0,0 +1,136 @@
+---
+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. Covers both the self-hosted open-source CLI (runs in your runner) and the managed app.strix.ai platform (GitHub/GitLab app or API, no runner infra). 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
+
+You can gate PRs two ways — pick based on the environment, or combine them:
+
+- **Managed platform (recommended for most teams)** — connect the GitHub/GitLab/Bitbucket app once and Strix reviews every PR with **no workflow file, no runner, no Docker, and no LLM key**. Results post as PR comments and land in the team dashboard. Best when you want zero CI maintenance, central tracking, or your runners lack Docker. See "Managed platform" below and the **strix-cloud-api** skill.
+- **Self-hosted OSS CLI in your runner** — run a diff-scoped scan as a pipeline step. Fully in your infra, free (BYO LLM key), no external account. Requires Docker on the runner. Best for air-gapped/self-hosted CI or when you don't want scans leaving your environment.
+
+Both fail the build on validated findings and both emit SARIF 2.1.0, so you can start with one and add the other later.
+
+---
+
+# Option A — Self-hosted OSS CLI in the runner
+
+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
+
+      # Don't fail open: a run that hits the hard budget stop exits 0 but leaves
+      # run.json status "stopped", not "completed". Enforce completion explicitly.
+      # This does not catch an agent that wrapped up early on a budget *warning*
+      # (it still calls finish_scan and records "completed"), so size the budget.
+      - name: Fail unless the scan completed
+        run: |
+          run_json=$(ls -t strix_runs/*/run.json | head -1)
+          status=$(jq -r .status "$run_json")
+          if [ "$status" != "completed" ]; then
+            echo "Strix run status is '$status' — the scan did not complete (likely budget exhausted). Raise --max-budget." >&2
+            exit 1
+          fi
+```
+
+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 set `--diff-base` to the PR's actual base branch — use `origin/${{ github.base_ref }}` in GitHub Actions rather than a hard-coded `origin/main`, since repos use different default branches.
+- Exit codes: `0` pass, `2` vulnerabilities found (fails the job), `1` setup error.
+- The runner needs Docker (default GitHub-hosted Ubuntu runners have it).
+- **Size the budget so the scan completes — don't let it fail open.** A `0` exit means "no validated vulnerabilities in what was analyzed"; if `--max-budget` is hit before the diff is fully covered, the scan wraps up early and can still exit `0`. The "Fail unless the scan completed" step above narrows the gap: `strix_runs/<run>/run.json` is `"stopped"` when the scan was cut off at the hard budget limit without a final report. It is not a complete guard — the agents get graduated wrap-up warnings before that limit, and a run that wraps up on a warning still calls `finish_scan` and records `"completed"` with partial coverage. So keep that step in any pipeline that gates merges **and** give the scan real headroom (compare `run.json`'s `llm_usage.cost` against `--max-budget`; if it ran right up to the cap, raise it). For a `quick` diff-scoped PR scan `--max-budget 10` is usually ample, raise it for large diffs.
+
+### 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
+# Resolve the PR's base branch robustly (use your CI's base-branch variable if it
+# has one, e.g. GitHub Actions: origin/${{ github.base_ref }}). Avoid piping the
+# git lookup into another command — a failed lookup would otherwise be masked.
+BASE_BRANCH="${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-}"   # GitLab MR target
+if [ -z "$BASE_BRANCH" ]; then
+  BASE_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null)
+  BASE_BRANCH="${BASE_BRANCH#origin/}"
+fi
+DIFF_BASE="origin/${BASE_BRANCH:-main}"
+# Fail loudly rather than silently narrowing scope (e.g. to HEAD~1, which on a
+# multi-commit branch would scan only the last commit and let earlier ones pass).
+if ! git rev-parse --verify --quiet "$DIFF_BASE" >/dev/null; then
+  echo "Cannot resolve diff base '$DIFF_BASE'. Fetch the base branch (git fetch origin <base>) or set --diff-base explicitly." >&2
+  exit 1
+fi
+strix -n -t ./ --scan-mode quick --scope-mode diff --diff-base "$DIFF_BASE" --max-budget 10
+```
+
+Gate the pipeline on the exit code (see the budget/fail-open caveat above — give the scan enough budget to finish). Schedule `standard` scans nightly and `deep` scans for release candidates.
+
+---
+
+# Option B — Managed platform (no runner infra)
+
+No workflow file, no Docker, no LLM key. Two ways to use it:
+
+1. **PR-review app (zero code):** the user installs the Strix GitHub/GitLab/Bitbucket app and enables PR reviews for the repo in the app.strix.ai dashboard. Every PR is then reviewed automatically, with findings posted as PR comments. Nothing to add to the repo. This is the lowest-effort path — recommend it first when the user just wants PR gating.
+
+2. **API-triggered from any pipeline:** if you want to trigger from an existing pipeline (or a system without the SCM app), call the API with a token that has `pr_reviews:write` (or `scans:write`). Store the token as a CI secret; ask the user to create it at **Settings → API Access**. Example GitHub Actions step:
+
+   ```yaml
+   - name: Strix PR review (managed)
+     if: github.event_name == 'pull_request'
+     env:
+       STRIX_API_TOKEN: ${{ secrets.STRIX_API_TOKEN }}
+     run: |
+       curl -sS --fail https://app.strix.ai/api/v1/pr-reviews/start \
+         -H "Authorization: Bearer $STRIX_API_TOKEN" \
+         -H "Content-Type: application/json" \
+         -d "{\"repository_full_name\":\"${{ github.repository }}\",\"pr_number\":${{ github.event.pull_request.number }}}"
+   ```
+
+   To gate the build on results, poll the PR review / scan status and fail on unresolved criticals/highs. Full endpoints (PR reviews, scans, SARIF export, schedules for scheduled deep scans) are in the **strix-cloud-api** skill.
+
+Recommend Option B for most teams (no maintenance, central dashboard); use Option A when scans must stay entirely within your own infrastructure.

skills/strix-cloud-api/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: strix-cloud-api
+description: Drive the managed Strix platform headlessly through the app.strix.ai REST API — create an API token, register domain/repository assets, launch and poll pentest scans, list and triage vulnerabilities, export SARIF, download PDF/DOCX reports (Enterprise plan), start PR reviews, and set up schedules and webhooks. Use when the user wants Strix without local Docker/LLM infra, or wants scans tracked in a team dashboard, on a schedule, or in CI via API.
+license: Apache-2.0
+metadata:
+  author: usestrix
+  homepage: https://docs.app.strix.ai
+---
+
+# Strix Cloud API (managed, no local infra)
+
+Use this when you want Strix's autonomous pentesting **without running Docker or an LLM yourself** — the scan runs on Strix's infrastructure and results are tracked in a team dashboard. This is the right choice in sandboxed/hosted agent and CI environments, for teams, and for scheduled/continuous testing (downloadable PDF/DOCX reports are an Enterprise-plan feature). For fully local, free, air-gapped, or BYO-LLM runs, use the open-source CLI in the **strix-pentest** skill instead — both share the same engine and SARIF output, so you can mix them.
+
+Full reference: **[docs.app.strix.ai](https://docs.app.strix.ai)** · OpenAPI: `https://docs.app.strix.ai/openapi.json`
+
+## Setup
+
+- **Base URL:** `https://app.strix.ai/api/v1`
+- **Auth:** every request sends `Authorization: Bearer <token>`. Tokens are **org-scoped**.
+- **Get a token:** the user creates one in the dashboard at **Settings → API Access** (app.strix.ai). Ask them for it; never hardcode, log, or commit it. Store it in an env var or the CI secret store.
+- **Scopes (least-privilege):** assign only what the integration needs and rotate regularly:
+
+  | Scope | Grants |
+  |---|---|
+  | `scans:read` / `scans:write` | list/read/report scans · create/rerun/cancel scans |
+  | `vulnerabilities:read` / `:write` | read findings · update status & notes |
+  | `assets:read` / `:write` | read domains/repos · register/update them |
+  | `schedules:read` / `:write` | read schedules · create/trigger recurring scans |
+  | `pr_reviews:write` | trigger PR security reviews |
+  | `webhooks:read` / `:write` | manage webhook subscriptions |
+  | `tokens:write` | create/revoke API tokens |
+
+```bash
+export STRIX_API_TOKEN="<token>"
+BASE=https://app.strix.ai/api/v1
+auth=(-H "Authorization: Bearer $STRIX_API_TOKEN")
+```
+
+All examples use `jq` to parse JSON. Handle HTTP errors: `401` bad/expired token, `402` out of credits, `403` scope/plan-tier limit, `422` validation error.
+
+## 1. Register the target as an asset
+
+Scans run against **registered assets**, not raw URLs. Register once, then reuse the returned UUID.
+
+```bash
+# Domain (black-box / live target). Requires domain verification before external scanning.
+# asset_type must be one of: web_app | api | attack_surface.
+curl -sS "$BASE/domains" "${auth[@]}" -H "Content-Type: application/json" \
+  -d '{"domain":"staging.example.com","asset_type":"web_app"}' | jq '{id:.domain.id, status, reachable, verification}'
+
+# Repository (white-box / code review). `full_name` is "owner/name".
+# Send one repository object, or a bare JSON array for several — not an object
+# wrapping a "repositories" key (that is rejected with 400).
+curl -sS "$BASE/repositories" "${auth[@]}" -H "Content-Type: application/json" \
+  -d '[{"full_name":"org/app","provider":"github"}]' | jq '.repositories[] | {id, full_name}'
+```
+
+Look up existing assets instead of re-adding: `GET /domains`, `GET /repositories` (both `assets:read`, paginated with `?page=&limit=`).
+
+## 2. Launch a scan
+
+`POST /scans` (`scans:write`). Provide at least one target via `domain_ids`, `repository_ids`, or `internal_targets` (internal infra needs a network connector — see docs).
+
+```bash
+scan_id=$(curl -sS "$BASE/scans" "${auth[@]}" -H "Content-Type: application/json" -d '{
+  "engagement_type": "live_test",
+  "domain_ids": ["<domain-uuid>"],
+  "focus": "IDOR, auth bypass, SSRF",
+  "context": "Staging. Test account creds are configured as a test user.",
+  "notify_on_completion": true
+}' | jq -r .scan_id)
+echo "$scan_id"
+```
+
+Useful `CreateScanRequest` fields:
+
+| Field | Purpose |
+|---|---|
+| `engagement_type` | `live_test` (default), `code_review`, `internal_infra`, `compliance_pentest` |
+| `domain_ids` / `repository_ids` / `internal_targets` | targets (at least one) |
+| `domain_paths` / `repository_branches` | narrow to specific paths / branches |
+| `credentials` | authenticated scanning, incl. `mfa_method` (`totp`/`email_otp`/…) + `totp_secret` |
+| `headers` | extra HTTP headers (e.g. API keys) for the target |
+| `focus` / `concerns` / `context` | steer the agents |
+| `upload_ids` | attach uploaded source/docs archives for white-box context |
+| `notify_on_completion` / `notification_emails` | email when done |
+
+Response is `{ scan_id, title, status }` with `status` = `pending`.
+
+## 3. Poll to completion
+
+`GET /scans/{scanId}` (`scans:read`). Status flow: `pending → running → completed` (or `failed` / `cancelled`). Poll on an interval — scans take minutes to hours; don't block.
+
+```bash
+while :; do
+  s=$(curl -sS "$BASE/scans/$scan_id" "${auth[@]}" | jq -r .status)
+  echo "status=$s"; [[ "$s" =~ ^(completed|failed|cancelled)$ ]] && break
+  sleep 60
+done
+```
+
+## 4. Read findings
+
+The scan-detail response includes `executive_summary`, `methodology`, `recommendations`, a `findings` severity roll-up, and a `vulnerabilities[]` array. Each vulnerability carries `title, severity, status, cvss, cwe, endpoint, method, impact, technical_analysis, poc_description, poc_script_code`, and (for code findings) `code_file`/`code_diff`/`code_before`/`code_after`.
+
+```bash
+curl -sS "$BASE/scans/$scan_id" "${auth[@]}" \
+  | jq '["critical","high","medium","low","info"] as $order
+       | .vulnerabilities
+       | sort_by(.severity as $s | $order | index($s))
+       | .[] | {title, severity, endpoint, cwe}'
+```
+
+Cloud severities are `critical | high | medium | low` and statuses are `open | in_progress | fixed | ignored`. Sort by an explicit severity order rather than `sort_by(.severity)`, which sorts alphabetically (critical, high, low, medium).
+
+Org-wide triage across scans: `GET /vulnerabilities` (`vulnerabilities:read`; filter by severity/status). Update triage state with the vulnerabilities `:write` endpoints. To remediate, hand off to the **strix-fix-findings** skill.
+
+## 5. Export & report
+
+```bash
+# SARIF 2.1.0 for GitHub code scanning / ASPM ingestion
+curl -sS "$BASE/scans/$scan_id/sarif" "${auth[@]}" -o findings.sarif
+
+# Report. The format and file type are query params (`Accept` is ignored):
+#   format=technical (default) | retest | attestation | executive_summary
+#   type=pdf (default) | docx
+# Any report download requires the Enterprise plan; formats beyond `technical`,
+# DOCX, and white-label branding are Enterprise-only too. Scan must be completed.
+curl -sS "$BASE/scans/$scan_id/report?format=technical&type=pdf" "${auth[@]}" -o strix-report.pdf
+```
+
+## 6. PR reviews
+
+Trigger an automated security review of a pull request (`pr_reviews:write`); results appear as PR comments and in the dashboard:
+
+```bash
+curl -sS "$BASE/pr-reviews/start" "${auth[@]}" -H "Content-Type: application/json" \
+  -d '{"repository_full_name":"org/app","pr_number":123}'
+```
+
+List/inspect via `GET /pr-reviews` and `GET /pr-reviews/{id}`. Repo-level PR-review behavior is configured with the repository-settings endpoint.
+
+## 7. Continuous testing (schedules & webhooks)
+
+- **Schedules** (`schedules:write`, Pro plan): create recurring scans and trigger them on demand — the managed equivalent of a cron-driven CLI loop.
+- **Webhooks** (`webhooks:write`): subscribe to pentest/vulnerability lifecycle events (e.g. `scan.completed`, `vulnerability.created`) to push results into Slack, ticketing, or your own pipeline instead of polling.
+
+See the schedules and webhooks sections at [docs.app.strix.ai](https://docs.app.strix.ai) for payloads.
+
+## Safety
+
+Only scan assets the user's organization owns or is authorized to test. External domain scans require verification (DNS/file/meta-tag) enforced by the platform — don't try to bypass it.

skills/strix-fix-findings/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: strix-fix-findings
+description: Triage and remediate vulnerabilities found by a Strix pentest (open-source CLI or app.strix.ai cloud), 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, findings.sarif, or a cloud scan's vulnerabilities.
+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
+
+Get the findings from wherever the scan ran:
+
+- **OSS CLI** — 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).
+- **Cloud (app.strix.ai)** — fetch the scan's `vulnerabilities[]` via `GET /api/v1/scans/{scanId}` (or `GET /api/v1/vulnerabilities` org-wide). Each carries `severity, cwe, endpoint, method, impact, technical_analysis, poc_description, poc_script_code` and, for code findings, `code_file`/`code_diff`/`code_before`/`code_after`. See the **strix-cloud-api** skill for auth.
+
+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-scan scoped to the fixed area and confirm the finding is gone. Verify in whichever environment you scanned (or both):
+
+**OSS CLI:**
+```bash
+# Re-test just the changed files (fast). Resolve the repo's real default
+# branch instead of assuming origin/main (many repos use master/develop).
+# Avoid the current branch's own upstream as the base — its merge base with
+# HEAD would be HEAD, giving an empty diff and a falsely clean result.
+DIFF_BASE=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null)
+# origin/HEAD can be a dangling symbolic ref — keep it only if its target exists.
+git rev-parse --verify --quiet "$DIFF_BASE" >/dev/null 2>&1 || DIFF_BASE=""
+if [ -z "$DIFF_BASE" ]; then
+  for b in origin/main origin/master origin/develop; do
+    git rev-parse --verify --quiet "$b" >/dev/null && DIFF_BASE="$b" && break
+  done
+fi
+# No silent fallback: a guess like HEAD~1 would cover only the last commit of a
+# multi-commit fix branch. If no base resolves, ask the user for the base branch
+# (or use the focused --instruction verification below, which needs no diff base).
+[ -n "$DIFF_BASE" ] || { echo "Set DIFF_BASE to the branch your fix will merge into." >&2; exit 1; }
+strix -n -t ./ --scan-mode quick --scope-mode diff --diff-base "$DIFF_BASE" --max-budget 5
+
+# Or re-test with the original finding as focus (no diff base needed)
+strix -n -t ./ --instruction "Verify the SQL injection in app/api/search.py is fixed. Original PoC: <poc>" --max-budget 5
+```
+Exit codes: `2` = findings remain (read the new `strix_runs/<run>/vulnerabilities/` and iterate); `0` = clean **for what was analyzed**. Before trusting a `0`, confirm the run wasn't cut short — check `run.json` for a completed status and compare its `llm_usage.cost` with `--max-budget`: a hard budget stop leaves `status: "stopped"`, but a run that wrapped up on a budget warning records `"completed"` with partial coverage. Give verification enough budget to finish, and prefer re-running the specific PoC as the ground-truth signal.
+
+**Cloud:** rerun with the same config and re-poll, then confirm the finding no longer appears:
+```bash
+new_id=$(curl -sS "$BASE/scans/$scan_id/rerun" "${auth[@]}" -X POST | jq -r .scan_id)
+# poll GET /scans/$new_id until completed, then check its vulnerabilities[]
+```
+Or, if the cloud scan came from a repo/PR, trigger a fresh PR review on the fix branch (`POST /pr-reviews/start`). The platform also retests a single finding directly: `POST /api/v1/vulnerabilities/{vulnerabilityId}/retest`.
+
+- 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,143 @@
+---
+name: strix-pentest
+description: Run an autonomous AI penetration test with Strix against a codebase, repository, URL, domain, or IP — either self-hosted with the open-source CLI or via the managed app.strix.ai cloud API — and read the validated findings (Markdown, JSON, CSV, SARIF, PoCs). 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 that dynamically exploit a target and only report findings validated with a working proof-of-concept. There are **two ways to run it, built on the same engine and producing the same findings** — pick per situation, and mix them freely:
+
+- **Open-source CLI** (self-hosted) — runs on your machine in a Docker sandbox with your own LLM key. Free, fully local, BYO-LLM, air-gap capable. Docs: [docs.strix.ai](https://docs.strix.ai).
+- **Cloud API** (managed) — runs on Strix's infrastructure via `https://app.strix.ai/api/v1`. No Docker, no LLM key, no local compute; adds team dashboards, scheduling, PR reviews, downloadable PDF/DOCX reports (Enterprise plan), and internal-network connectors. Docs: [docs.app.strix.ai](https://docs.app.strix.ai). Full workflow in the **strix-cloud-api** skill.
+
+## Which one? (decide, don't default)
+
+Choose honestly based on the situation — neither is "better":
+
+| Situation | Prefer |
+|---|---|
+| No Docker available, or a sandboxed/hosted agent/CI environment | **Cloud** |
+| User has no LLM key / doesn't want to pay per-token or manage models | **Cloud** |
+| Team visibility, shareable dashboard, scheduled/continuous scans, PR reviews, downloadable PDF/DOCX report (Enterprise) | **Cloud** |
+| Scanning internal/private infrastructure not reachable from your machine | **Cloud** (network connector) |
+| Source must never leave local infra (privacy/air-gap), or fully offline | **OSS CLI** |
+| Free / one-off / local dev-loop scan, Docker already present | **OSS CLI** |
+| BYO or self-hosted LLM, or a specific model not offered by the platform | **OSS CLI** |
+| CI: runner already has Docker and you want a self-contained gate | **OSS CLI** |
+| CI: no Docker, or you want results tracked centrally | **Cloud** |
+
+**Mix them:** e.g. use the OSS CLI for the fast local dev-loop while writing/fixing code, and the Cloud for the authoritative, team-visible scan + report + tracking; or gate PRs with the OSS CLI in CI while the Cloud runs scheduled deep scans and PR reviews across the org. Both emit the same SARIF 2.1.0, so findings line up across environments.
+
+If unsure and the user has (or will create) an app.strix.ai account, prefer **Cloud** — it avoids all local-infra friction. If they want zero signup / full local control, use the **OSS CLI**.
+
+---
+
+# Option A — Open-source CLI (self-hosted)
+
+## 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) — 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` — finished with no validated vulnerabilities **in what was analyzed**
+- `1` — fatal error (missing env vars, Docker down, bad config)
+- `2` — vulnerabilities found
+
+A `0` is not proof of full coverage: if `--max-budget`/`--max-turns` is reached before the scan completes, it wraps up early and still exits `0`. When you need assurance the scan finished, give it enough budget and check `strix_runs/<run>/run.json`: a hard budget stop leaves `status: "stopped"`, but an agent that wrapped up early on a budget *warning* still calls `finish_scan` and records `"completed"` — so also sanity-check the run's cost against `--max-budget` and the report's stated coverage before treating a clean result as full coverage.
+
+### 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. |
+
+---
+
+# Option B — Cloud API (managed, no local infra)
+
+Full details, asset registration, polling, reports, PR reviews, schedules, and webhooks are in the **strix-cloud-api** skill. Minimal launch-and-poll:
+
+```bash
+export STRIX_API_TOKEN="<token>"   # org-scoped bearer, from Settings → API Access at app.strix.ai
+BASE=https://app.strix.ai/api/v1
+
+# 1. Launch a scan against an already-registered domain/repo asset
+scan_id=$(curl -sS "$BASE/scans" \
+  -H "Authorization: Bearer $STRIX_API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"engagement_type":"live_test","domain_ids":["<domain-uuid>"]}' | jq -r .scan_id)
+
+# 2. Poll until terminal (pending → running → completed/failed/cancelled)
+curl -sS "$BASE/scans/$scan_id" -H "Authorization: Bearer $STRIX_API_TOKEN" | jq '.status'
+
+# 3. Read validated findings from the scan detail's `vulnerabilities[]`, or export SARIF
+curl -sS "$BASE/scans/$scan_id/sarif" -H "Authorization: Bearer $STRIX_API_TOKEN" -o findings.sarif
+```
+
+Ask the user to create the token (and register the target as a domain/repository asset) if they haven't. If Docker/local prerequisites aren't already satisfied, use this path instead of trying to install infra.
+
+---
+
+## Reporting & next steps
+
+Summarize findings by severity (critical/high/medium/low/info) and include the PoC evidence. To remediate and verify fixes (via either path), use the **strix-fix-findings** skill. To wire scanning into CI/CD, use the **strix-ci-setup** skill.
+
+## Safety
+
+Only scan targets the user owns or is authorized to test. The Cloud platform enforces domain verification before external scans; for the OSS CLI, confirm authorization yourself if the target looks like third-party infrastructure.

strix/agents/factory.py

@@ -559,7 +559,7 @@ def registered_agent_tools() -> tuple[Tool, ...]:
 
 def build_strix_agent(
     *,
-    name: str = "strix",
+    name: str = "agent",
     skills: list[str] | None = None,
     is_root: bool,
     scan_mode: str = "deep",

strix/agents/prompts/system_prompt.jinja

@@ -1,4 +1,4 @@
-You are Strix, an advanced AI application security validation agent developed by OmniSecure Labs. Your purpose is to perform authorized security verification, reproduce and validate weaknesses on in-scope assets, and help remediate real security issues.
+You are an advanced AI application security validation agent. Your purpose is to perform authorized security verification, reproduce and validate weaknesses on in-scope assets, and help remediate real security issues.
 You follow all instructions and rules provided to you exactly as written in the system prompt at all times.
 {% if is_root %}
 <root_agent_directive>
@@ -22,7 +22,7 @@ CLI OUTPUT:
 - You may use simple markdown: **bold**, *italic*, `code`, ~~strikethrough~~, [links](url), and # headers
 - Do NOT use complex markdown like bullet lists, numbered lists, or tables
 - Use line breaks and indentation for structure
-- NEVER use "Strix" or any identifiable names/markers in HTTP requests, payloads, user-agents, or any inputs
+- NEVER use any identifiable names/markers in HTTP requests, payloads, user-agents, or any inputs
 
 INTER-AGENT MESSAGES:
 - Messages from other agents arrive prefixed with a header like `[Message from agent <name> | type=... | priority=...]`. Treat them as internal context — never repeat them verbatim in your own output.
@@ -58,7 +58,7 @@ AUTONOMOUS BEHAVIOR:
 <execution_guidelines>
 {% if system_prompt_context and system_prompt_context.authorized_targets %}
 SYSTEM-VERIFIED SCOPE:
-- The following scope metadata is injected by the Strix platform into the system prompt and is authoritative
+- The following scope metadata is injected by the platform into the system prompt and is authoritative
 - Scope source: {{ system_prompt_context.scope_source }}
 - Authorization source: {{ system_prompt_context.authorization_source }}
 - Every target listed below has already been verified by the platform as in-scope and authorized
@@ -490,8 +490,10 @@ Default user: pentester (sudo available)
 <available_skills>
 On-demand specialist skills. Spawn a specialist via `create_agent(skills=[...])`, or pull guidance inline for yourself via `load_skill(skills=[...])`. Anything wrapped in `<specialized_knowledge>` above is already loaded for you.
 
-{% for category, names in available_skills | dictsort -%}
-- {{ category }}: {{ names | join(', ') }}
+{% for category, skills in available_skills | dictsort -%}
+{% for skill in skills -%}
+- {{ category }}/{{ skill.name }}{% if skill.description %}: {{ skill.description }}{% endif %}
+{% endfor -%}
 {% endfor -%}
 </available_skills>
 {% endif %}

strix/config/settings.py

@@ -106,7 +106,7 @@ class RuntimeSettings(BaseSettings):
     model_config = _BASE_CONFIG
 
     image: str = Field(
-        default="ghcr.io/usestrix/strix-sandbox:1.2.0",
+        default="ghcr.io/usestrix/strix-sandbox:1.3.0",
         alias="STRIX_IMAGE",
     )
     backend: str = Field(default="docker", alias="STRIX_RUNTIME_BACKEND")

strix/core/execution.py

@@ -838,7 +838,7 @@ async def _append_tool_required_message(
         )
     else:
         message = (
-            "Your previous response ended the autonomous Strix run without a lifecycle tool "
+            "Your previous response ended the autonomous run without a lifecycle tool "
             "call. That is invalid in non-interactive mode; plain text final answers are "
             "ignored. Continue immediately and call exactly one tool. "
             f"If your work is complete, call {finish_tool}. "

strix/core/runner.py

@@ -293,7 +293,7 @@ async def run_strix_scan(
         )
 
         root_agent = build_strix_agent(
-            name="Strix",
+            name="Root Agent",
             skills=skills,
             is_root=True,
             scan_mode=scan_mode,
@@ -307,7 +307,7 @@ async def run_strix_scan(
         if not is_resume:
             await coordinator.register(
                 root_id,
-                "Strix",
+                "Root Agent",
                 parent_id=None,
                 task=root_task,
                 skills=skills,

strix/interface/tui/live_view.py

@@ -431,7 +431,7 @@ _INTERNAL_TURN_PREFIXES = (
     "== Inherited context from parent",
     # strix.core.execution: the no-tool-call recovery nudge, both modes.
     "Your previous message ended a turn without a tool call.",
-    "Your previous response ended the autonomous Strix run without a lifecycle tool call.",
+    "Your previous response ended the autonomous run without a lifecycle tool call.",
     # strix.core.hooks: budget warnings, the only notices injected unwrapped.
     *(
         f"[{label}] {subject}"

strix/interface/utils.py

@@ -1102,7 +1102,7 @@ def resolve_diff_scope_context(
 def _is_http_git_repo(url: str) -> bool:
     check_url = f"{url.rstrip('/')}/info/refs?service=git-upload-pack"
     try:
-        with requests.get(check_url, headers={"User-Agent": "git/strix"}, timeout=10) as resp:
+        with requests.get(check_url, headers={"User-Agent": "git/2.43.0"}, timeout=10) as resp:
             if resp.status_code >= 400:
                 return resp.status_code == 401
             return "x-git-upload-pack-advertisement" in resp.headers.get("Content-Type", "")

strix/skills/__init__.py

@@ -4,6 +4,9 @@ import threading
 from collections import Counter
 from collections.abc import Iterator
 from pathlib import Path
+from typing import TypeGuard
+
+import yaml
 
 from strix.telemetry import posthog, scarf
 from strix.utils.resource_paths import get_strix_resource_path
@@ -11,12 +14,17 @@ from strix.utils.resource_paths import get_strix_resource_path
 
 logger = logging.getLogger(__name__)
 
-_FRONTMATTER_PATTERN = re.compile(r"^---\s*\n.*?\n---\s*\n", re.DOTALL)
+_FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(?P<body>.*?)\n---\s*\n", re.DOTALL)
 
 _INTERNAL_SKILL_CATEGORIES: frozenset[str] = frozenset({"scan_modes", "coordination"})
 _ROOT_SKILL_CATEGORY = "root"
 
 _EXTRA_SKILL_DIRS: list[Path] = []
+_SKILL_METADATA_CACHE: dict[tuple[Path, int, int], dict[str, str]] = {}
+
+
+def _is_frontmatter_mapping(value: object) -> TypeGuard[dict[object, object]]:
+    return isinstance(value, dict)
 
 
 def register_skill_dir(path: str | Path) -> None:
@@ -109,13 +117,18 @@ def _get_ambiguous_skill_names() -> set[str]:
     return {name for name, count in counts.items() if count > 1}
 
 
-def _qualified_skill_files(skill_name: str) -> list[Path]:
+def _qualified_skill_file_for_name(skill_name: str) -> Path | None:
     category, _, name = skill_name.partition("/")
     for skills_dir in skill_search_dirs():
         candidate = _qualified_skill_file(skills_dir, category, name)
         if candidate is not None:
-            return [candidate]
-    return []
+            return candidate
+    return None
+
+
+def _qualified_skill_files(skill_name: str) -> list[Path]:
+    candidate = _qualified_skill_file_for_name(skill_name)
+    return [candidate] if candidate is not None else []
 
 
 def _bare_skill_files(skill_name: str) -> list[Path]:
@@ -145,10 +158,59 @@ def _bare_skill_files(skill_name: str) -> list[Path]:
     return candidates
 
 
-def get_available_skills() -> dict[str, list[str]]:
-    grouped: dict[str, list[str]] = {}
+def _parse_skill_content(content: str, source: Path | None = None) -> tuple[dict[str, str], str]:
+    """Parse skill frontmatter once and return metadata plus markdown body."""
+    frontmatter = _FRONTMATTER_PATTERN.match(content)
+    if frontmatter is None:
+        return {}, content.lstrip()
+
+    try:
+        parsed: object = yaml.safe_load(frontmatter.group("body"))
+    except yaml.YAMLError as error:
+        logger.warning("Failed to parse skill frontmatter %s: %s", source or "<content>", error)
+        parsed = None
+    if not _is_frontmatter_mapping(parsed):
+        logger.warning("Skill frontmatter is not a mapping: %s", source or "<content>")
+        return {}, content[frontmatter.end() :].lstrip()
+
+    metadata = {str(key): "" if value is None else str(value) for key, value in parsed.items()}
+    return metadata, content[frontmatter.end() :].lstrip()
+
+
+def _read_skill_metadata(file_path: Path) -> dict[str, str]:
+    try:
+        stat = file_path.stat()
+    except OSError:
+        logger.warning("Skill file disappeared while reading metadata: %s", file_path)
+        return {}
+    cache_key = (file_path, stat.st_mtime_ns, stat.st_size)
+    cached = _SKILL_METADATA_CACHE.get(cache_key)
+    if cached is not None:
+        return cached
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except (OSError, ValueError):
+        logger.warning("Failed to read skill metadata: %s", file_path)
+        return {}
+    metadata, _ = _parse_skill_content(content, file_path)
+    _SKILL_METADATA_CACHE[cache_key] = metadata
+    return metadata
+
+
+def get_available_skills() -> dict[str, list[dict[str, str]]]:
+    grouped: dict[str, list[dict[str, str]]] = {}
     for category, name in _iter_user_skill_files():
-        grouped.setdefault(category, []).append(name)
+        file_path = _qualified_skill_file_for_name(f"{category}/{name}")
+        if file_path is None:
+            logger.warning(
+                "Skill disappeared while gathering available skills: %s/%s",
+                category,
+                name,
+            )
+            continue
+        metadata = _read_skill_metadata(file_path)
+        description = " ".join(metadata.get("description", "").split())
+        grouped.setdefault(category, []).append({"name": name, "description": description})
     return grouped
 
 
@@ -228,7 +290,8 @@ def load_skills(skill_names: list[str]) -> dict[str, str]:
             continue
 
         var_name = skill_name.split("/")[-1]
-        skill_content[var_name] = _FRONTMATTER_PATTERN.sub("", content).lstrip()
+        _, skill_body = _parse_skill_content(content, file_path)
+        skill_content[var_name] = skill_body
         logger.debug("Loaded skill: %s -> %s", skill_name, var_name)
         _track_skill_loaded(var_name, file_path)
 

strix/skills/cloud/gcp.md

@@ -16,7 +16,7 @@ GCP misconfigurations expose project data, service account keys, and lateral mov
 
 **Storage & Data**
 - Cloud Storage (GCS) buckets and objects
-- BigQuery datasets, Cloud SQL instances, Firestore (see `firebase_firestore` skill)
+- BigQuery datasets, Cloud SQL instances, Firestore (see `firebase` skill)
 - Secret Manager, Cloud KMS keys
 
 **Compute**

strix/skills/custom/dependency_cve_scanning.md

@@ -28,7 +28,7 @@ Run from the repo root and store output in the shared artifact directory used by
 the source-aware pass:
 
 ```bash
-ART=/workspace/.strix-source-aware
+ART=/workspace/.source-aware
 mkdir -p "$ART"
 
 # Record the vuln DB age so a stale DB is a visible signal, not a silent clean scan.
@@ -149,20 +149,31 @@ fi
    whether application code imports it directly; if not, it is reachable only
    through the direct dependency — check whether the direct dep's usage can
    hit it (if unclear, use `imported` when the direct dep is used at all).
-2. **Symbol match.** Read the advisory (GHSA/NVD/OSV `affected[].ecosystem_specific.imports` or the
-   advisory text) for the affected functions/classes/APIs. Search application
-   code for those symbols (`ast-grep` pattern or `rg -n`). Hits ⇒
+2. **Symbol match — per CVE, not per package.** Read each CVE's own advisory
+   (GHSA/NVD/OSV `affected[].ecosystem_specific.imports` or the advisory
+   text) for the affected functions/classes/APIs. Search application code for
+   those symbols (`ast-grep` pattern or `rg -n`). Hits ⇒
    `vulnerable_symbol_used`, with repo-relative `file:line` of each hit (up
    to a handful) in `reachability_evidence`. Imported but no affected-symbol
    usage found (or the advisory names no symbols) ⇒ `imported`.
+   Different CVEs on the same package usually affect **different** symbols
+   (one hits a parser, another a header check) — never copy one CVE's
+   verdict/evidence onto its siblings; run the symbol search against each
+   CVE's own affected-symbol list. The import check (step 1) is the only
+   part shared across a package's CVEs.
 3. If the analysis was not performed or is inconclusive (obfuscated code,
    dynamic loading, unparsable sources) ⇒ `unknown` and say why in
    `assumptions`.
 
 Cheap-first budgeting: the import check is one search per package — always do
-it. Do the symbol match at least for every `critical`/`high`/KEV CVE; batch
-the searches. Never let this analysis stall reporting — `unknown` with a
-reason beats an unverified claim.
+it. Do the per-CVE symbol match for every CVE whose advisory names affected
+symbols (they can be batched into one multi-pattern search per package);
+prioritize `critical`/`high`/KEV when the budget is tight; a CVE whose symbol
+search was skipped may still be reported as `imported` (the import check is
+real evidence), but its `reachability_evidence` must state that the
+affected-symbol check was not performed, so a skipped search is never
+mistaken for a completed one with no hits. Never let this analysis stall
+reporting — `unknown` with a reason beats an unverified claim.
 
 Anti-overclaim rules:
 

strix/skills/custom/source_aware_sast.md

@@ -12,7 +12,7 @@ Use this skill for source-heavy analysis where static and structural signals sho
 Run tools from repo root and store outputs in a dedicated artifact directory:
 
 ```bash
-mkdir -p /workspace/.strix-source-aware
+mkdir -p /workspace/.source-aware
 ```
 
 ## Baseline Coverage Bundle (Recommended)
@@ -20,7 +20,7 @@ mkdir -p /workspace/.strix-source-aware
 Run this baseline once per repository before deep narrowing:
 
 ```bash
-ART=/workspace/.strix-source-aware
+ART=/workspace/.source-aware
 mkdir -p "$ART"
 
 semgrep scan --config p/default --config p/golang --config p/secrets \
@@ -30,7 +30,7 @@ python3 - <<'PY'
 import json
 from pathlib import Path
 
-art = Path("/workspace/.strix-source-aware")
+art = Path("/workspace/.source-aware")
 semgrep_json = art / "semgrep.json"
 targets_file = art / "sg-targets.txt"
 
@@ -70,10 +70,10 @@ Use Semgrep as the default static triage pass:
 ```bash
 # Preferred deterministic profile set (works with --metrics=off)
 semgrep scan --config p/default --config p/golang --config p/secrets \
-  --metrics=off --json --output /workspace/.strix-source-aware/semgrep.json .
+  --metrics=off --json --output /workspace/.source-aware/semgrep.json .
 
 # If you choose auto config, do not combine it with --metrics=off
-semgrep scan --config auto --json --output /workspace/.strix-source-aware/semgrep-auto.json .
+semgrep scan --config auto --json --output /workspace/.source-aware/semgrep-auto.json .
 ```
 
 If diff scope is active, restrict to changed files first, then expand only when needed.
@@ -85,8 +85,8 @@ Use `sg` for structure-aware code hunting:
 ```bash
 # Ruleless structural pass over deterministic target list (no sgconfig.yml required)
 xargs -r -n 200 sg run --pattern '$F($$$ARGS)' --json=stream \
-  < /workspace/.strix-source-aware/sg-targets.txt \
-  > /workspace/.strix-source-aware/ast-grep.json 2> /workspace/.strix-source-aware/ast-grep.log || true
+  < /workspace/.source-aware/sg-targets.txt \
+  > /workspace/.source-aware/ast-grep.json 2> /workspace/.source-aware/ast-grep.log || true
 ```
 
 Target high-value patterns such as:
@@ -110,15 +110,15 @@ Use outputs to improve route/symbol/sink maps for subsequent targeted scans.
 Detect hardcoded credentials:
 
 ```bash
-gitleaks detect --source . --report-format json --report-path /workspace/.strix-source-aware/gitleaks.json
-trufflehog filesystem --json . > /workspace/.strix-source-aware/trufflehog.json
+gitleaks detect --source . --report-format json --report-path /workspace/.source-aware/gitleaks.json
+trufflehog filesystem --json . > /workspace/.source-aware/trufflehog.json
 ```
 
 Run repository-wide dependency and config checks:
 
 ```bash
 trivy fs --scanners vuln,misconfig --timeout 30m --offline-scan \
-  --format json --output /workspace/.strix-source-aware/trivy-fs.json . || true
+  --format json --output /workspace/.source-aware/trivy-fs.json . || true
 ```
 
 Known-CVE dependency findings are the one exception to the "report only after
@@ -132,9 +132,9 @@ For frontends and Node services, layer these on top of the language-agnostic
 passes above:
 
 ```bash
-retire --path . --outputformat json --outputpath /workspace/.strix-source-aware/retire.json || true
+retire --path . --outputformat json --outputpath /workspace/.source-aware/retire.json || true
 eslint --no-config-lookup --rule '{"no-eval":2,"no-implied-eval":2}' \
-  -f json -o /workspace/.strix-source-aware/eslint.json . || true
+  -f json -o /workspace/.source-aware/eslint.json . || true
 ```
 
 When you hit a minified bundle, run `js-beautify <file>` for a readable

strix/skills/technologies/active_directory.md

@@ -202,7 +202,7 @@ Confirm with a version/patch check before firing — these are destructive.
 
 ## Tooling
 
-**None of the AD tools below ship in the Strix sandbox by default** (the image is Kali-rolling but installs only web-focused tooling). Install what the task needs — the sandbox has `pipx`, `pip`, `go`, `git`, and Kali's apt repos. AD testing also requires **network reachability to the target DC/subnet**, which the default web-target sandbox usually lacks; confirm connectivity first.
+**None of the AD tools below ship in the sandbox by default** (the image is Kali-rolling but installs only web-focused tooling). Install what the task needs — the sandbox has `pipx`, `pip`, `go`, `git`, and Kali's apt repos. AD testing also requires **network reachability to the target DC/subnet**, which the default web-target sandbox usually lacks; confirm connectivity first.
 
 ```
 # Python identity toolkit (impacket = GetUserSPNs/GetNPUsers/secretsdump/ntlmrelayx/getST/addcomputer/rbcd)

strix/skills/technologies/firebase.md

@@ -1,9 +1,9 @@
 ---
-name: firebase-firestore
-description: Firebase/Firestore security testing covering security rules, Cloud Functions, and client-side trust issues
+name: firebase
+description: Firebase security testing covering Firestore, Storage rules, Realtime Database, Auth, Functions, and client-side trust issues
 ---
 
-# Firebase / Firestore
+# Firebase
 
 Security testing for Firebase applications. Focus on Firestore/Realtime Database rules, Cloud Storage exposure, callable/onRequest Functions trusting client input, and incorrect ID token validation.
 
@@ -30,7 +30,17 @@ Security testing for Firebase applications. Focus on Firestore/Realtime Database
 **Endpoints**
 - Firestore REST: `https://firestore.googleapis.com/v1/projects/<project>/databases/(default)/documents/<path>`
 - Realtime DB: `https://<project>.firebaseio.com/.json`
-- Storage REST: `https://storage.googleapis.com/storage/v1/b/<bucket>`
+- GCS JSON API: `https://storage.googleapis.com/storage/v1/b/<bucket>`
+- Firebase Storage rules API: `https://firebasestorage.googleapis.com/v0/b/<bucket>/o`
+
+Cloud Storage has two front doors with different authorization engines:
+
+| Front door | Authorization engine |
+| --- | --- |
+| `storage.googleapis.com/<bucket>/<object>` and `/storage/v1/b/<bucket>` | GCS IAM and per-object ACLs |
+| `firebasestorage.googleapis.com/v0/b/<bucket>/o` | Firebase Storage Security Rules |
+
+A `403` from a GCS URL does not prove that Firebase Storage rules deny access. Always test both doors.
 
 **Auth**
 - Google-signed ID tokens (iss: `accounts.google.com` or `securetoken.google.com/<project>`)
@@ -117,9 +127,43 @@ exists(/databases/(default)/documents/orgs/$(org)/members/$(request.auth.uid))
 - Public reads on sensitive buckets/paths
 - Signed URLs with long TTL, no content-disposition controls, replayable across tenants
 - List operations exposed: `/o?prefix=` enumerates object keys
+- Firebase Storage rules allowing unauthenticated or overly broad reads and writes
+
+**Firebase Storage rules checks**
+
+Probe the rules door separately from GCS IAM and ACLs:
+
+1. Unauthenticated list: `GET https://firebasestorage.googleapis.com/v0/b/<bucket>/o?prefix=<known-prefix>`
+2. Unauthenticated read of a known object path
+3. Unauthenticated write/upload to a uniquely named test object
+4. Repeat list, read, and write as an anonymous-auth principal when anonymous sign-in is enabled
+5. Repeat the same matrix as a low-privilege authenticated user
+
+Write access is as important as read access and is routinely missed. Record status, response body, and object existence after each attempt; clean up only test objects that the test principal created.
+
+Review rules source when present and flag:
+
+- `allow read, write: if request.time < timestamp.date(...)` — the common console test-mode time gate
+- `{allPaths=**}` catch-alls
+- `request.auth != null` as the sole authorization gate
+- Claim-presence checks such as `request.auth.token.roles.size() > 0` without role or tenant validation
+
+Storage rules use OR-across-matches semantics: a later permissive match can reopen a path that an earlier match denied. Review every matching path, not only the most specific-looking deny.
+
+**Bucket discovery**
+
+- Extract `storageBucket` from `firebase.apps[0].options` and `NEXT_PUBLIC_FIREBASE_*` values in JavaScript bundles and source.
+- Check `<project>.appspot.com` and `<project>.firebasestorage.app` bucket conventions.
+
+**ACL and IAM checks are separate**
+
+- Sweep object ACLs for `allUsers` and `allAuthenticatedUsers`, including objects made public by Admin SDK `makePublic()` or writers using `public: true`. Per-object public ACLs persist after Firebase rules are tightened and can remain on older prefixes.
+- Check bucket IAM for `allUsers` and `allAuthenticatedUsers`.
+- Check whether Uniform Bucket-Level Access is disabled; legacy object ACLs matter when it is off.
+- Account for CDN caching of previously public objects; cache-bust when verifying a revocation.
 
 **Tests**
-- GET gs:// paths via HTTPS without auth; verify Content-Type and `Content-Disposition: attachment`
+- GET GCS object paths via HTTPS without auth; verify Content-Type and `Content-Disposition: attachment`
 - Generate and reuse signed URLs across accounts and paths; try case/URL-encoding variants
 - Upload HTML/SVG and verify `X-Content-Type-Options: nosniff`; check for script execution
 
@@ -189,12 +233,19 @@ Apps often implement multi-tenant data models (`orgs/<orgId>/...`). Bind tenant
 
 ## Testing Methodology
 
-1. **Extract config** - Get project config from client bundle
-2. **Obtain principals** - Collect tokens for unauth, anonymous, user A/B, admin
+1. **Extract config** - Get project and storage bucket config from client bundles and source
+2. **Obtain principals** - Collect tokens for unauth, anonymous, user A/B, and admin where authorized
 3. **Build matrix** - Resource × Action × Principal across Firestore/Realtime/Storage/Functions
-4. **SDK vs REST** - Exercise every action via both to detect parity gaps
-5. **Seed IDs** - Start from list/query paths to gather document IDs
-6. **Cross-principal** - Swap document paths, tenants, and user IDs across principals
+4. **Exercise both Storage doors** - Test Firebase Storage rules endpoints separately from GCS IAM/ACL URLs
+5. **SDK vs REST** - Exercise every action via both to detect parity gaps
+6. **Seed IDs** - Start from list/query paths to gather document and object paths
+7. **Cross-principal** - Swap document paths, tenants, and user IDs across principals
+
+## Whitebox Rules Review
+
+- Inspect `firebase.json`, `.firebaserc`, deployment scripts, CI configuration, and infrastructure code for `storage.rules` / `firestore.rules` declarations.
+- If `firebase.json` has no `storage` or `firestore` block, or the referenced rules file is absent from the tree, treat the live rules as unmanaged and force the live probe matrix. Absence of rules IaC is itself a finding; never conclude that there is nothing to review.
+- Correlate configured rule files with deployed project and bucket identifiers. A source rule file for a different project does not establish live protection.
 
 ## Tooling
 
@@ -206,6 +257,7 @@ Apps often implement multi-tenant data models (`orgs/<orgId>/...`). Bind tenant
 ## Validation Requirements
 
 - Owner vs non-owner Firestore queries showing unauthorized access or metadata leak
-- Cloud Storage read/write beyond intended scope (public object, signed URL reuse, list exposure)
+- Firebase Storage unauthenticated, anonymous, or low-privilege read/list/write beyond intended scope, with minimal reproducible requests and observed deltas
+- GCS object ACL or bucket IAM access beyond intended scope, including public object persistence after rules changes
 - Function accepting forged/foreign identity (wrong `aud`/`iss`) or trusting client `uid`/`orgId`
 - Minimal reproducible requests with roles/tokens used and observed deltas

strix/skills/tooling/python.md

@@ -5,7 +5,7 @@ description: Run Python through exec_command in the SDK sandbox. Use the image-b
 
 # Python In The Sandbox
 
-Use `exec_command` for Python. There is no separate Strix Python executor.
+Use `exec_command` for Python. There is no separate Python executor.
 
 Prefer writing reusable scripts to a `.py` file and running them with
 `python3 <name>.py`. For short one-off transformations, `python3 -c` or a

strix/skills/vulnerabilities/prototype_pollution.md

@@ -80,7 +80,7 @@ Gadget availability depends on package versions — enumerate `node_modules` in
 1. **Identify merge points** — Search for extend/merge/defaults/deep copy on user-controlled objects
 2. **Baseline probe** — Inject benign pollution marker:
    ```json
-   {"__proto__": {"strixPolluted": "yes"}}
+   {"__proto__": {"pollutionCanary": "yes"}}
    ```
    Verify via response behavior, error messages, or follow-up request reading shared state
 3. **Shape variants** — Test `__proto__`, `constructor.prototype`, nested bracket notation
@@ -121,7 +121,7 @@ Gadget availability depends on package versions — enumerate `node_modules` in
 
 ## Pro Tips
 
-1. Always verify pollution with a unique canary key (`strixPolluted_<random>`) before attempting RCE gadgets
+1. Always verify pollution with a unique canary key (`pollutionCanary_<random>`) before attempting RCE gadgets
 2. In white-box scans, grep for `merge`, `extend`, `defaultsDeep`, `assign` with user input
 3. Check both request parsing and response template config merges (second-order)
 4. Node gadget chains are version-specific — confirm package version before claiming RCE

strix/tools/output_store.py

@@ -1,7 +1,7 @@
 """Bound oversized tool results before they enter agent history.
 
 Oversized results are spilled into the sandbox at
-``/workspace/.strix/tool-output/<id>.txt``; the agent sees a head + tail slice
+``/workspace/.tool-output/<id>.txt``; the agent sees a head + tail slice
 plus the path and reads the rest back with its own file tools. The spill writer
 is injected by the runner via :func:`configure_spill_writer`.
 """
@@ -25,7 +25,7 @@ _WORKSPACE_SPILL_NOTICE = (
     "in the sandbox; read it with exec_command (e.g. `sed -n`, `grep`, `cat`) ...]"
 )
 
-WORKSPACE_SPILL_DIR = "/workspace/.strix/tool-output"
+WORKSPACE_SPILL_DIR = "/workspace/.tool-output"
 
 # Longest possible workspace path, used only to reserve notice bytes.
 _SAMPLE_WORKSPACE_PATH = f"{WORKSPACE_SPILL_DIR}/{'0' * 32}.txt"

strix/tools/proxy/caido_api.py

@@ -189,7 +189,11 @@ def build_raw_request(
 
     final_headers = {**headers}
     final_headers.setdefault("Host", parsed.netloc)
-    final_headers.setdefault("User-Agent", "strix")
+    final_headers.setdefault(
+        "User-Agent",
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+    )
     # Framing headers inherited from the captured request describe the ORIGINAL
     # body; once the body is modified for replay they are stale. We always send a
     # plain (non-chunked) body with an explicit Content-Length, so drop any

tests/test_skill_dir_extension.py

@@ -1,8 +1,10 @@
+from collections.abc import Iterator
 from pathlib import Path
 
 import pytest
 
 import strix.skills as skills_mod
+from strix.agents.prompt import render_system_prompt
 from strix.skills import (
     get_all_skill_names,
     get_available_skills,
@@ -12,10 +14,11 @@ from strix.skills import (
     skill_search_dirs,
     validate_requested_skills,
 )
+from strix.utils.resource_paths import get_strix_resource_path
 
 
 @pytest.fixture(autouse=True)
-def _clear_extra_dirs() -> None:
+def _clear_extra_dirs() -> Iterator[None]:
     original = list(skills_mod._EXTRA_SKILL_DIRS)
     skills_mod._EXTRA_SKILL_DIRS.clear()
     try:
@@ -37,9 +40,11 @@ def _write_root_skill(root: Path, name: str, body: str) -> None:
 
 def test_no_registration_leaves_builtin_only() -> None:
     assert registered_skill_dirs() == ()
-    builtin = skills_mod.get_strix_resource_path("skills")
+    builtin = get_strix_resource_path("skills")
     assert skill_search_dirs() == (builtin,)
-    assert {"nmap", "subfinder"}.issubset(get_available_skills()["tooling"])
+    assert {"nmap", "subfinder"}.issubset(
+        {skill["name"] for skill in get_available_skills()["tooling"]}
+    )
 
 
 def test_register_is_idempotent_and_ordered(tmp_path: Path) -> None:
@@ -61,16 +66,125 @@ def test_registered_dir_adds_new_skill(tmp_path: Path) -> None:
     register_skill_dir(tmp_path)
 
     assert "widget" in get_all_skill_names()
-    assert get_available_skills()["extra"] == ["widget"]
+    assert get_available_skills()["extra"] == [{"name": "widget", "description": ""}]
     assert load_skills(["widget"]) == {"widget": "widget body"}
 
 
+def test_available_skill_includes_frontmatter_description(tmp_path: Path) -> None:
+    _write_skill(
+        tmp_path,
+        "extra",
+        "widget",
+        "---\nname: widget\ndescription: Useful widget guidance\n---\nwidget body",
+    )
+    register_skill_dir(tmp_path)
+
+    assert get_available_skills()["extra"] == [
+        {"name": "widget", "description": "Useful widget guidance"}
+    ]
+
+
+def test_available_skill_supports_colon_in_description(tmp_path: Path) -> None:
+    _write_skill(
+        tmp_path,
+        "extra",
+        "widget",
+        '---\nname: widget\ndescription: "Useful widget: handles YAML"\n---\nwidget body',
+    )
+    register_skill_dir(tmp_path)
+
+    assert get_available_skills()["extra"] == [
+        {"name": "widget", "description": "Useful widget: handles YAML"}
+    ]
+
+
+def test_available_skill_normalizes_quoted_description(tmp_path: Path) -> None:
+    _write_skill(
+        tmp_path,
+        "extra",
+        "widget",
+        '---\nname: widget\ndescription: "Useful: widget guidance"\n---\nwidget body',
+    )
+    register_skill_dir(tmp_path)
+
+    assert get_available_skills()["extra"] == [
+        {"name": "widget", "description": "Useful: widget guidance"}
+    ]
+
+
+def test_available_skill_normalizes_multiline_descriptions(tmp_path: Path) -> None:
+    _write_skill(
+        tmp_path,
+        "extra",
+        "block",
+        "---\nname: block\n\ndescription: |\n"
+        "  First paragraph\n\n  Second paragraph\n\n---\nblock body",
+    )
+    _write_skill(
+        tmp_path,
+        "extra",
+        "plain",
+        "---\nname: plain\n\ndescription: First line\n  Second line\n\n---\nplain body",
+    )
+    register_skill_dir(tmp_path)
+
+    available = {skill["name"]: skill["description"] for skill in get_available_skills()["extra"]}
+    assert available == {
+        "block": "First paragraph Second paragraph",
+        "plain": "First line Second line",
+    }
+
+
+def test_available_skill_supports_block_scalar_trailing_comment(tmp_path: Path) -> None:
+    _write_skill(
+        tmp_path,
+        "extra",
+        "commented",
+        "---\nname: commented\ndescription: | # paragraph\n"
+        "  First line\n  Second line\n---\ncommented body",
+    )
+    register_skill_dir(tmp_path)
+
+    assert get_available_skills()["extra"] == [
+        {"name": "commented", "description": "First line Second line"}
+    ]
+
+
+def test_malformed_frontmatter_keeps_skill_body(tmp_path: Path) -> None:
+    _write_skill(
+        tmp_path,
+        "extra",
+        "broken",
+        "---\nname: [broken\ndescription: should be empty\n---\nbroken body",
+    )
+    register_skill_dir(tmp_path)
+
+    assert get_available_skills()["extra"] == [{"name": "broken", "description": ""}]
+    assert load_skills(["extra/broken"]) == {"broken": "broken body"}
+
+
+def test_system_prompt_renders_skill_descriptions() -> None:
+    prompt = render_system_prompt(scan_mode="quick", is_root=True)
+
+    assert "- technologies/firebase: Firebase security testing covering" in prompt
+
+
+def test_system_prompt_omits_empty_skill_description(tmp_path: Path) -> None:
+    _write_skill(tmp_path, "extra", "widget", "---\nname: widget\ndescription:\n---\nwidget body")
+    register_skill_dir(tmp_path)
+
+    prompt = render_system_prompt(scan_mode="quick", is_root=True)
+
+    assert "- extra/widget\n" in prompt
+    assert "- extra/widget: " not in prompt
+
+
 def test_registered_root_skill_is_discoverable_and_valid(tmp_path: Path) -> None:
     _write_root_skill(tmp_path, "widget", "widget body")
     register_skill_dir(tmp_path)
 
     assert "widget" in get_all_skill_names()
-    assert get_available_skills()["root"] == ["widget"]
+    assert get_available_skills()["root"] == [{"name": "widget", "description": ""}]
     assert validate_requested_skills(["widget"]) is None
     assert validate_requested_skills(["root/widget"]) is None
     assert load_skills(["widget"]) == {"widget": "widget body"}
@@ -83,8 +197,8 @@ def test_ambiguous_bare_skill_requires_qualified_name(tmp_path: Path) -> None:
     register_skill_dir(tmp_path)
 
     assert "widget" in get_all_skill_names()
-    assert get_available_skills()["alpha"] == ["widget"]
-    assert get_available_skills()["beta"] == ["widget"]
+    assert get_available_skills()["alpha"] == [{"name": "widget", "description": ""}]
+    assert get_available_skills()["beta"] == [{"name": "widget", "description": ""}]
     assert validate_requested_skills(["alpha/widget"]) is None
     assert validate_requested_skills(["beta/widget"]) is None
 

uv.lock

@@ -2378,7 +2378,7 @@ wheels = [
 
 [[package]]
 name = "strix-agent"
-version = "1.4.1"
+version = "1.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "caido-sdk-client" },