Pkg Spec v1.0

AI Skill Package Specification

A .aiskill file is a ZIP archive — a versioned, unit-tested package that delivers an AI agent skill as a structured artifact. Where an AI Skill is an ephemeral text prompt, an AI Skill Package is a deployable, reproducible, integrity-verified unit of capability.

This specification defines the .aiskill open standard: the file format, manifest schema, directory layout, checksum protocol, and capability token registry. The standard is technology-agnostic — any AI runtime that can read a ZIP archive and execute assets can implement it.

Pioneering standard. No prior art has been identified for the .aiskill format or the AI Skill Package concept. This document is the normative specification for v1.0.

What this spec covers

  • The distinction between ephemeral AI Skills and versioned AI Skill Packages
  • The complete .aiskill ZIP layout and all required/optional files
  • The normative manifest.yaml field reference
  • The determinism principle and why it matters for AI-executed computation
  • Step-by-step tutorial for creating your first .aiskill package
  • Real-world examples from the WCP ecosystem
  • The full capability token registry and MIME type association

AI Skills

An AI Skill is a plain UTF-8 Markdown file that instructs an AI agent how to perform a task. It is the simplest unit of AI capability distribution: write a prompt, save it as a .md file, give the AI a URL or paste the content — the skill is loaded.

Characteristics

  • Ephemeral — the skill fires, the AI generates output, the session ends. Nothing persists between sessions.
  • Text-only — instructions, no versioned assets, no tests, no integrity guarantees.
  • Runtime-generated output — the AI interprets the skill and writes code, prose, or instructions fresh each time. Output varies by model, session, and context.
  • Zero infrastructure — a Markdown file in a GitHub repository is sufficient. No build step, no packaging.

AI Skills are excellent for conversational guidance, creative workflows, general-purpose reasoning tasks, and routing logic. They are the right tool when the output is meant to be read, not executed.

In the WCP ecosystem, AI-SKILL.md files in GitHub repositories form a skill chain for building and releasing WCP widgets and agents. These are classic AI Skills — loaded by URL, consumed by any AI, no packaging required.

AI Skill Packages

An AI Skill Package is a .aiskill file — a ZIP archive that bundles a skill's instructions alongside versioned, unit-tested assets that the AI executes rather than generates.

What a package contains

  • SKILL.md — the entry point: tells the AI what the skill does and how to execute the assets
  • manifest.yaml — machine-readable metadata: identity, version, author, capabilities, permissions
  • assets/ — versioned scripts, templates, data files — anything the skill needs at runtime
  • inputs/ — JSON Schema describing the inputs the skill accepts from the runtime
  • checksums.yaml — SHA-256 integrity hashes for every file in the archive

What makes a package different from a skill

The AI does not write the assets — it executes them. A packaged Python script produces the same output every run, regardless of which AI session is running it or what model version is in use. The unit tests in the package prove this at packaging time.

The key insight. An AI Skill Package moves the computation out of the AI's generation step and into a verified, versioned artifact. The AI becomes the executor, not the author.

Why Packages Matter

Consider asking an AI to write a WCAG contrast-ratio checker. In an ephemeral session, the AI generates a Python snippet on the fly. The snippet may be correct — or it may silently mishandle the gamma-correction step. In a different session, a different version of the model may generate slightly different code. There is no way to know which version was used, no test suite to verify it, and no checksum to confirm the script hasn't changed.

An AI Skill Package solves each of these problems:

ProblemEphemeral AI SkillAI Skill Package
ReproducibilityRe-generated each session — output may varyFixed asset in the archive — identical every run
CorrectnessValidated by human review onlyUnit tests in assets/tests/ — proven at packaging time
IntegrityPrompt can be modified without detectionSHA-256 checksums — any change is detectable
VersioningNo version — the prompt is the promptSemantic version in manifest.yaml, git-tagged
AuditabilitySession log onlyPackage ID + version + checksum = full audit trail

Packages are not a replacement for AI Skills. They are the right tool when the skill's output is executed as code — when correctness, reproducibility, and auditability matter.

Open Standard, Technology-Agnostic

The .aiskill format is an open standard. It makes no assumptions about:

  • AI runtime — Claude, GPT-4, Gemini, local models, or any future agent that can read a ZIP
  • Host platform — macOS, Linux, Windows, container, CI runner
  • Asset language — Python, shell, Node.js, Go, or any language the runtime can execute
  • Distribution channel — local filesystem, GitHub Release, private registry, email attachment

The standard was born in the Widget Context Protocol ecosystem, where the first two production AI Skill Packages — WCP SPA WCP Compliance and WCP SPA Theme Settings — were developed and deployed. However, the format is not WCP-specific. It is applicable to any domain where AI agents execute structured tasks.

