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.