# How Skills Are Validated for Security Vulnerabilities Before Publication in Agent-Skills

> Learn how Agent-Skills validates security vulnerabilities before publication using SHA-256 hashing, Snyk scans, and CI checks to protect the public registry from a vulnerable code.

- Repository: [TechLeads.club 💎/agent-skills](https://github.com/tech-leads-club/agent-skills)
- Tags: how-to-guide
- Published: 2026-05-18

---

**The agent-skills catalog enforces a rigorous security-validation pipeline using incremental SHA-256 hashing, Snyk Agent Scan, and mandatory CI checks to ensure no vulnerable code reaches the public registry.**

The **tech-leads-club/agent-skills** repository maintains a stringent security posture by validating every skill for vulnerabilities before publication. This automated pipeline ensures that only vetted, safe code enters the public registry. Each skill undergoes incremental hashing, dependency scanning, and allow-list verification as implemented in the TypeScript scanning logic and GitHub Actions workflows.

## Incremental SHA-256 Hashing for Efficient Scanning

To avoid redundant security checks, the catalog implements **incremental SHA-256 hashing** that identifies changed skills. In [`packages/skills-catalog/src/scan-skills.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/skills-catalog/src/scan-skills.ts) (lines 82-87), the system computes hashes for each skill's complete file set. Only skills with modified hashes trigger a new scan, significantly reducing CI runtime for unchanged components.

### Cache Artifacts and Storage

Scan results persist in [`.security-scan-results.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.security-scan-results.json) and [`.security-scan-cache.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.security-scan-cache.json), both git-ignored. These files enable the CI to reuse previous results when content remains static. The cache handling logic appears in [`.github/actions/security-scan/action.yml`](https://github.com/tech-leads-club/agent-skills/blob/main/.github/actions/security-scan/action.yml) (lines 38-41), ensuring rapid incremental runs across pipeline executions.

## Snyk Agent Scan Integration

The repository leverages **Snyk Agent Scan** (formerly `mcp-scan`) to detect known vulnerabilities, insecure dependencies, and unsafe code patterns. This scan executes automatically via the composite action defined in [`.github/actions/security-scan/action.yml`](https://github.com/tech-leads-club/agent-skills/blob/main/.github/actions/security-scan/action.yml) (lines 47-55). The scanner examines source files and dependencies against Snyk's vulnerability database before allowing publication.

## Managing False Positives with Allow-Lists

When the scanner reports intentional safe patterns—such as trusted internal integrations—contributors can suppress findings through the allow-list file [`packages/skills-catalog/security-scan-allowlist.yaml`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/skills-catalog/security-scan-allowlist.yaml). Each entry requires the skill name, Snyk code, justification reason, and approver metadata. Documentation for this workflow resides in [`SECURITY.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SECURITY.md) (lines 117-138), ensuring audit trails for all security exceptions.

```yaml

# Adding a false-positive entry to the allow-list

- skill: my-cool-skill
  code: SNYK-CODE-123456
  reason: Trusted internal script
  allowedBy: maintainer@example.com
  allowedAt: 2024-11-01T12:00:00Z

```

## CI Enforcement and Merge Protection

The security scan operates as a blocking gate in [`.github/workflows/release.yml`](https://github.com/tech-leads-club/agent-skills/blob/main/.github/workflows/release.yml) (lines 61-84). The workflow captures the scan outcome—`success` or `failure`—and prevents merging or publishing if any skill fails validation.

### Fork Protection via Merge Queue

For pull requests originating from forks, GitHub does not expose secrets to workflow runners. The repository circumvents this limitation using the **GitHub Merge Queue** with a required status check named "Security Scan (merge queue)". This configuration ensures scans execute on trusted runners before merge completion, as detailed in [`SECURITY.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SECURITY.md).

## Running Security Scans Locally

Developers can validate skills locally before submitting pull requests using the npm script interface. The command triggers the Nx executor that wraps the TypeScript scanning logic and Snyk integration.

```bash

# Compute hashes and run the incremental security scan locally

npm run scan

# Executes: npx nx run @tech-leads-club/skills-catalog:security-scan

```

The underlying GitHub Action implementation follows this pattern:

```yaml

# Example snippet from .github/actions/security-scan/action.yml

- name: Run security scan
  run: npx nx run @tech-leads-club/skills-catalog:security-scan

```

## Summary

- **Incremental hashing** in [`scan-skills.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/scan-skills.ts) ensures only modified skills undergo re-scanning via SHA-256 checksums.
- **Snyk Agent Scan** detects vulnerabilities and unsafe patterns through the composite action in [`security-scan/action.yml`](https://github.com/tech-leads-club/agent-skills/blob/main/security-scan/action.yml).
- **Allow-list management** in [`security-scan-allowlist.yaml`](https://github.com/tech-leads-club/agent-skills/blob/main/security-scan-allowlist.yaml) provides auditable exceptions for false positives.
- **CI blocking** in [`release.yml`](https://github.com/tech-leads-club/agent-skills/blob/main/release.yml) prevents publication of vulnerable skills through mandatory status checks.
- **Merge queue protection** ensures forked contributions undergo security validation on trusted infrastructure before merging.

## Frequently Asked Questions

### What tool performs the actual vulnerability scanning?

The pipeline uses **Snyk Agent Scan** (formerly `mcp-scan`) to analyze skill source files and dependencies. The scanner runs via `npx nx run @tech-leads-club/skills-catalog:security-scan` within the GitHub Actions workflow, checking for known CVEs and insecure coding patterns.

### How does the system avoid scanning unchanged skills?

The implementation in [`packages/skills-catalog/src/scan-skills.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/skills-catalog/src/scan-skills.ts) computes **SHA-256 hashes** for each skill's file set. These hashes compare against cached values in [`.security-scan-cache.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.security-scan-cache.json), skipping scans for content that matches previous validations.

### Can I bypass security findings for intentional code patterns?

Yes. Contributors may add entries to [`packages/skills-catalog/security-scan-allowlist.yaml`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/skills-catalog/security-scan-allowlist.yaml) with the specific Snyk code, justification reason, and approver details. This documented exception process requires audit trail metadata as specified in [`SECURITY.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SECURITY.md) (lines 117-138).

### Why doesn't the scan run immediately on fork pull requests?

GitHub restricts secret access in workflows triggered by forks. Instead, the repository uses a **required status check** and **GitHub Merge Queue** to execute the security scan on a trusted runner after the PR enters the merge queue, preventing vulnerable code from reaching the main branch.