No prior art. An exhaustive search at the time of this specification's creation found no prior open standard for AI agent skill packaging with versioning, unit testing, and integrity verification. The .aiskill extension and format are pioneering.

File Structure

A .aiskill file is a standard ZIP archive with a mandatory directory layout. The archive is renamed from .zip to .aiskill after packaging.

my-skill-1.0.0.aiskill (ZIP archive) ├── manifest.yaml # required — identity & metadata ├── SKILL.md # required — AI entry point ├── assets/ # required — versioned execution artifacts │ ├── scripts/ │ │ └── wcag_contrast.py │ └── tests/ │ └── test_wcag_contrast.py ├── inputs/ # optional — runtime input schema │ └── schema.json └── checksums.yaml # required — SHA-256 integrity hashes

Required files

  • manifest.yaml — machine-readable package metadata (see manifest.yaml)
  • SKILL.md — the AI's entry point; instructions for executing the package (see SKILL.md)
  • assets/ — at least one asset file; the execution artifacts of the skill
  • checksums.yaml — SHA-256 hashes of every file in the archive (see checksums.yaml)

Optional directories

  • inputs/ — JSON Schema for runtime-provided inputs (see inputs/ & schema.json)
  • images/ — screenshots or diagrams referenced by SKILL.md
  • docs/ — supplementary documentation for human readers
File naming convention. Package filenames follow the pattern <id>-<version>.aiskill, where id is the last segment of the reverse-domain identifier and version is the semver string. Example: wcag-contrast-audit-1.0.0.aiskill.

manifest.yaml

The manifest.yaml file is the machine-readable identity record for the package. It must be a valid YAML file located at the root of the archive.

Example

name: WCAG Contrast Audit
id: com.widgetcontextprotocol.wcag-contrast-audit
version: 1.0.0
description: Audits colour pairs against WCAG 2.1/2.2 contrast ratios
author: Penrith Beacon
entry: SKILL.md
license: MIT
minimum_runtime: 1.0.0
capabilities:
  - filesystem.read
permissions:
  filesystem.read:
    paths: ["./inputs/", "./assets/"]
homepage: https://aiskill.widgetcontextprotocol.com
repository: https://github.com/penrithbeacon/aiskill-wcag-contrast
authorEmail: hello@penrithbeacon.com
tags: [accessibility, wcag, contrast, audit]
type: analytical

Field summary

FieldTypeDescription
namerequiredstringHuman-readable skill name
idrequiredstringReverse-domain unique identifier, e.g. com.example.skill-name
versionrequiredsemverPackage version following Semantic Versioning 2.0
descriptionrequiredstringOne-line statement of the skill's purpose
authorrequiredstringAuthor name or organisation
entryrequiredstringRelative path to the AI entry point, e.g. SKILL.md
licenserequiredstringSPDX identifier (MIT, Apache-2.0) or Proprietary
minimum_runtimerequiredsemverMinimum AI Skill runtime version required to execute this package
capabilitiesrequiredlistCapability tokens the skill requires (see Capability token registry)
permissionsoptionalobjectCapability-specific permission constraints
homepageoptionalstringCanonical URL for the skill or its documentation
repositoryoptionalstringSource repository URL
authorEmailoptionalstringContact email address
wcpVersionoptionalstringWCP spec version targeted (WCP-specific skills only)
tagsoptionallistDiscovery tags for registries and search
typeoptionalstringprocedural | analytical | generative

See the normative reference table for full field constraints, allowed values, and validation rules.

SKILL.md — The Entry Point

SKILL.md is the first file the AI runtime reads when executing a package. It is a plain Markdown document that tells the AI what the skill does, what assets to execute, and what arguments or inputs to pass.

What SKILL.md must contain

  • A brief description of the skill's purpose
  • Clear instructions for executing each asset (script name, arguments, expected output)
  • Descriptions of all required and optional inputs
  • Expected output format and interpretation guidance

Example

# WCAG Contrast Audit

Execute the script at `assets/scripts/wcag_contrast.py` using the colour pairs
provided by the runtime in `inputs/pairs.csv`.

## Execution

```bash
python3 assets/scripts/wcag_contrast.py \
  --input inputs/pairs.csv \
  --level AA \
  --output table
```

## Arguments

| Argument   | Default          | Description                                  |
|------------|------------------|----------------------------------------------|
| `--input`  | `inputs/pairs.csv` | Path to CSV of hex colour pairs            |
| `--level`  | `AA`             | WCAG level: `AA` or `AAA`                   |
| `--output` | `table`          | Output format: `table` | `json` | `csv`    |

## Expected Output

A table showing each pair's contrast ratio, WCAG level status
(Pass/Fail for normal and large text), and EAA compliance status.
SKILL.md vs the asset. SKILL.md contains instructions for the AI; the asset contains the computation. The AI reads SKILL.md to understand what to do, then executes the asset file exactly as written — it does not rewrite or regenerate the asset.

