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 to install Heeler skills into any repository:

# 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:

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:

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

Or set the environment variable:

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:

.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):

#!/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):

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:

   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:

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.