MCP, Skills, and Recipes

Achilles is built to pair with your editor and coding agent, not to replace them. This page covers the three integration surfaces: the Model Context Protocol server, the built-in industry skills, and the packaged recipes with their scheduler.

Achilles finds, your harness patches

Achilles runs beside Codex, Claude Code, OpenCode, and Cursor as a dedicated security pair programmer. Achilles finds, triages, and briefs with the ledger as shared context; your harness patches. The payoff is that both sides stay more accurate and far more token efficient than either alone: your agent does not re-scan anything, and it reasons over confirmed evidence instead of pasted files.

MCP: the harness as a tool

Model Context Protocol lets your coding agent use Achilles as a tool. Findings stay in the local ledger, and the agent reads that ledger over MCP instead of you pasting scan output or whole files into chat.

Point your editor's MCP server config at the Achilles binary with the mcp argument:

{
  "mcpServers": {
    "achilles": {
      "command": "achilles",
      "args": ["mcp"]
    }
  }
}

This works in Cursor, Claude Code, Codex, OpenCode, or any MCP host. The AppSec tools exposed are:

Tool	Purpose
appsec_scan	Start a scan on a workspace, fast or deep
appsec_query	Query the ledger for open findings and details
appsec_investigate	Run the investigator/validator loop over selected findings
appsec_brief	Produce a copy-pasteable fix brief for a finding
appsec_verdict	Resolve a finding as confirmed, false positive, or fixed
appsec_triage	Work the triage queue
appsec_utils	Second-line utilities: hashing, redaction, encryption, SBOM
appsec_intel	External intel lookup (KEV, EPSS, Socket, NVD-style feeds)

No editor is required: the same tools work headless via the achilles appsec CLI for CI and scripts, covered on the headless CLI page.

Skills: how to think, not what to guess

A skill is a SKILL.md playbook compiled into the desktop and CLI binaries. The model loads it when the chat topic matches, and it teaches how to think about a class of security issues, not how to run a second scanner. Skills are ledger-first: they instruct the model to cite finding ids and engine output rather than invent CVEs or attack paths.

The 13 built-in skills

Review (ledger-first judgment)

Skill	When the model loads it
auth-review	Authentication and authorization questions - login, sessions, JWT, permission checks
code-review	Security-minded review of a path or git diff; no invented CVEs
review-findings	Discussing the latest scan; finding ids only, spell out SAST/SCA context
security-review	High-confidence PR / branch / diff review that demands a concrete path to a sink

Orient (map the surface)

Skill	When the model loads it
map-codebase	Layout, entry points, how to build and test - without a whole-tree dump
map-attack-surface	Deploy, CI, and cloud surfaces from fingerprint output - nothing invented
threat-model	Lightweight threat model from surfaces plus open findings

Intel (explain the finding)

Skill	When the model loads it
dependency-risk	SCA finding or known-vulnerable library questions go through appsec_intel; no invented scores
stack-security	Stack playbooks for JS, Python, Go, Rust, IaC, GitHub Actions, auth flows

Pipeline (CI and workflows)

Skill	When the model loads it
github-actions-security	Workflow files: pull_request_target, write-all, persist-credentials, fork-PR secrets

Remediate (ship the fix)

Skill	When the model loads it
propose-fix	Produce a patch brief for one finding id; waits for confirmation before editing
rotate-secret	Remove a leaked credential from the repo and rotate it; never prints the secret
variant-hunt	Hunt the same bug pattern elsewhere, given one finding or file:line

Toggle any skill per model in the desktop's Skills panel. The rule of thumb: a skill is loaded mid-chat when the topic matches, and once loaded it should behave like a security engineer, citing the ledger and confronting speculation with engine output.

Recipes: the same job on demand or on a timer

A recipe is a YAML session definition - extensions enabled, parameters set, prompt preloaded - shipped inside the binary. On first run Achilles materializes them into the app data shipped-recipes/ folder, where they appear in the Recipe Library and cannot be deleted (editing one saves a personal copy). You can also import extra recipes or run one by path from the CLI.

The three shipped recipes:

Recipe	What it does	Best for
Scan Recap	Runs a fast scan, then walks severity, engine, and triage state for every open finding	A quick health check after landing changes, or a scheduled nightly recap
SCA Hygiene Report	Pulls known-vulnerable packages from lockfiles and flags unpinned versions, missing locks, risky install scripts, and lookalike names	Weekly dependency review
Security Review	High-confidence review of the PR, branch, or diff you are on, demanding a concrete path to a sink	Pre-merge review

Skills vs recipes

	Skills	Recipes
Shape	SKILL.md playbook, loaded when the topic matches	YAML file: extensions, params, prompt ready at session start
Best for	How to think about a class of issues mid-chat	The same job, the same tools, on demand or on a timer
Example	security-review while you are already chatting	Launch security-review.yaml with a PR number and schedule it before merges

Schedule recipes

The scheduler only fires recipes - it is not a scan queue. In the desktop, open a recipe and choose Schedule (cron), or go to Recipe Library and create a schedule. Headless schedules use the CLI once the server is started with --enable-scheduler:

# Daily 02:00 local - fast scan plus recap
achilles schedule add --schedule-id nightly-scan --cron "0 0 2 * * *" \
  --recipe-source recipes/scan-recap.yaml \
  --params workspace=/path/to/repo

# Monday 09:00 local - SCA plus pinning
achilles schedule add --schedule-id weekly-sca --cron "0 0 9 * * 1" \
  --recipe-source recipes/sca-hygiene-report.yaml \
  --params workspace=/path/to/repo

workspace is a required parameter on schedules so the job never accidentally scans the server's current directory. Run a recipe directly instead:

achilles run --recipe scan-recap --params workspace=/path/to/repo
achilles run --recipe recipes/security-review.yaml --params workspace=/path/to/repo --params pr=123

Recipes in practice

Because the binary materializes shipped recipes on launch, the same loop works in the desktop or fully headless in CI. A complete CI job looks like:

# .github/workflows/security-review.yml (excerpt)
- name: Achilles scan recap
  run: |
    achilles run --recipe scan-recap --params workspace=${{ github.workspace }}

Every result, on desktop or in CI, writes to the same local ledger, so a finding triaged in the IDE in the evening does not reappear as "new" when the CI job retries in the morning.