assets/ — Versioned Execution Artifacts

The assets/ directory contains all files the skill executes at runtime. These files are fixed at package creation time — the AI runtime executes them as-is, without modification.

Supported asset types

TypeExamplesNotes
Scripts.py, .sh, .js, .rb, .goPrimary execution artifacts
Teststest_*.py, *.test.jsUnit tests; proved at packaging time
Templates.html, .md, .jinjaContent templates injected by scripts
Data.json, .yaml, .csvReference data consumed by scripts
Config.toml, .ini, .env.exampleConfiguration files for packaged tools
Documentation.md, .txtSupplementary human-readable docs
Images.png, .jpg, .svgScreenshots, diagrams referenced by SKILL.md

Recommended sub-directory layout

assets/
├── scripts/       # executable scripts
├── tests/         # unit tests for the scripts
├── templates/     # content templates
└── data/          # reference data
No binary executables. Assets must be source files or data — not compiled binaries. The runtime is responsible for providing the language interpreter (Python, Node.js, etc.). Binaries cannot be integrity-verified across platforms and are explicitly excluded from the .aiskill format.

inputs/ & schema.json

The optional inputs/ directory defines the runtime-provided inputs the skill expects. When present, the directory must contain a schema.json file in JSON Schema (Draft-07 or later) format.

schema.json

The schema describes the inputs object the AI runtime must supply before executing the skill. The runtime validates the inputs against this schema before passing them to the asset scripts.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["pairs"],
  "properties": {
    "pairs": {
      "type": "string",
      "description": "Path to a CSV file containing hex colour pairs",
      "format": "uri-reference"
    },
    "level": {
      "type": "string",
      "enum": ["AA", "AAA"],
      "default": "AA",
      "description": "WCAG conformance level to test against"
    }
  }
}

Runtime input file

When inputs are provided by the runtime, they are written to the inputs/ directory before skill execution. The AI reads SKILL.md for instructions on how to locate and pass the input files to the asset scripts.

checksums.yaml — Integrity Verification

checksums.yaml contains SHA-256 hashes of every file in the archive (except itself). The AI runtime verifies all checksums before executing any asset. If any hash fails, execution is aborted.

Format

algorithm: sha256
files:
  manifest.yaml: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  SKILL.md: "a1b2c3d4e5f6..."
  assets/scripts/wcag_contrast.py: "7f8e9d0c1b2a..."
  assets/tests/test_wcag_contrast.py: "3d4e5f6a7b8c..."
  inputs/schema.json: "9a0b1c2d3e4f..."

Generating checksums

# Python — generate checksums.yaml
import hashlib, yaml
from pathlib import Path

files = {}
for p in Path('.').rglob('*'):
    if p.is_file() and p.name != 'checksums.yaml':
        files[str(p)] = hashlib.sha256(p.read_bytes()).hexdigest()

Path('checksums.yaml').write_text(
    yaml.dump({'algorithm': 'sha256', 'files': files}, sort_keys=True)
)
Trust chain starts here. Checksums bind the package version to a known set of file contents. Combined with a git tag on the source repository, this creates a verifiable audit trail: version → tag → source → checksums → archive.

Ephemerality

Every AI session is a blank slate. The AI has no memory of previous sessions unless you provide that context explicitly. This is the fundamental property of ephemerality — and it is why packaging exists.

Ephemeral AI Skills

When you ask an AI to write a Python function, it writes that function in the current session. In the next session, asked the same question, it writes the function again — possibly differently. The output is a product of the model version, the session context, the random seed, and the exact phrasing of your prompt. None of these are fixed.

For many tasks, this is fine. If you are asking the AI to explain a concept, draft a document, or suggest an architecture, non-determinism is acceptable — even desirable. But if you are asking the AI to compute something that must be correct and reproducible, ephemerality becomes a liability.

Persistent AI Skill Packages

A package removes the AI from the computation path. The script in assets/scripts/ was written once, tested, and frozen into the archive. The AI's role at runtime is to locate the script and execute it — not to rewrite it. The computation is deterministic. The result is the same in every session, on every machine, for every model version.

The ephemerality boundary. SKILL.md (the instructions) can be updated between package versions. The assets (the computation) are fixed within a version. Versioning is how the package evolves without losing reproducibility.

Deterministic Computation

Determinism means that given the same inputs, a computation always produces the same output. It is the foundational property that makes software testable, auditable, and trustworthy.

AI-generated code is not inherently deterministic across sessions. The same prompt may produce subtly different implementations. A computation that appears correct in one session may have silent edge-case bugs that appear in another. Without unit tests, there is no way to know.

