# Agent Skills Deployment Guide

Heeler Agent Skills bring security scanning directly into AI coding agents. When installed in a repository, skills are automatically discovered by agents like Claude Code, Cursor, GitHub Copilot, OpenCode, Codex, and VS Code — enabling developers to run security checks through natural language without leaving their workflow.

### Prerequisites

* **`heelercli`** installed (see the CLI Deployment Guide) — authentication is required for most skills, but secrets scanning works without it
* **Node.js** (v18+) — required for the `dotagents` package manager
* An **AI coding agent** — Claude Code, Cursor, GitHub Copilot, Codex, OpenCode, or VS Code with an AI extension

### Available skills

| Skill                           | Description                                                                   | CLI command                           |
| ------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------- |
| `heeler-secrets-scan`           | Detect and validate exposed secrets, tokens, and API keys                     | `heelercli secrets`                   |
| `heeler-vulnerabilities-scan`   | CVE analysis with severity gating and baseline regression                     | `heelercli vulnerabilities`           |
| `heeler-license-check`          | OSS license compliance, prohibited license detection                          | `heelercli licenses`                  |
| `heeler-malicious-package-scan` | Typosquatting and supply-chain malware detection                              | `heelercli detect-malicious-packages` |
| `heeler-scan-all`               | Combined full security scan (secrets + vulns + licenses + malicious packages) | `heelercli ci`                        |
| `heeler-security-review`        | Comprehensive repository security posture review with prioritized remediation | Orchestrates all scans                |
| `heeler-recommended-version`    | Recommended safe dependency version for a package                             | `heelercli get-recommended-version`   |
| `heeler-threat-modeling`        | PASTA/STRIDE threat model context and prompt generation                       | `heelercli threat-model`              |

### Step 1: Install skills into your repository

