Documentation
Canonical Skill Spec
The Canonical Skill Spec is a vendor-neutral JSON shape. It describes WHAT the skill does, not HOW to phrase it. When rendered to a specific model, the adapter translates the semantics into that model's preferred format.
Key Fields
| Field | Type | Description |
|---|---|---|
| id | string | kebab-case skill id, e.g. code-reviewer |
| name | string | Display name |
| purpose | string | One-liner of what the skill does |
| persona | string? | Role / persona (optional) |
| whenToUse | string? | Activation condition (used by Claude / Custom GPT routing) |
| steps | string[] | Execution steps, rendered in order |
| inputs | FieldSchema[] | Input fields (name / type / description / required) |
| output | OutputContract | Output contract: format + fields + constraints |
| constraints | string[]? | Hard constraints ("never…", "must…") |
| examples | ShotExample[]? | Few-shot examples; reasoning is auto-stripped for reasoning models |
| tools | ToolSpec[]? | Callable tools / functions |
| knowledge | {title,content}[]? | Long reference material — inlined by Kimi/Gemini, progressively disclosed by Claude |
Example Spec
json
{
"id": "code-reviewer",
"name": "Code Review Assistant",
"purpose": "Review code along multiple dimensions and return a structured report.",
"persona": "A strict but friendly senior engineer.",
"whenToUse": "When the user pastes code and asks for review.",
"steps": [
"Understand the code's intent",
"Find issues across readability / performance / security / maintainability",
"Provide severity and a minimal-diff suggestion for each",
"Give a one-line overall conclusion"
],
"inputs": [
{ "name": "language", "type": "string", "description": "Code language", "required": true },
{ "name": "code", "type": "string", "description": "Code body", "required": true }
],
"constraints": [
"Never rewrite the entire file",
"If code is already good, say so — don't invent issues"
],
"output": {
"format": "json",
"fields": [
{ "name": "issues", "type": "object", "description": "Array: dimension/severity/description/suggestion" },
{ "name": "summary", "type": "string", "description": "One-line conclusion" }
]
}
}TIP
The 'reasoning' field in examples is rendered only for non-reasoning models. Reasoning models (o1 / R1 / QwQ) automatically strip it to avoid interfering with native CoT.
Continue Reading