How packages enforce determinism

  1. Fixed assets — the script is written once and checksummed into the archive. It cannot change between executions without a new package version.
  2. Unit testsassets/tests/ contains tests that prove the script produces correct output for known inputs. These tests pass before the package is released.
  3. Integrity verificationchecksums.yaml ensures the script that was tested is the script that runs. Any tampering is detected before execution.
  4. Semantic versioning — when the script changes, the version number changes. Consumers can pin to a specific version and get reproducible behaviour.
Determinism and the AI's role. The AI runtime reads SKILL.md to understand what to do, then executes the asset. It does not regenerate the asset. This separation means the AI's inherent non-determinism is confined to the orchestration layer, not the computation layer.

WCAG Contrast: The Canonical Determinism Example

The WCAG contrast ratio is the clearest demonstration of why deterministic packaging matters. It is a pure mathematical function — an algorithm defined in the W3C specification with no ambiguity. Yet an AI asked to implement it from scratch in different sessions may produce subtly different code, particularly around the gamma-correction step.

The mathematics

The contrast ratio between two colours is defined by WCAG 2.1 and 2.2 as:

# Step 1 — linearise each sRGB channel (gamma correction)
def srgb_to_linear(c: float) -> float:
    c /= 255.0
    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4

# Step 2 — relative luminance  (WCAG formula)
def relative_luminance(r: int, g: int, b: int) -> float:
    return (0.2126 * srgb_to_linear(r)
          + 0.7152 * srgb_to_linear(g)
          + 0.0722 * srgb_to_linear(b))

# Step 3 — contrast ratio
def contrast_ratio(rgb1: tuple, rgb2: tuple) -> float:
    l1 = relative_luminance(*rgb1)
    l2 = relative_luminance(*rgb2)
    lighter, darker = max(l1, l2), min(l1, l2)
    return (lighter + 0.05) / (darker + 0.05)

# Step 4 — WCAG level classification
def wcag_level(ratio: float) -> str:
    if ratio >= 7.0:  return "AAA — normal & large text"
    if ratio >= 4.5:  return "AA  — normal & large text"
    if ratio >= 3.0:  return "AA  — large text only"
    return "Fail"

WCAG conformance levels

LevelNormal text (≥18pt or ≥14pt bold)Large text (<18pt and <14pt bold)
AA4.5 : 1 minimum3.0 : 1 minimum
AAA7.0 : 1 minimum4.5 : 1 minimum

European Accessibility Act (EAA)

The European Accessibility Act entered force on 28 June 2025, mandating WCAG 2.1 Level AA compliance for all digital services offered in EU member states. The harmonised European standard is EN 301 549 v3.2.1.

For products and services in scope, the WCAG contrast requirements are now a legal obligation, not a best practice. A packaged, unit-tested WCAG contrast checker — distributed as a .aiskill file — provides a repeatable, auditable compliance verification tool that can be cited in accessibility reports.

Why this is the canonical example

The gamma-correction step (((c + 0.055) / 1.055) ** 2.4) is where AI-generated implementations diverge. A simplified linearisation (c / 255.0) passes obvious test cases but fails on mid-range colours. A packaged script with unit tests covering known colour pairs — including the boundary cases at 3.0:1 and 4.5:1 — proves correctness in a way that ephemeral generation cannot.

# Unit tests shipped in assets/tests/test_wcag_contrast.py
import pytest
from scripts.wcag_contrast import contrast_ratio, wcag_level

def test_black_on_white():
    assert round(contrast_ratio((0,0,0), (255,255,255)), 2) == 21.0

def test_wcag_aa_boundary():
    # #767676 on white is exactly AA compliant at 4.48:1
    ratio = contrast_ratio((118,118,118), (255,255,255))
    assert ratio >= 4.5 - 0.05  # within rounding of the AA threshold

def test_eaa_compliant_pair():
    # Dark blue on white: 8.59:1 — AAA compliant
    ratio = contrast_ratio((0,70,127), (255,255,255))
    assert ratio >= 7.0

def test_fail_case():
    # Light grey on white: 1.6:1 — Fail
    assert wcag_level(1.6) == "Fail"

Trust Chain

A .aiskill package establishes a trust chain — a verifiable sequence linking a version identifier to a known set of file contents.

LayerArtifactWhat it proves
SourceGit repository + tagsThe history and authorship of the assets
Versionmanifest.yaml version fieldA specific, named point in the package's lifecycle
Archive.aiskill ZIP fileThe exact set of files distributed to the runtime
Integritychecksums.yamlThat no file has been modified since the package was built
CorrectnessUnit tests in assets/tests/That the assets produce correct output for known inputs

When the AI runtime receives a .aiskill file, it:

  1. Extracts the archive
  2. Reads checksums.yaml and verifies every file's SHA-256 hash
  3. Reads manifest.yaml to confirm the package identity and required capabilities
  4. Reads SKILL.md for execution instructions
  5. Executes the assets according to those instructions

If step 2 fails — any hash mismatch — execution is aborted. The trust chain is broken and the runtime must not proceed.

