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.
.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
.aiskillZIP layout and all required/optional files - The normative
manifest.yamlfield reference - The determinism principle and why it matters for AI-executed computation
- Step-by-step tutorial for creating your first
.aiskillpackage - 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.
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.
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:
| Problem | Ephemeral AI Skill | AI Skill Package |
|---|---|---|
| Reproducibility | Re-generated each session — output may vary | Fixed asset in the archive — identical every run |
| Correctness | Validated by human review only | Unit tests in assets/tests/ — proven at packaging time |
| Integrity | Prompt can be modified without detection | SHA-256 checksums — any change is detectable |
| Versioning | No version — the prompt is the prompt | Semantic version in manifest.yaml, git-tagged |
| Auditability | Session log only | Package 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.
.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.
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 skillchecksums.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 bySKILL.mddocs/— supplementary documentation for human readers
<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
| Field | Type | Description | |
|---|---|---|---|
| name | required | string | Human-readable skill name |
| id | required | string | Reverse-domain unique identifier, e.g. com.example.skill-name |
| version | required | semver | Package version following Semantic Versioning 2.0 |
| description | required | string | One-line statement of the skill's purpose |
| author | required | string | Author name or organisation |
| entry | required | string | Relative path to the AI entry point, e.g. SKILL.md |
| license | required | string | SPDX identifier (MIT, Apache-2.0) or Proprietary |
| minimum_runtime | required | semver | Minimum AI Skill runtime version required to execute this package |
| capabilities | required | list | Capability tokens the skill requires (see Capability token registry) |
| permissions | optional | object | Capability-specific permission constraints |
| homepage | optional | string | Canonical URL for the skill or its documentation |
| repository | optional | string | Source repository URL |
| authorEmail | optional | string | Contact email address |
| wcpVersion | optional | string | WCP spec version targeted (WCP-specific skills only) |
| tags | optional | list | Discovery tags for registries and search |
| type | optional | string | procedural | 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.
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
| Type | Examples | Notes |
|---|---|---|
| Scripts | .py, .sh, .js, .rb, .go | Primary execution artifacts |
| Tests | test_*.py, *.test.js | Unit tests; proved at packaging time |
| Templates | .html, .md, .jinja | Content templates injected by scripts |
| Data | .json, .yaml, .csv | Reference data consumed by scripts |
| Config | .toml, .ini, .env.example | Configuration files for packaged tools |
| Documentation | .md, .txt | Supplementary human-readable docs |
| Images | .png, .jpg, .svg | Screenshots, 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
.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)
)
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.
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
- Fixed assets — the script is written once and checksummed into the archive. It cannot change between executions without a new package version.
- Unit tests —
assets/tests/contains tests that prove the script produces correct output for known inputs. These tests pass before the package is released. - Integrity verification —
checksums.yamlensures the script that was tested is the script that runs. Any tampering is detected before execution. - Semantic versioning — when the script changes, the version number changes. Consumers can pin to a specific version and get reproducible behaviour.
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
| Level | Normal text (≥18pt or ≥14pt bold) | Large text (<18pt and <14pt bold) |
|---|---|---|
| AA | 4.5 : 1 minimum | 3.0 : 1 minimum |
| AAA | 7.0 : 1 minimum | 4.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.
| Layer | Artifact | What it proves |
|---|---|---|
| Source | Git repository + tags | The history and authorship of the assets |
| Version | manifest.yaml version field | A specific, named point in the package's lifecycle |
| Archive | .aiskill ZIP file | The exact set of files distributed to the runtime |
| Integrity | checksums.yaml | That no file has been modified since the package was built |
| Correctness | Unit tests in assets/tests/ | That the assets produce correct output for known inputs |
When the AI runtime receives a .aiskill file, it:
- Extracts the archive
- Reads
checksums.yamland verifies every file's SHA-256 hash - Reads
manifest.yamlto confirm the package identity and required capabilities - Reads
SKILL.mdfor execution instructions - 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.
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.
Create the directory structure
mkdir -p my-skill/assets/scripts my-skill/assets/tests my-skill/inputs
cd my-skill
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()
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
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" }
}
}
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.
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
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"
.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
| Field | Value |
|---|---|
| name | WCAG Contrast Audit |
| id | com.widgetcontextprotocol.wcag-contrast-audit |
| version | 1.0.0 |
| type | analytical |
| license | MIT |
| capabilities | filesystem.read |
Archive layout
Runtime invocation
An AI runtime receives this package and a CSV file of colour pairs. The runtime:
- Verifies all 6 checksums from
checksums.yaml - Reads
manifest.yaml— confirmsfilesystem.readcapability and permission scope - Reads
SKILL.md— learns to runwcag_contrast.py --input inputs/pairs.csv --level AA - Executes the script — identical output to every other session with the same inputs
- 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.
#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
What the package does
The AI executes the package against a target WCP SPA's index.html:
- Audit — reads
01-audit.md; scans the target file for non-WCP CSS variables and bespoke colour values - Token mapping — uses
02-token-mapping.mdto map each bespoke variable to its canonical--wcp-*equivalent - Replace — substitutes all bespoke variables in the target file with WCP tokens; removes any leftover bespoke
:rootdeclarations - Inject runtime — follows
03-injection-guide.mdto insert the WCP theme runtime<script>before</head> - Insert :root — inserts the canonical 81-token
:rootblock fromtemplate-wcp-root.htmlas 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.
: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
The 11 integration steps
SKILL.md instructs the AI to apply the package to the target SPA in 11 steps:
- Add JSZip CDN
<script>to<head>(required for.wcptfile import) - Add gear button to the topbar's
.topbar-rightnav - Copy modal CSS from
assets/css/modal-styles.cssinto the page's<style>block - Insert modal HTML from
assets/html/modal-template.htmlbefore</body> - Insert theme engine JS from
assets/js/theme-engine.jsbefore</body> - Insert theme controller JS from
assets/js/theme-controller.jsbefore</body> - Copy the four
.wcptfiles fromassets/themes/to the target SPA'ssrc/themes/ - Wire the seasonal loader buttons to the
wcpLoadSeasonal(name)function - Configure the URL export panel with the target site's origin
- Add the WCP compliance badge to the page footer
- Verify: open the gear icon, switch themes, import a
.wcptfile, confirm all--wcp-*tokens respond
Screenshots
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 case | What 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 case | Standard / 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 |
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
Reference: manifest.yaml Fields (Normative)
| Field | Required | Type | Constraints | Description |
|---|---|---|---|---|
| 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
| Value | Description | Example |
|---|---|---|
| procedural | The AI follows step-by-step instructions; assets guide the process | WCP SPA Compliance, Theme Settings integration |
| analytical | A script computes a result from input data; output is deterministic | WCAG contrast audit, dependency analysis |
| generative | Assets provide structure and constraints; the AI generates content within them | Document 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.
| Token | Description | Permission 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) |
permissions scope.
Reference: MIME Type & File Association
MIME type
| Property | Value |
|---|---|
| MIME type | application/vnd.aiskill+zip |
| File extension | .aiskill |
| Underlying format | ZIP (PKZIP-compatible; deflate or store compression) |
| Encoding | Binary; not base64-encoded at the file level |
| Magic bytes | 50 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