---
name: shakerscan-agent-gate
description: Use when a user wants to connect Shaker Scan to an agent, MCP-enabled IDE, CI pipeline, or deployment workflow. Configure the Shaker MCP server, create or use an API key, submit scans, poll results, fetch findings, verify supported findings, evaluate policy, and return an evidence-backed gate decision.
---

# ShakerScan Agent Gate

Use this skill when Shaker should become part of an automated workflow rather than a dashboard-only tool.

Hosted production base URL: `https://shakerscan.com`

If you run Shaker Scan in another environment, replace that base URL accordingly. Relative API paths below are shown so the same workflow also works for self-hosted or local deployments.

## What this skill does

- Connects an agent to Shaker through MCP or direct HTTP
- Uses the current live API surface:
  - `POST /api/v1/scan`
  - `GET /api/v1/scan`
  - `GET /api/v1/scans`
  - `GET /api/v1/findings`
  - `POST /api/v1/findings/:id/verify`
  - `POST /api/v1/policy/evaluate`
  - `GET /api/v1/evidence/:id`
  - `POST /api/v1/evidence/:id/token`
  - `POST /api/v1/approval-tokens/verify`
  - `POST /api/v1/findings/:id/remediate`
  - `GET /api/v1/remediation/:id`
  - `GET /api/v1/usage`
- Applies an evidence-backed workflow decision when verify and policy are available, with a fallback heuristic only when needed

## Quick selection

- For Claude Code or Cursor: use MCP first
- For CI or bots: use the CLI gate command first, then direct HTTP when you need raw control
- For Codex-style agents: use this skill for procedure and MCP, CLI, or HTTP for execution

## Copy-ready setup

### MCP for Claude Code or Cursor

```json
{
  "mcpServers": {
    "shakerscan": {
      "command": "npx",
      "args": ["-y", "shakerscan-mcp"],
      "env": {
        "SCANNER_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

### CLI gate

```bash
npx -y shakerscan gate \
  --api-key "$SHAKER_API_KEY" \
  --target "$TARGET_URL" \
  --scan-type quick \
  --environment preview \
  --policy-pack preview-fast \
  --approval-token true \
  --approval-token-audience github-actions
```

### Minimal direct HTTP flow

Base URL: `https://shakerscan.com`

1. `POST https://shakerscan.com/api/v1/scan`
2. Poll `GET https://shakerscan.com/api/v1/scan?id=...`
3. `GET https://shakerscan.com/api/v1/findings?scan_id=...`
4. `POST https://shakerscan.com/api/v1/findings/:id/verify` for supported critical and high findings
5. `POST https://shakerscan.com/api/v1/policy/evaluate`
6. `GET https://shakerscan.com/api/v1/evidence/:id`
7. If allow, `POST https://shakerscan.com/api/v1/evidence/:id/token`
8. If blocked, optionally `POST https://shakerscan.com/api/v1/findings/:id/remediate`

## Inputs to ask for

- Target URL
- Environment: `preview`, `staging`, or `production`
- Policy pack: usually `preview-fast` or `release-strict`
- Whether the workflow needs an approval token audience such as `github-actions`
- Whether the user wants remediation when the result is `block` or `needs_approval`

## Default workflow

1. Confirm the target belongs to the user or they have permission.
2. Prefer a quick, non-invasive scan for preview or CI flows.
3. Submit the scan.
4. Poll until `completed` or `failed`.
5. Fetch findings.
6. Verify critical and high findings that support deterministic retesting.
7. Run policy evaluation for the scan, naming a `policy_pack` when the workflow needs an explicit gate mode such as `preview-fast`, `release-strict`, or a tenant custom pack.
8. Fetch evidence if the workflow needs a durable artifact.
9. Mint an approval token when the effective decision is `allow` and a downstream system needs signed proof.
10. Request remediation for blocked or high-risk findings when the workflow needs a durable fix plan, patch suggestion, or PR draft.
11. Fetch usage if the workflow needs reporting or budget awareness.
12. Return the policy decision when available. Fallback to a conservative decision only if verify or policy cannot run:

- `block` if any `critical` findings exist
- `needs_approval` if any `high` findings exist
- `allow` otherwise

State clearly whether the decision came from `evaluate_policy` or from the fallback heuristic.

## Operational rules

- Prefer `quick: true` and `public: true` unless the user explicitly wants deeper testing and the target is eligible.
- If the API returns a domain-verification or plan restriction error, downgrade to the safe scan path and explain why.
- Keep findings summaries compact. Show top critical and high issues first.
- If using MCP, ask the model to call the Shaker tools directly instead of reimplementing scan orchestration in text.
- When verification returns `unsupported`, preserve the finding in the decision path and call that out.

## Output shape

When acting as a gate, return:

- `decision`: `allow | block | needs_approval`
- `reason`: one sentence
- `scan_id`
- `critical_count`
- `high_count`
- `evidence_id`
- `next_step`