Trust chain is one-way. Checksums prove the archive matches what was packaged. They do not prove the assets were written correctly — that is the job of unit tests, which must pass before packaging.

Create Your First .aiskill Package

This tutorial walks through creating a minimal .aiskill package from scratch. The example skill computes file sizes for a directory listing — simple enough to follow in full, complete enough to be a real working package.

Step 1

Create the directory structure

mkdir -p my-skill/assets/scripts my-skill/assets/tests my-skill/inputs
cd my-skill
Step 2

Write the asset script

Create assets/scripts/dir_sizes.py:

#!/usr/bin/env python3
"""List files in a directory with their sizes in human-readable format."""
import argparse, os, sys
from pathlib import Path

def human_size(n: int) -> str:
    for unit in ['B','KB','MB','GB']:
        if n < 1024: return f"{n:.1f} {unit}"
        n /= 1024
    return f"{n:.1f} TB"

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument('--path', required=True)
    ap.add_argument('--sort', choices=['name','size'], default='name')
    args = ap.parse_args()

    entries = [(p.name, p.stat().st_size) for p in Path(args.path).iterdir() if p.is_file()]
    entries.sort(key=lambda x: x[1] if args.sort == 'size' else x[0])

    for name, size in entries:
        print(f"{human_size(size):>10}  {name}")

if __name__ == '__main__':
    main()
Step 3

Write unit tests

Create assets/tests/test_dir_sizes.py:

import sys; sys.path.insert(0, 'assets/scripts')
from dir_sizes import human_size

def test_bytes():    assert human_size(500) == "500.0 B"
def test_kilobytes(): assert human_size(2048) == "2.0 KB"
def test_megabytes(): assert human_size(1_048_576) == "1.0 MB"
# Run tests — they must pass before you package
python3 -m pytest assets/tests/ -v
Step 4

Write the input schema

Create inputs/schema.json:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["path"],
  "properties": {
    "path": { "type": "string", "description": "Directory path to list" },
    "sort": { "type": "string", "enum": ["name", "size"], "default": "name" }
  }
}
Step 5

Write SKILL.md

# Directory Size Lister

Execute `assets/scripts/dir_sizes.py` with the path provided by the runtime.

## Execution

```bash
python3 assets/scripts/dir_sizes.py --path <inputs.path> --sort <inputs.sort>
```

## Output

One line per file: human-readable size followed by filename, sorted by name or size.
Step 6

Write manifest.yaml

name: Directory Size Lister
id: com.example.dir-sizes
version: 1.0.0
description: Lists files in a directory with human-readable sizes
author: Your Name
entry: SKILL.md
license: MIT
minimum_runtime: 1.0.0
capabilities:
  - filesystem.read
permissions:
  filesystem.read:
    paths: ["./inputs/"]
tags: [filesystem, utility]
type: analytical
Step 7

Generate checksums and package

# Generate checksums.yaml
python3 - <<'EOF'
import hashlib, yaml
from pathlib import Path

files = {}
for p in sorted(Path('.').rglob('*')):
    if p.is_file() and p.name != 'checksums.yaml':
        rel = str(p.relative_to('.'))
        files[rel] = hashlib.sha256(p.read_bytes()).hexdigest()

Path('checksums.yaml').write_text(
    yaml.dump({'algorithm': 'sha256', 'files': files}, sort_keys=True)
)
print(f"Checksummed {len(files)} files.")
EOF

# Create the .aiskill archive
cd ..
zip -r dir-sizes-1.0.0.aiskill my-skill/
mv dir-sizes-1.0.0.aiskill dir-sizes-1.0.0.aiskill  # already named correctly
echo "Package ready: dir-sizes-1.0.0.aiskill"
Your first package is ready. The .aiskill file is self-contained. Give it to any AI runtime that supports the format and it will: verify checksums, read SKILL.md, and execute dir_sizes.py — every time, identically.

Worked Example: WCAG Contrast Audit Package

This is a complete walkthrough of the WCAG contrast audit package — the canonical .aiskill example. The full source is referenced in WCAG contrast: the canonical determinism example.

Package identity

FieldValue
nameWCAG Contrast Audit
idcom.widgetcontextprotocol.wcag-contrast-audit
version1.0.0
typeanalytical
licenseMIT
capabilitiesfilesystem.read

Archive layout

wcag-contrast-audit-1.0.0.aiskill ├── manifest.yaml ├── SKILL.md ├── assets/ │ ├── scripts/ │ │ └── wcag_contrast.py # 87 lines │ └── tests/ │ └── test_wcag_contrast.py # 24 lines, 6 test cases ├── inputs/ │ └── schema.json └── checksums.yaml

Runtime invocation

