此技术文档暂仅提供英文版。以下内容为权威原文。

The .aiskill specification (v1)

.aiskill is a portable, platform-neutral packaging of an AI agent skill: the prompts, the variables they accept, and the metadata needed to install and trust it. It is plain JSON (or its 1:1 YAML twin) with a format: aiskill/v1 envelope.

Design principles

No inference required. A skill is pure configuration — no API keys, no model calls, no side effects.
Human-readable first. Everything is plain text you can read, diff and audit.
Platform-neutral. One file imports into GPTs, Claude Code, Cursor, Dify and LangGraph.
Versioned. Semantic versions plus a tested_environment so you know what a skill has run on.

Complete example

spec-example.aiskill

{
  "format": "aiskill/v1",
  "skill": {
    "name": "Code Review Assistant",
    "slug": "code-review-assistant",
    "version": "1.2.0",
    "description": "Senior-engineer review pass ranked by severity.",
    "category": "Development",
    "tags": ["code-review", "security"],
    "platforms": ["chatgpt", "claude-code", "cursor", "dify"],
    "tested_environment": "GPT-5, Claude Sonnet 4.5",
    "license": "CC-BY-4.0"
  },
  "prompts": {
    "system": "You are a staff-level engineer…",
    "user_template": "Review the following {{language}} code…"
  },
  "variables": [
    {
      "name": "language",
      "description": "Primary language of the code.",
      "required": true,
      "example": "TypeScript"
    }
  ],
  "install": {
    "steps": [{ "title": "Copy the system prompt", "detail": "…" }]
  },
  "usage": {
    "steps": ["Paste the code you want reviewed…"]
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.dev/skills/code-review-assistant",
    "exported_at": "2026-10-22T00:00:00.000Z"
  }
}

Field reference

Field	Type	Required	Description
format	string	Yes	Must be "aiskill/v1".
skill.name	string	Yes	Human-readable skill name.
skill.slug	string	Yes	Lowercase kebab-case unique id: ^[a-z0-9]+(-[a-z0-9]+)*$.
skill.version	string	Yes	Semantic version (MAJOR.MINOR.PATCH).
skill.description	string	Yes	One-two sentence summary.
skill.category	string	Yes	One of the eight SkillVault categories.
skill.tags	string[]	No	Discovery tags, lowercase kebab-case.
skill.platforms	string[]	Yes	At least one of: chatgpt, claude-code, cursor, dify, langgraph.
skill.tested_environment	string	No	Models / versions the skill was validated on.
skill.license	string	No	SPDX identifier; SkillVault skills default to CC-BY-4.0.
prompts.system	string	Yes	System prompt defining role, rules and output format.
prompts.user_template	string	Yes	User message template with {{variable}} placeholders.
variables[].name	string	Yes	Placeholder name, matches [a-zA-Z0-9_-]+.
variables[].description	string	Yes	What the variable should contain.
variables[].required	boolean	No	Defaults to false.
variables[].example	string	No	Sample value.
install.steps[].title/detail	string	No	Ordered installation steps.
usage.steps	string[]	No	Ordered usage flow.
metadata	object	No	author, source, exported_at. Set automatically by SkillVault.

Validation rules

The file must parse as JSON or YAML and carry the aiskill/v1 envelope.
Every {{placeholder}} used in prompts.user_template SHOULD be declared in variables (warning if missing).
prompts.system must be non-empty; keep it under ~8000 characters for cross-platform safety.
The online editor enforces all of this live — a green status bar means the file validates.

YAML conventions

YAML exports use 2-space indentation, double-quoted strings only when necessary, and block scalars (|) for multi-line prompts. Any YAML 1.2 parser round-trips them to identical JSON.

Attribution on Free exports

Free-plan exports add a single _skillvault metadata block. It never touches your prompts and is ignored by every platform. Pro exports are byte-clean.