> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/prevent/agent-skills.md). # Agent Skills Drop-in security capabilities your AI coding agent runs in natural language — secret, vulnerability, license, and malicious-package scans, plus a full security review — each backed by heelercli. **Agent Skills** let a developer run Heeler's security checks in plain language, right inside the coding agent — *"scan this repo for secrets,"* *"is this dependency safe to add?"*, *"run a security review before we release."* Each skill is a drop-in capability the agent discovers automatically in the repository and wraps a [`heelercli`](/mrecEO40m5D6bt7Pq5pE/prevent/cli.md) command, so the check runs where the code is being written — left of the pull request. {% hint style="info" %} **Who this is for:** developers using an AI agent that supports skills — Claude Code, Cursor, GitHub Copilot, OpenCode, Codex, and VS Code. **This page is the catalog and how to use them.** To install them across your repos (via dotagents) and roll them out, see [Set Up Developer Tooling → Install Agent Skills](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/agent-skills.md). Most skills need [`heelercli`](/mrecEO40m5D6bt7Pq5pE/prevent/cli.md) installed and authenticated — **secret scanning is the exception and works with no Heeler account**. {% endhint %} ## Available skills Each skill activates automatically when the conversation calls for it — there's no command to remember, though you can also invoke one by name. | Skill | What it does | Activates when… | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `heeler-secrets-scan` | Scans the repo or staged changes for exposed credentials, keys, and tokens. **Runs fully offline — no Heeler auth.** Reports each finding's validation status and what triggered it. | You ask about credential leaks or want a pre-commit secret gate. | | `heeler-vulnerabilities-scan` | CVE analysis across all ecosystems, with severity gating, baseline diffing, and exploitability-aware triage. | You ask about dependency risk, a manifest/lockfile changes and you ask "is this safe?", or you want release readiness. | | `heeler-license-check` | Discovers dependency licenses and checks them against your allow/deny policy. | You ask for a license inventory or an OSS-compliance question, or a dependency is added or upgraded. | | `heeler-malicious-package-scan` | Typosquatting, dependency hijacking, and known-malicious detection via Heeler's package-risk intelligence. | A new dependency is added, a version changes in a PR, or you ask about supply-chain risk before release. | | `heeler-recommended-version` | The safest version to install or upgrade to — the most widely-adopted version with no active vulnerabilities, not just the latest tag. | You add a dependency and ask what version, ask whether to upgrade, or as a substep of a review. | | `heeler-scan-all` | All four scans (secrets + vulnerabilities + licenses + malicious) in one pass → a unified report with a consolidated verdict. | You want one-command coverage or a pre-release gate. | | `heeler-security-review` | A structured full-repo AppSec audit with a prioritized remediation plan (detailed below). | You ask for a full audit or a release-readiness check. | | `heeler-threat-modeling` | Gathers threat-model context from Heeler's APIs and writes an LLM-ready STRIDE/PASTA prompt to disk, then offers to validate the top findings against repository evidence. | You want LLM-assisted threat modeling grounded in platform data. | ## What each skill decides The scanning skills run in **advisory** mode when no policy is configured, and switch to strict **pass/fail** when one is — so the same skill is useful on day one and enforceable once you've set policy. * **Vulnerabilities** — advisory returns a judgment of **`ship`**, **`ship-with-monitoring`**, or **`block for remediation`** (critical and actively-exploitable first, with a reachability check on the top findings). With a policy, it's strict pass/fail against severity thresholds or specific CVE IDs. **Baseline mode** evaluates only findings not present in a prior baseline — so a PR is judged on what it *adds*. * **License** — advisory prefers permissive licenses (MIT, Apache-2.0, BSD) and flags copyleft (GPL/AGPL), unknown, and custom for review; with a policy, it's pass/fail against your allow/deny lists. For any failing package it proposes **one to three compliant alternatives** in the same ecosystem. * **Malicious packages** — each flag is **high confidence** (clear indicators — a release blocker unless the risk is explicitly accepted) or **needs verification** (a suspicious signal with incomplete evidence — concrete verification steps are given before you remove anything). * **`heeler-scan-all`** — four sections then a final verdict: **`PASS`/`FAIL`** for policy-gated checks, or **`ADVISORY`** with an explicit risk judgment when no policy is defined. A missing toolchain doesn't abort the run — the other scans continue and partial coverage is noted. `heeler-scan-all` starts with one `heelercli ci` pass so dependency checks share the same SBOM collection and the report has reconciled counts. It then runs only the targeted detail commands needed to supply CVE, license, secret, or malicious-package evidence that the consolidated result does not contain. ## Inside `heeler-security-review` The review **runs the other skills as substeps** — always secrets, vulnerabilities, and license (a review isn't complete unless all three are attempted; partial coverage is reported if one can't run), plus recommended-version and malicious-package scans when it detects dependency changes. When authenticated SAST is available, it also uses `heelercli sast` to seed the SSRF and injection review, then verifies reachability and attacker-controlled data flow against the source. It then adds analysis that goes beyond automated scanning, across **seven categories**: * **Secrets & credential exposure** — validation status, blast radius, true-positive likelihood. * **Dependency vulnerabilities** — severity, exploitability, CVSS vectors, and reachability from network entry points. * **Application-layer SSRF** — whether attacker-controlled input can reach outbound request sinks and internal targets. * **License & compliance** — prohibited, unknown, and high-review licenses, and missing metadata. * **Supply chain & build integrity** — pinning strategy, lockfile hygiene, CI controls. * **Repository operational security** — least-privilege tokens, logging/redaction, risky shell patterns. * **LLM & agent attack surface** *(when present)* — prompt injection, tool-misuse, and exfiltration controls. Findings carry three confidence levels, but **only `HIGH` and `MEDIUM` appear** in the output — theoretical best-practice notes are dropped to keep the review actionable. For each Critical and High finding, the review gives the **entry point, propagation path, impact, a concrete file-path evidence reference, and remediation steps**. It closes with a risk register, a needs-verification list, a prioritized action plan, and a decision statement: **`ready`**, **`ready with conditions`**, or **`not ready`**. ## Using them Just ask the agent in natural language — *"Run a Heeler security review on this repository"* — or, in Claude Code, invoke a skill by name (`/heeler-scan-all`, `/heeler-secrets-scan`). The agent confirms `heelercli` is installed and authenticated, runs the right command, and returns a structured report. Because each skill wraps a CLI command, the exact same check runs identically in three places: from the agent (here), from your terminal or a pre-commit hook, and in CI — see the [CLI](/mrecEO40m5D6bt7Pq5pE/prevent/cli.md). Use **heelercli 1.0.23 or later** with the current skills. Network-backed scans inherit the CLI's batched SBOM assessment, bounded `429` retries, and explicit partial-coverage reporting. The skills preserve those coverage signals rather than translating a partially analyzed repository into a clean result. For a complete view, connect [MCP](/mrecEO40m5D6bt7Pq5pE/prevent/mcp.md) too. The skills scan the current working tree; MCP supplies stored Heeler context for committed code, services, runtime exposure, policy, and prior findings. Each scanning skill tells the agent where MCP can add that platform context without treating it as a replacement for the local scan. ## Troubleshooting * **Skills not discovered?** Confirm `.agents/skills/` exists and each skill has a `SKILL.md`, then restart the agent. Ask *"What Heeler skills are available?"* to verify. * **Skill errors?** Check `heelercli --version` and authentication — if the CLI works standalone, the issue is agent discovery; restart the agent. * **A network-backed skill is rate limited?** Upgrade to heelercli 1.0.23 or later, let the CLI honour `Retry-After`, and avoid immediately replaying the same skill call. See [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md). * **A scan says it's advisory when you expected pass/fail?** No policy is configured for that check — set one so the skill gates strictly (secrets is the exception and always runs). ## Worked example See this as part of securing your AI coding agents end to end: {% content-ref url="/pages/IBFvawl27EPDOZqk2Tar" %} [Secure AI Coding Agents](/mrecEO40m5D6bt7Pq5pE/solutions-and-use-cases/secure-your-ai-coding-agents.md) {% endcontent-ref %} ## Related * [CLI](/mrecEO40m5D6bt7Pq5pE/prevent/cli.md) — the engine behind every skill; run the same checks directly or in CI. * [MCP Server](/mrecEO40m5D6bt7Pq5pE/prevent/mcp.md) — the read-only context counterpart: live Heeler data the agent reasons over as it writes. * [Rate Limits](/mrecEO40m5D6bt7Pq5pE/reference/rate-limits.md) — the batching and retry behavior inherited from the CLI. * [Install Agent Skills](/mrecEO40m5D6bt7Pq5pE/get-started/set-up-developer-tooling/agent-skills.md) — dotagents install and org rollout. * [Threat Modeling with the Service Decomposition Export](/mrecEO40m5D6bt7Pq5pE/solutions-and-use-cases/threat-modeling-with-service-decomposition.md) — what `heeler-threat-modeling` produces, and the platform export it mirrors. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/prevent/agent-skills.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.