An AI runtime receives this package and a CSV file of colour pairs. The runtime:

  1. Verifies all 6 checksums from checksums.yaml
  2. Reads manifest.yaml — confirms filesystem.read capability and permission scope
  3. Reads SKILL.md — learns to run wcag_contrast.py --input inputs/pairs.csv --level AA
  4. Executes the script — identical output to every other session with the same inputs
  5. Returns the result table to the user

Sample input CSV

foreground,background,context
#1f2328,#ffffff,Body text
#636c76,#ffffff,Secondary text
#0969da,#ffffff,Link
#1a7f37,#ffffff,Success badge
#9a6700,#ffffff,Warning badge
#cf222e,#ffffff,Error text

Sample output

Foreground  Background  Ratio   Level                    Context
#1f2328     #ffffff     16.75:1  AAA — normal & large    Body text
#636c76     #ffffff     5.74:1   AA  — normal & large    Secondary text
#0969da     #ffffff     4.63:1   AA  — normal & large    Link
#1a7f37     #ffffff     5.94:1   AA  — normal & large    Success badge
#9a6700     #ffffff     3.03:1   AA  — large text only   Warning badge  ⚠
#cf222e     #ffffff     5.12:1   AA  — normal & large    Error text

EAA status: 5 of 6 pairs meet WCAG 2.1 AA. Warning badge requires review.
The warning badge case. #9a6700 on white yields 3.03:1 — passing only for large text. This is a real edge case that an AI generating the checker fresh each session might handle inconsistently. The packaged test suite covers this boundary explicitly.

Real-World Example: WCP SPA WCP Compliance

The WCP SPA WCP Compliance package upgrades an existing WCP Single-Page Application to full Widget Context Protocol compliance. It is a pure instruction skill — no Python, no shell scripts — just structured Markdown templates and a token-mapping reference that the AI follows step by step.

Archive layout

wcp-spa-wcp-compliance-1.2.0.aiskill (ZIP, ~12 KB) ├── manifest.yaml ├── SKILL.md ├── assets/ │ └── instructions/ │ ├── 01-audit.md # audit checklist for the AI │ ├── 02-token-mapping.md # bespoke var → WCP token map │ ├── 03-injection-guide.md # WCP runtime script injection │ └── template-wcp-root.html # canonical 81-token :root block └── checksums.yaml

What the package does

The AI executes the package against a target WCP SPA's index.html:

  1. Audit — reads 01-audit.md; scans the target file for non-WCP CSS variables and bespoke colour values
  2. Token mapping — uses 02-token-mapping.md to map each bespoke variable to its canonical --wcp-* equivalent
  3. Replace — substitutes all bespoke variables in the target file with WCP tokens; removes any leftover bespoke :root declarations
  4. Inject runtime — follows 03-injection-guide.md to insert the WCP theme runtime <script> before </head>
  5. Insert :root — inserts the canonical 81-token :root block from template-wcp-root.html as the first rule in <style>

The package contains no executable scripts. The AI itself performs the file edits, guided entirely by the instruction assets. This is a procedural AI Skill Package — the assets guide the computation rather than executing it independently.

Why package pure instructions? The token-mapping table and canonical :root block are versioned artifacts. If the WCP spec adds new tokens in v1.1, a new package version is released. Every site that ran v1.0 can be re-audited with v1.1 without relying on the AI to remember the change.

manifest.yaml (key fields)

name: WCP SPA WCP Compliance
id: com.widgetcontextprotocol.wcp-spa-compliance
version: 1.2.0
type: procedural
capabilities:
  - filesystem.read
  - filesystem.write
permissions:
  filesystem.write:
    paths: ["./target/"]   # runtime supplies the target SPA path here

Real-World Example: WCP SPA Theme Settings

The WCP SPA Theme Settings package integrates a full theme management system — modal UI, seasonal .wcpt collections, URL export, and the WCP theme engine — into any WCP-compliant SPA. It is the most feature-complete production AI Skill Package in the WCP ecosystem.

Archive layout

wcp-spa-theme-settings-2.1.0.aiskill (ZIP, ~94 KB) ├── manifest.yaml ├── SKILL.md ├── assets/ │ ├── js/ │ │ ├── theme-engine.js # _wcpTheme IIFE — localStorage + sessionStorage │ │ └── theme-controller.js # modal open/close, list render, import/export │ ├── html/ │ │ └── modal-template.html # complete modal HTML block │ ├── css/ │ │ └── modal-styles.css # modal CSS (namespaced wcp-theme-*) │ └── themes/ │ ├── seasons-spring.wcpt │ ├── seasons-summer.wcpt │ ├── seasons-autumn.wcpt │ └── seasons-winter.wcpt ├── images/ │ ├── DarkTheme.png # screenshot — dark theme active │ └── LightTheme.png # screenshot — light theme active └── checksums.yaml

The 11 integration steps

