> For the complete documentation index, see [llms.txt](https://docs.skillplus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skillplus.xyz/architecture-and-scanning.md).

# Architecture and Scanning Process

SkillPlus is a three-layer security analysis pipeline for AI skills, backed by a persistent supply-chain intelligence graph.

From the user's perspective it stays simple: submit a skill, get a report. Under the hood, every scan feeds a living dataset that keeps re-scoring the ecosystem as new threat intelligence arrives.

## High-level architecture

```mermaid
flowchart TD
    A[Skill URL or repository] --> B[Source resolution<br/>GitHub · skills.sh]
    B --> C1[Layer 1<br/>Deterministic rule engine]
    B --> C2[Layer 2<br/>Supply-chain graph extraction]
    B --> C3[Layer 3<br/>Multi-agent AI audit]
    C2 --> G[(Persistent graph<br/>packages · versions · endpoints)]
    T[Threat intelligence<br/>OSV / MAL advisories] --> BL[Version-precise blacklist]
    BL --> G
    G -->|retroactive hits| H
    C1 --> H[Security report]
    C3 --> H
    H --> I[Rating]
    H --> J[Badge]
    H --> K[Report page]
    H --> L[SDK / API]
```

## Scanning flow

```mermaid
sequenceDiagram
    participant User as User or Platform
    participant SP as SkillPlus
    participant Source as Skill Source
    participant Rules as Rule Engine
    participant Graph as Supply-chain Graph
    participant Agents as Specialist Agents ×4
    participant Lead as Lead Auditor
    participant Verify as Adversarial Verify

    User->>SP: Submit GitHub or skills.sh URL
    SP->>Source: Resolve and fetch skill content
    Source-->>SP: Skill files, instructions, scripts, links
    SP->>Rules: Deterministic security checks
    Rules-->>SP: Findings with file:line evidence
    SP->>Graph: Extract dependencies + network endpoints
    Graph-->>SP: Coordinates, version precision, known advisories, blacklist hits
    SP->>Agents: Structure · Supply Chain · Network · Behavior
    Agents-->>Lead: Independent findings per lens
    Lead-->>SP: Integrated 8-category assessment + recommendations
    SP->>Verify: Re-examine high-severity findings
    Verify-->>SP: Confirmed or refuted
    SP->>SP: Code-enforced invariants (floors, gates)
    SP-->>User: Rating · report · badge · SDK data
```

## 1. Source resolution

SkillPlus accepts common skill sources such as GitHub repositories and skills.sh links. It resolves the source, identifies the skill files, and records the content tree hash — so every report is pinned to the exact content version it analyzed.

## 2. Layer 1 — deterministic rule engine

The first layer looks for known risk patterns:

* unsafe command execution
* credential file access
* suspicious external URLs
* prompt-injection language
* hidden or misleading instructions
* persistence-related behavior
* suspicious downloads
* malformed skill structure

Rule checks are deterministic, fast, and evidence-based. Anything they flag can be inspected down to the file and line.

## 3. Layer 2 — supply-chain graph extraction

The second layer parses the skill's *instructions and scripts* — not just manifests — and extracts:

* **Dependencies**, resolved to ecosystem coordinates (`pypi:litellm`, `npm:skills`) with version-resolution precision: pinned exactly, version range, or unpinned. An unpinned `pip install litellm` in a SKILL.md is captured just like a lockfile entry would be.
* **Network endpoints** the skill references or instructs the agent to contact.

Everything is persisted into the graph. This step is deterministic and runs in milliseconds — and it is what powers retroactive protection (see below).

## 4. Layer 3 — multi-agent AI audit

Four specialist AI analysts review the skill independently, each through one lens:

| Agent                  | Lens                                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Structure & Capability | What can this skill make an agent do? Are declared capabilities consistent with its stated purpose?               |
| Supply Chain           | Judges the extracted graph: confirmed poisoned links, relevant advisories, dependency hygiene.                    |
| Network & Egress       | Where can data go? Documentation links vs. real egress paths; false-positive correction for rule-layer URL flags. |
| Behavior & MCP         | Hidden instructions, prompt manipulation, deceptive content, credential access patterns.                          |

A **Lead Auditor (synthesis)** integrates the specialist findings into a fixed 8-category verdict — command execution, data exfiltration, remote code execution, indirect prompt injection, external downloads, tool poisoning, credential theft, obfuscated payload — plus an executive summary and **actionable recommendations**.

High-severity findings then go through **adversarial verification**: an independent pass that actively tries to refute each one. Refuted findings are downgraded (never silently deleted), and confirmed ones are marked as adversarially verified in the report.

### Severity calibration

All agents follow an explicit calibration contract: **score behavior, not capability**. A finding of medium severity or higher requires a concrete threat path. Ecosystem-normal patterns — invoking a well-known CLI via `npx`, installing what the user asked for, documentation links — are reported as context at low severity. The calibration never applies to known-compromised packages, purpose-anomalous patterns (typosquats, pipe-to-shell, obfuscation), or content that manipulates the agent itself.

### Code-enforced invariants

The final verdict is not left to LLM goodwill. After synthesis, a pure code layer enforces:

1. A high/critical specialist finding can never be dropped by the synthesis stage — it is restored and marked *llm-unconfirmed*.
2. Medium/low findings must pass a confidence gate before affecting the verdict.
3. Adversarially refuted findings are downgraded, never deleted.
4. A **confirmed poisoned dependency forces the risk level to at least High**, no matter what any model says — and forces a remediation step that names the compromised package.
5. The risk level is floored to the worst confirmed finding.
6. If the synthesis stage fails entirely, a fallback verdict is built from the specialists — a broken pipeline can never yield a false "safe".

## 5. Retroactive supply-chain protection

This is the step that runs *without* a scan.

```mermaid
flowchart LR
    A[OSV / MAL advisory feed] --> B[Blacklist entry<br/>version-precise, e.g. litellm 1.82.7–1.82.8]
    B --> C[Propagation over ALL historical scans in the graph]
    C --> D[Hits recorded per skill]
    D --> E[Ratings flip to High everywhere<br/>report · badge · homepage · search]
    E --> F[Report shows the poisoned versions<br/>+ remediation step]
```

Blacklist entries are **version-precise**: only the actually-compromised versions match (no blanket bans of popular packages), so a skill pinned to a safe version is never falsely flagged, while an unpinned dependency on the same package is flagged as *possibly affected*.

## 6. Content-drift-aware re-scanning

Reports are pinned to a content version. When a re-scan is requested, SkillPlus compares the current content hash against the one on record:

* **unchanged** → the AI layer is refreshed in place, same report URL;
* **drifted** → a full fresh scan runs (rules + graph + AI) as a new report, and the old report keeps its history intact.

A report never mixes conclusions from two different versions of a skill.

## 7. Report and trust signals

| Output               | Purpose                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------- |
| Public report page   | Findings, evidence, per-agent analysis, recommendations.                                    |
| Rating               | One consistent risk signal across report, badge, homepage, and search.                      |
| Supply-chain section | Dependency/endpoint counts and any confirmed-malicious links, with poisoned versions named. |
| Badge URL            | Trust made visible in READMEs and marketplaces — always in sync with the report.            |
| SDK/API response     | Structured data for platforms, CI, and governance workflows.                                |

SkillPlus turns raw skill content into a trust signal that stays true over time.


---

# 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.skillplus.xyz/architecture-and-scanning.md?ask=<question>&goal=<endgoal>
```

`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.