Use [dotagents](https://github.com/getsentry/dotagents) to install Heeler skills into any repository:

```bash
# Initialize dotagents in your repo (creates agents.toml if needed)
npx @sentry/dotagents init

# Add all Heeler skills
npx @sentry/dotagents add Heeler-Security/heelercli --all

# Install skills into .agents/skills/
npx @sentry/dotagents install
```

This creates a `.agents/skills/` directory containing the skill definitions. Commit this directory to your repository so all team members have access.

#### Installing specific skills only

If you don't need all skills, install a subset:

```bash
npx @sentry/dotagents add Heeler-Security/heelercli heeler-security-review heeler-scan-all
npx @sentry/dotagents install
```

### Step 2: Authenticate heelercli

Most skills require `heelercli` to be authenticated. The exception is **secrets scanning**, which works without authentication. For all other skills (vulnerabilities, licenses, malicious packages, etc.), authenticate if you haven't already:

```bash
heelercli login https://app.heeler.com YOUR_HEELER_API_KEY
```

Or set the environment variable:

```bash
export HEELER_API_KEY=YOUR_HEELER_API_KEY
```

For full authentication details, see the CLI Deployment Guide.

### Step 3: Verify skills are discovered

Open your AI coding agent in the repository and test that skills are available.

**Claude Code:**

You can invoke skills in two ways:

1. **Natural language** — just describe what you want:

   ```
   > Run a Heeler security review on this repository
   ```
2. **Slash commands** — invoke skills directly by name:

   ```
   > /heeler-scan-all
   > /heeler-secrets-scan
   > /heeler-vulnerabilities-scan
   ```

**Cursor / GitHub Copilot / VS Code:**

Ask your agent to run a security scan or check for vulnerabilities. The agent should discover and invoke the appropriate Heeler skill.

The agent will:

1. Check that `heelercli` is installed (`heelercli --version`)
2. Verify authentication is available
3. Run the appropriate scan command
4. Present findings in a structured report

***

### Skill reference

#### heeler-secrets-scan

**When to use:** When committing code, or when asked to detect secrets, credential leaks, or API key exposure.

**What it does:** Runs `heelercli secrets` to scan for exposed credentials with validation to reduce false positives.

**Example prompt:** "Scan this repo for exposed secrets before I push."

***

#### heeler-vulnerabilities-scan

**When to use:** When dependency manifests or lockfiles change, when asking if a dependency upgrade is safe, or for release readiness checks.

**What it does:** Runs `heelercli vulnerabilities` with severity gating and optional baseline regression.

**Example prompt:** "Check if my dependencies have any critical vulnerabilities."

***

#### heeler-license-check

**When to use:** When adding new dependencies, during license audits, or for compliance checks.

**What it does:** Runs `heelercli licenses` to inventory dependency licenses and flag policy violations.

**Example prompt:** "Are any of my dependencies using GPL licenses?"

***

#### heeler-malicious-package-scan

**When to use:** When adding new dependencies, or when investigating supply-chain risk.

**What it does:** Runs `heelercli detect-malicious-packages` to detect typosquatting, malware, and compromised packages.

**Example prompt:** "Check if any of my npm dependencies are flagged as malicious."

***

#### heeler-scan-all

**When to use:** When asked for a "full scan" or "scan everything" — a single-command comprehensive security pass.

**What it does:** Orchestrates secrets scanning, vulnerability scanning, license checks, and malicious package detection in sequence, then produces a consolidated report.

**Example prompt:** "Run a full Heeler security scan on this project."

***

#### heeler-security-review

**When to use:** When asked for a security posture review, appsec audit, or release-readiness check.

**What it does:** Runs all scans (secrets, vulnerabilities, licenses, malicious packages, recommended versions) and produces a prioritized remediation plan with confidence-rated findings.

**Example prompt:** "Give me a full security review of this repository with remediation priorities."

***

#### heeler-recommended-version

**When to use:** When installing or upgrading a dependency and needing guidance on which version to use.

**What it does:** Runs `heelercli get-recommended-version` to find the most-used version in your environment with no active vulnerabilities.

**Example prompt:** "What version of lodash should I use?"

***

#### heeler-threat-modeling

**When to use:** When performing PASTA or STRIDE threat modeling, or when asked to generate threat model context.

**What it does:** Resolves the service ID for the repository, gathers threat model context from the Heeler platform, and generates a structured prompt for threat modeling analysis.

**Example prompt:** "Generate a PASTA threat model for this service."

***

### Automating setup across your organization

#### Repo templates

Include the skills configuration in your repository template so every new project has agent skills from day one:

```
my-repo-template/
  agents.toml              # dotagents configuration
  .agents/
    skills/                # pre-installed Heeler skills
      heeler-secrets-scan/
      heeler-vulnerabilities-scan/
      heeler-license-check/
      heeler-malicious-package-scan/
      heeler-scan-all/
      heeler-security-review/
      heeler-recommended-version/
      heeler-threat-modeling/
  ...
```

#### Bootstrap script

Add dotagents installation to your existing developer setup script:

**`Makefile` example:**

```makefile
.PHONY: setup
setup:
	pip install pre-commit
	pre-commit install
	npx @sentry/dotagents install
	@echo "Heeler CLI hooks and agent skills activated."
```

**Standalone script (`scripts/dev-setup.sh`):**

```bash
#!/usr/bin/env bash
set -euo pipefail

echo "Installing pre-commit framework..."
pip install pre-commit
pre-commit install

echo "Installing agent skills..."
npx @sentry/dotagents install

echo "Done. Heeler security scanning and agent skills are active."
```

#### CI reproducibility

For deterministic installs in CI (no network fetches for skill definitions):

```bash
npx @sentry/dotagents install --frozen
```

This uses the lockfile created by `dotagents add` to ensure the exact same skill versions are installed every time.

***

### Troubleshooting

#### "heelercli is not on PATH"

Skills require `heelercli` to be installed and available on the developer's PATH. Install it following the CLI Deployment Guide.

#### Authentication errors

Skills other than secrets scanning check for authentication before running. Ensure you've either:

* Run `heelercli login https://app.heeler.com YOUR_API_KEY`, or
* Set `HEELER_API_KEY` in your environment

#### Skills not discovered by the agent

1. Confirm `.agents/skills/` exists in your repository root:

   ```bash
   ls .agents/skills/
   ```
2. Ensure each skill directory contains a `SKILL.md` file
3. Restart your AI agent / IDE to pick up new files
4. Try explicitly asking the agent: "What Heeler skills are available?"

#### Skills run but return errors

Check that `heelercli` is working independently:

```bash
heelercli --version
heelercli secrets -q
```

If the CLI works but skills don't, the issue is likely with agent discovery. Restart the agent and try again.