SKILL.md instructs the AI to apply the package to the target SPA in 11 steps:

  1. Add JSZip CDN <script> to <head> (required for .wcpt file import)
  2. Add gear button to the topbar's .topbar-right nav
  3. Copy modal CSS from assets/css/modal-styles.css into the page's <style> block
  4. Insert modal HTML from assets/html/modal-template.html before </body>
  5. Insert theme engine JS from assets/js/theme-engine.js before </body>
  6. Insert theme controller JS from assets/js/theme-controller.js before </body>
  7. Copy the four .wcpt files from assets/themes/ to the target SPA's src/themes/
  8. Wire the seasonal loader buttons to the wcpLoadSeasonal(name) function
  9. Configure the URL export panel with the target site's origin
  10. Add the WCP compliance badge to the page footer
  11. Verify: open the gear icon, switch themes, import a .wcpt file, confirm all --wcp-* tokens respond

Screenshots

AI Skill Package site — dark theme active AI Skill Package site — light theme active
Meta note. This website — the AI Skill Package Specification — was itself built using the WCP SPA Theme Settings package it describes. The gear icon in the topbar is the result of applying step 2; the seasonal theme collections are the result of step 7; this callout is WCP-compliant because of steps 3 and 5.

manifest.yaml (key fields)

name: WCP SPA Theme Settings
id: com.widgetcontextprotocol.wcp-spa-theme-settings
version: 2.1.0
type: procedural
capabilities:
  - filesystem.read
  - filesystem.write
wcpVersion: "1.0"
tags: [wcp, theme, spa, modal, wcpt, seasonal]

Use Cases: Software Engineering

Any software engineering task that involves executing a defined algorithm against a codebase or file set is a candidate for .aiskill packaging. The defining characteristic: the computation must produce the same result every run given the same inputs.

Use caseWhat the package contains
Code quality audit A Python script wrapping linting tools (pylint, eslint) with a normalised report format; unit tests on known-bad code samples
CSS token migration A regex-based token-replacement script and a mapping table; test fixtures proving no tokens are missed or double-replaced
API contract validation A script that compares an OpenAPI spec against a live endpoint's responses; test cases covering missing fields and wrong types
Dependency graph analysis A script that parses package.json / requirements.txt and flags known-vulnerable or outdated packages
Security vulnerability scan A script that runs static analysis tools and formats findings as a structured report; test cases on known-vulnerable snippets
File tree audit A script that validates repository structure against a required-file manifest; unit tests for common missing-file patterns

In each case the value is the same: the AI does not rewrite the analyser each session. It executes a tested, versioned tool that produces consistent, auditable output.

Use Cases: Accessibility & Standards Compliance

Standards compliance is the ideal domain for AI Skill Packages. Standards are precise, stable, and algorithmically verifiable. The computation is deterministic by definition.

Use caseStandard / requirement
WCAG contrast audit WCAG 2.1/2.2 AA + AAA; EAA (EU, from 28 Jun 2025); EN 301 549 v3.2.1
ARIA landmark validation WAI-ARIA 1.2 — verifies required roles (banner, main, navigation) are present and correctly nested
Keyboard navigation testing Scripted tab-order extraction; test that all interactive elements are reachable without a mouse
Colour-blindness simulation report A Python script using colour transform matrices to simulate deuteranopia / protanopia; outputs a contrast table for the simulated palette
Focus indicator audit CSS parser that verifies :focus styles are not suppressed (outline: none without replacement)
Alt text coverage HTML parser counting <img> tags without alt attributes; outputs a report with file locations
Compliance reporting. Because each package run is deterministic and checksummed, the output of an accessibility audit can be cited in a compliance report with a specific package version. The report is reproducible — the same package on the same HTML file will always produce the same findings.

Use Cases: Beyond Software Engineering

The .aiskill format is not limited to code. Any domain where an AI agent performs a structured, repeatable task with verifiable outputs is a candidate.

Web & publishing

  • SEO audit — a script that parses HTML for missing <title>, <meta description>, Open Graph tags, and canonical links
  • Broken link detection — an async Python script that crawls a site and reports 4xx/5xx responses
  • Document formatting pipeline — a Pandoc-based script that converts Markdown to PDF, DOCX, and EPUB from a single source
  • Multi-language localisation QA — a script that compares translation files against a source locale and flags missing or extra keys

Data & databases

  • Schema migration validation — a script that applies a migration in a sandbox and verifies the resulting schema against an expected definition
  • Data integrity audit — a script that checks referential integrity, null constraints, and format consistency across a dataset
  • Hobby collection database population — a structured data-entry pipeline with validation rules for a specific collection domain (stamps, coins, records, etc.)

Research & content

  • Citation consistency check — a script that parses a bibliography and flags duplicate or malformed citations
  • Bibliography formatter — a script that normalises references to a chosen citation style (APA, MLA, Chicago)
  • Data extraction from PDFs — a pdfminer-based script that extracts structured data from a known document format

