# vercel-labs/agent-skills architecture

> Architecture diagram of the GitHub repository vercel-labs/agent-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vercel-labs/agent-skills
- Repository: https://github.com/vercel-labs/agent-skills

## Overview

This repository packages agent skills; its most substantial executable workflow is the Vercel Optimize audit. The README describes collecting Vercel metrics, investigating only implicated routes and files, and producing a ranked report. The graph follows that workflow and its gate, scanner, and report layers. Other documented skills are represented by instructions and content not present in the supplied tree. Several workflow scripts are unsampled, so their internal calls are not asserted.

Main entry points: [`skills/vercel-optimize/lib/gates/index.mjs`](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/gates/index.mjs) (Candidate gates), [`skills/vercel-optimize/scripts/collect-signals.mjs`](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/collect-signals.mjs) (Collect signals), [`skills/vercel-optimize/lib/render-report.mjs`](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/render-report.mjs) (Render report), [`skills/vercel-optimize/lib/scanners/index.mjs`](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/scanners/index.mjs) (Code scanners)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audit["Audit workflow"]
  node_collect["Collect signals"]
end

subgraph group_signals["Signal analysis"]
  node_scan["Scan codebase<br/>[scan-codebase.mjs]"]
  node_gates["Candidate gates<br/>[index.mjs]"]
  node_scanner["Code scanners<br/>[index.mjs]"]
  node_routes["Route normalization"]
end

subgraph group_findings["Findings and investigation"]
  node_reconcile["Reconcile candidates"]
  node_brief["Investigation brief"]
  node_deepdive["Deep dive<br/>[deep-dive.mjs]"]
  node_verify["Verify claims<br/>[verify-claim.mjs]"]
end

subgraph group_reporting["Report and trust"]
  node_sanitize["Sanitize recommendations<br/>[index.mjs]"]
  node_dedup["Deduplicate recommendations<br/>[dedup-recs.mjs]"]
  node_render["Render report<br/>[render-report.mjs]"]
  node_coverage["Cost coverage<br/>[cost-coverage.mjs]"]
end

node_user(("Agent or user"))
node_vercel[("Vercel project")]

node_user -->|"requests audit"| node_collect
node_collect -->|"collects metrics"| node_vercel
node_collect -.->|"provides signals"| node_gates
node_scan -.->|"runs scanners"| node_scanner
node_scanner -->|"feeds findings"| node_gates
node_gates -->|"normalizes routes"| node_routes
node_gates -.->|"produces candidates"| node_reconcile
node_reconcile -.->|"selects investigations"| node_brief
node_brief -.->|"guides investigation"| node_deepdive
node_deepdive -.->|"checks claims"| node_verify
node_verify -.->|"supports findings"| node_sanitize
node_sanitize -.->|"filters recommendations"| node_dedup
node_dedup -.->|"provides recommendations"| node_render
node_render -->|"computes cost coverage"| node_coverage
node_render -->|"returns ranked report"| node_user

click node_collect "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/collect-signals.mjs"
click node_scan "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/scan-codebase.mjs"
click node_gates "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/gates/index.mjs"
click node_scanner "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/scanners/index.mjs"
click node_routes "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/route-normalize.mjs"
click node_reconcile "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/reconcile-candidates.mjs"
click node_brief "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/investigation-brief.mjs"
click node_deepdive "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/deep-dive.mjs"
click node_verify "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/verify-claim.mjs"
click node_sanitize "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/sanitizers/index.mjs"
click node_dedup "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/dedup-recs.mjs"
click node_render "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/render-report.mjs"
click node_coverage "https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/cost-coverage.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_collect,node_user toneBlue
class node_scan,node_gates,node_scanner,node_routes,node_vercel toneAmber
class node_reconcile,node_brief,node_deepdive,node_verify toneMint
class node_sanitize,node_dedup,node_render,node_coverage toneRose
```

## Components

### Audit workflow

- [Collect signals](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/collect-signals.mjs): `skills/vercel-optimize/scripts/collect-signals.mjs`

### Signal analysis

- [Scan codebase](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/scan-codebase.mjs): `skills/vercel-optimize/scripts/scan-codebase.mjs`
- [Candidate gates](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/gates/index.mjs): `skills/vercel-optimize/lib/gates/index.mjs`
- [Code scanners](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/scanners/index.mjs): `skills/vercel-optimize/lib/scanners/index.mjs`
- [Route normalization](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/route-normalize.mjs): `skills/vercel-optimize/lib/route-normalize.mjs`

### Findings and investigation

- [Reconcile candidates](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/reconcile-candidates.mjs): `skills/vercel-optimize/scripts/reconcile-candidates.mjs`
- [Investigation brief](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/investigation-brief.mjs): `skills/vercel-optimize/lib/investigation-brief.mjs`
- [Deep dive](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/scripts/deep-dive.mjs): `skills/vercel-optimize/scripts/deep-dive.mjs`
- [Verify claims](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/verify-claim.mjs): `skills/vercel-optimize/lib/verify-claim.mjs`

### Report and trust

- [Sanitize recommendations](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/sanitizers/index.mjs): `skills/vercel-optimize/lib/sanitizers/index.mjs`
- [Deduplicate recommendations](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/dedup-recs.mjs): `skills/vercel-optimize/lib/dedup-recs.mjs`
- [Render report](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/render-report.mjs): `skills/vercel-optimize/lib/render-report.mjs`
- [Cost coverage](https://github.com/vercel-labs/agent-skills/blob/main/skills/vercel-optimize/lib/cost-coverage.mjs): `skills/vercel-optimize/lib/cost-coverage.mjs`

### Other components

- **Agent or user**
- **Vercel project**

## Connections

- Agent or user → Collect signals: requests audit
- Collect signals → Vercel project: collects metrics
- Collect signals → Candidate gates: provides signals
- Scan codebase → Code scanners: runs scanners
- Code scanners → Candidate gates: feeds findings (evidence: `skills/vercel-optimize/lib/gates/index.mjs`)
- Candidate gates → Route normalization: normalizes routes
- Candidate gates → Reconcile candidates: produces candidates
- Reconcile candidates → Investigation brief: selects investigations
- Investigation brief → Deep dive: guides investigation
- Deep dive → Verify claims: checks claims
- Verify claims → Sanitize recommendations: supports findings
- Sanitize recommendations → Deduplicate recommendations: filters recommendations
- Deduplicate recommendations → Render report: provides recommendations
- Render report → Cost coverage: computes cost coverage (evidence: `skills/vercel-optimize/lib/render-report.mjs`)
- Render report → Agent or user: returns ranked report