Specification v1.0.0

SkillBOM

Skill Bill of Materials — The Security Standard for AI Skills

The first portable, machine-readable manifest format that declares everything about an AI skill's dependencies, permissions, behavior, and provenance.

1. Overview

A SkillBOM is a JSON document that accompanies every AI skill (MCP tool, agent skill, or integration) published to the MYGRYN marketplace. It serves as a complete security profile, enabling automated risk assessment, trust scoring, and compliance verification.

Design Principles

  1. Dual-Source Model — Publishers declare a manifest; the platform scanner independently verifies and enriches it. Mismatches are themselves trust signals.
  2. Machine-Readable First — JSON Schema validated, parseable by CI/CD pipelines, IDE extensions, and API consumers.
  3. Language-Agnostic — Works for Node.js, Python, Go, Rust, and Docker-based skills.
  4. Version-Tracked — Every BOM version is hashed and stored, enabling rug-pull detection across releases.
  5. Compliance-Ready — Maps to EU AI Act (August 2026), NIST AI RMF, and OWASP Agentic Top 10.

Document Types

DocumentFilePurpose
SkillBOMskillbom.schema.jsonPublisher-declared + scanner-enriched manifest
Scanner Overlayscanner-overlay.schema.jsonRaw scanner findings before merge into BOM
Trust Deltatrust-delta.schema.jsonDeclared vs. detected mismatches with trust grade

Lifecycle

Publisher creates skillbom.json
         |
         v
  SUBMISSION      Publisher uploads skill + skillbom.json
         |
         v
  SCANNING        Static analysis, dependency audit,
                  sandbox execution, prompt injection probes,
                  signature verification, reproducible build check
         |
         v
  OVERLAY         Scanner produces scanner-overlay.json
         |
         v
  MERGE           Scanner overlay merges into the BOM
         |
         v
  DELTA           Trust delta report generated for mismatches
         |
         v
  DECISION        approve / conditional / quarantine / delist

2. Schema Sections

codeDependencies

Declares the skill's runtime environment and all code-level dependencies.

Publisher declares
  • Runtime and version (node >=18.0.0, python >=3.10)
  • Package manager and lockfile hash (SHA-256)
  • Direct dependencies with name, version, source, license
Scanner enriches
  • CVE data from OSV/NVD APIs
  • Transitive dependency tree discovery
  • License conflict detection
  • Lockfile hash verification (tamper detection)
  • Undeclared dependencies via AST import scanning

modelDependencies

Declares which LLMs, embedding models, or local ML models the skill uses.

Publisher declares
  • External model API calls (provider, model ID, purpose)
  • Bundled local model files (format, hash, source)
  • Whether the skill chains to other skills
Scanner enriches
  • Detects undeclared HTTP calls to model API endpoints
  • Flags unsafe model formats (pickle, pt)
  • Verifies model file hashes
  • Discovers model calls via AST analysis

dataAccessPatterns

The most security-critical section. Declares every data source and sink.

Sub-sections
  • filesystem — paths read/written, sensitivity flags
  • network — outbound connections, inbound listeners
  • databases — type, SQL ops, tables, PII columns
  • externalApis — endpoints, auth methods, token sources
  • dataFlowSummary — ingress/egress and trust boundary flags
Key risk signals
  • sensitive: true on undeclared paths
  • piiExposure: "raw" — unmasked PII leaves the system
  • crossesTrustBoundary: true
  • Any detectedBy: "scanner" entry

permissionRequirements

Declares what the skill needs permission to do, with justifications.

Permission types: network, filesystem, env_var, secret, process, shell, clipboard, browser, camera, microphone

Key fields
  • scope — narrow scope (e.g. api.stripe.com:443)
  • justification — human-readable reason
  • privilegeLevel — minimal → admin
  • Booleans: shellAccess, canSpawnProcesses, canModifyAgentConfig, canAccessOtherTools
Key risk signals
  • shellAccess: true — always high-risk
  • canModifyAgentConfig: true — CLAUDE.md manipulation
  • scopeCreep: "high" — broader than actual usage
  • Undeclared permissions detected by scanner

behavioralContract

Defines the skill's interface, safety promises, and runtime observations.

Publisher declares
  • toolInterface — MCP tool name, input/output schemas
  • sideEffects — DB writes, API calls, file changes
  • invariants — safety promises (e.g. never_deletes_data)
  • resourceLimits — execution time, memory, output size
Scanner enriches (sandbox)
  • Actual syscall profile and network fingerprint
  • Unexpected syscalls (execve, fork)
  • Prompt injection detection in output
  • Encoded data detection (base64/hex exfiltration)
  • Invariant violation detection

provenance

Establishes the skill's identity, origin, and integrity chain.

Sub-sections
  • publisher — identity, verification method
  • source — repo URL, commit SHA, branch, tag
  • build — reproducibility, artifact hash, signature
  • history — version history with BOM hashes
  • attestations — scans, audits, compliance certs
Rug-pull indicators
  • permissionEscalation — did permissions grow?
  • newNetworkEndpoints — new outbound hosts?
  • descriptionChanged — tool poisoning vector
  • maintainerChanged — account takeover vector

3. Trust Scoring Algorithm

The trust grade (A+ through F) is computed from:

FactorWeightSource
Permission risk score25%permissionRequirements.riskScore
CVE exposure15%codeDependencies.packages[].cves
Behavioral compliance20%behavioralContract.observedBehavior
Provenance strength20%provenance verification depth
Delta severity20%trustDelta.deltas[].severity counts

Grade Thresholds

A90-100 No critical/warning deltas, verified publisher, reproducible build, clean sandbox
B75-89 Minor warnings only, no critical deltas
C60-74 Some warnings, unverified publisher, or unreproducible build
D40-59 Critical deltas present but no active threat indicators
F0-39 Active threat indicators (C2, credential exfiltration, prompt injection)

Auto-actions

  • A/B: Approve for marketplace
  • C: Conditional approve (publisher notified of required fixes)
  • D: Manual review required (CISO notified)
  • F: Automatic quarantine + delist

4. Comparison with Existing Standards

StandardScopeSkillBOM Advantage
SBOM (CycloneDX/SPDX)Code dependencies onlyAdds model deps, data access, permissions, behavior, provenance
AI BOM (emerging)Model + training dataAdds runtime behavior observation and trust delta tracking
OWASP MCP Top 10Risk categoriesOperationalizes detection into a machine-readable format
Docker MCP CatalogContainer-level isolationProvides skill-level granularity within containers
Invariant mcp-scanPoint-in-time scanningTracks trust trajectory across versions

5. File Naming Conventions

<skill-id>.skillbom.json              # Publisher-declared BOM
<skill-id>.scanner-overlay.json       # Scanner findings (internal)
<skill-id>.trust-delta.json           # Published delta report

6. Versioning

The SkillBOM specification follows semver:

  • Major: Breaking schema changes (new required fields, removed fields, changed enums)
  • Minor: New optional fields, new enum values
  • Patch: Description clarifications, documentation fixes

Current version: 1.0.0