File systems & archives

  • Archive inventory — a script that walks a directory tree and produces a manifest CSV with name, size, type, and checksum
  • Duplicate detection — a script that groups files by SHA-256 hash and reports duplicates
  • Backup verification — a script that compares a backup archive against a source manifest and reports any discrepancies
The common thread. In every use case, the skill is an algorithm — not a conversation. The AI Skill Package format is the right tool whenever you want the same computation to run the same way, every time, across any session, model, or machine.

Reference: manifest.yaml Fields (Normative)

FieldRequiredTypeConstraintsDescription
name string 1–128 chars Human-readable display name
id string Reverse-domain, lowercase, dots & hyphens only. E.g. com.example.skill-name Globally unique package identifier
version string Semantic Versioning 2.0.0. Pre-release: 1.0.0-beta Package version
description string 1–256 chars, plain text One-line purpose statement
author string 1–128 chars Author name or organisation
entry string Relative path; file must exist in archive Path to the AI entry point (typically SKILL.md)
license string SPDX identifier or Proprietary Distribution license
minimum_runtime string Semver; runtime must satisfy >= this version Minimum AI Skill runtime version
capabilities list[string] Must be tokens from the capability registry Required capabilities the runtime must grant
permissions object Keys are capability tokens; values are capability-specific objects Scoped permission constraints per capability
homepage string Valid URL Canonical URL for the skill or its specification
repository string Valid URL Source repository (GitHub, GitLab, etc.)
authorEmail string Valid email address Contact address for the package author
wcpVersion string WCP spec version string, e.g. "1.0" Only for skills that target the WCP ecosystem
tags list[string] Lowercase, hyphens allowed, max 20 tags Discovery tags for search and registries
type string procedural | analytical | generative Skill type — informs runtime and tooling how to handle execution

Skill type values

ValueDescriptionExample
proceduralThe AI follows step-by-step instructions; assets guide the processWCP SPA Compliance, Theme Settings integration
analyticalA script computes a result from input data; output is deterministicWCAG contrast audit, dependency analysis
generativeAssets provide structure and constraints; the AI generates content within themDocument templates, report scaffolds

Reference: Capability Token Registry

Capability tokens declare what resources a package requires the runtime to grant. The runtime must verify it can satisfy all declared capabilities before executing the package.

TokenDescriptionPermission fields
filesystem.read Read files from the local filesystem paths — list of allowed path prefixes
filesystem.write Write or modify files on the local filesystem paths — list of allowed path prefixes
filesystem.execute Execute scripts or shell commands interpreters — list of allowed interpreters (e.g. python3, bash)
network.fetch Make outbound HTTP/HTTPS requests domains — list of allowed domain patterns
network.listen Bind to a local port and accept connections ports — list of allowed port numbers
runtime.env Read environment variables keys — list of allowed variable names
runtime.subprocess Spawn child processes commands — list of allowed command names
clipboard.read Read the system clipboard — (no permission sub-fields)
clipboard.write Write to the system clipboard — (no permission sub-fields)
Least-privilege principle. Declare only the capabilities the skill actually requires. Runtimes may refuse packages that request capabilities disproportionate to the declared task. Each capability should be paired with the narrowest possible permissions scope.

Reference: MIME Type & File Association

MIME type

PropertyValue
MIME typeapplication/vnd.aiskill+zip
File extension.aiskill
Underlying formatZIP (PKZIP-compatible; deflate or store compression)
EncodingBinary; not base64-encoded at the file level
Magic bytes50 4B 03 04 (standard ZIP local file header)

macOS file association

<!-- Info.plist entry for a macOS app that opens .aiskill files -->
<key>CFBundleDocumentTypes</key>
<array>
  <dict>
    <key>CFBundleTypeName</key>         <string>AI Skill Package</string>
    <key>CFBundleTypeExtensions</key>   <array><string>aiskill</string></array>
    <key>CFBundleTypeMIMETypes</key>    <array><string>application/vnd.aiskill+zip</string></array>
    <key>CFBundleTypeRole</key>         <string>Viewer</string>
  </dict>
</array>

HTTP content-type header

Content-Type: application/vnd.aiskill+zip
Content-Disposition: attachment; filename="wcag-contrast-audit-1.0.0.aiskill"

Filename convention

Package filenames should follow the pattern: <short-id>-<version>.aiskill

Where short-id is the last segment of the reverse-domain identifier (e.g. wcag-contrast-audit from com.example.wcag-contrast-audit) and version is the full semver string.

wcag-contrast-audit-1.0.0.aiskill       # stable release
wcag-contrast-audit-1.1.0-beta.aiskill  # pre-release
dir-sizes-1.0.0.aiskill                 # different package

Theme Settings


Import from URL or paste base64 — or choose a .wcpt file